docs(skill-builder): make authoring guidance more portable

[bntvllnt]

Summary

• make skill-builder more portable across agent products and harnesses
• align the guidance more tightly with the Agent Skills spec and description-driven discovery
• upgrade validation from checklist-only guidance to evidence-backed spec, trigger, and output validation

What changed

• add explicit operation selection rules for CREATE, UPDATE, ADD, RENAME, DELETE, and VALIDATE
• make description the primary discovery surface instead of implying a custom top-level triggers field
• make README.md, references/, scripts/, assets/, and allowed-tools optional rather than default-required
• replace tool-name guidance with capability-based least-privilege guidance
• add a reusable confirmation boundary and explicit output contracts for the documented mutate/rename/delete flows
• expand references/validation.md to cover spec validation, trigger evals, output evals, and validation report structure

Validation

• parsed skill-builder/SKILL.md frontmatter with yaml.safe_load
• ran git diff --check
• manually checked the updated guidance against the Agent Skills spec and description optimization docs

[bntvllnt]

Final review handoff — current head a04713a

Status

• Blocking issue remains.
• Because the authenticated reviewer is also the PR author, GitHub formal REQUEST_CHANGES is not available here. I used inline review comments plus this top-level handoff instead.

PR metadata check

• Title/body now match the current diff.
• Normalized in this run: removed the body claim that this PR already adds output contracts for every operation.

PR change summary

• makes skill-builder more portable across agent products and harnesses
• moves discovery guidance toward description-first activation
• loosens default-required file structure assumptions
• strengthens validation guidance around evidence-backed spec/trigger/output checks

What the PR does in product terms

• makes the skill easier to reuse outside one agent runtime
• gives authors clearer validation expectations
• reduces accidental coupling to one harness-specific file layout

Timeline summary

• First automated review pass on this head.
• Metadata was normalized in this run so the handoff matches the actual diff.

What changed across review passes

• No prior Jarvis review existed on this head.
• Current pass tightened the PR body to match the code/docs exactly.

What remains active now

• C1 — skill contract advertises VALIDATE without a dedicated execution/output contract (skill-builder/SKILL.md:31, skill-builder/SKILL.md:220-226).
• W1 — description-first guidance is not fully propagated to neighboring referenced docs (skill-builder/SKILL.md:95-104).

Cleanup performed

• No prior Jarvis artifacts needed cleanup.
• This comment is the single authoritative current handoff summary for this head.

Manual review fast path

1. Check whether VALIDATE now has a dedicated procedure and output contract.
2. Re-scan the adjacent referenced docs for trigger/discovery wording drift.
3. Confirm the body still matches the final landed contract.

Validation

• Ran: git diff --check
• Ran: frontmatter parse check for skill-builder/SKILL.md
• Verified: changed-file coverage complete; metadata now matches the diff.
• Remaining gap: no independent external spec audit beyond the repo context/docs loaded for this pass.