fusion-skill-authoring

Create or Modernize Skills

When to use

Activate when creating a new skill under skills/, or when an existing skill needs a material authoring refresh.

Typical triggers:

• "Create a skill for ..."
• "Scaffold skills/<name>/SKILL.md"
• "Turn this workflow into a reusable skill"
• "Improve this skill's metadata and activation cues"
• "Make this skill easier to discover"
• "Set up references/assets/helper agents for a skill"

Implicit triggers:

• Recurring task keeps requiring the same instructions or safety boundaries
• Existing skill is too vague, too long, poorly routed, or missing structure
• User wants a reusable workflow package, not a one-off prompt

When not to use

• Editing product or application code outside skills/
• Tiny typo-only edits that don't need authoring workflow help
• Requests better solved as docs, templates, or scripts without an installable skill
• Large unrelated repo refactors
• Destructive commands or hidden network automation

Required inputs

If required inputs are missing, ask concise targeted questions first. Use assets/follow-up-questions.md as the default question bank.

Mandatory

Collect before drafting:

• Whether this is a new skill, update, or not a skill at all
• Target repo path and intended skill directory
• Base skill name in kebab-case before any prefix/namespace
• Final skill name in kebab-case; default to custom-<base-skill-name> unless repo has different convention
• One-sentence purpose and user outcome
• Concrete activation cues: trigger phrases, domain keywords, anti-triggers
• Expected output: files, commands, or decisions the skill produces
• Safety boundaries and approval requirements

Conditional

Collect when relevant:

• Naming prefix, namespace, or catalog convention
• Skill category: capability uplift or workflow/encoded preference
• Composition: standalone, orchestrator, or subordinate
• Repository-specific ownership, lifecycle, or release policy
• Orchestrator relationship: metadata.orchestrator for subordinates, metadata.skills for orchestrators
• Target status (active, experimental, deprecated, archived)
• compatibility text when skill has real environment constraints
• MCP requirements (metadata.mcp.required / metadata.mcp.suggested)
• Whether helper agents in agents/ would sharpen scoping, review, or trigger tuning
• Whether deterministic automation justifies a scripts/ directory

Optional

Capture if useful:

• metadata.sponsor as backup accountability if catalog uses it
• Starter assets, checklists, examples, or templates
• Related issue follow-up if an almost-match exists and should be improved instead of duplicated

Metadata and structure constraints

Validate before writing files:

• name: 1-64 characters, lowercase letters/numbers/hyphens only, must match the folder name, no leading/trailing hyphen, no consecutive hyphens, no XML tags, and no reserved words
• If the target repository has no prefix or namespace convention, default new skills to custom-<base-skill-name>
• description: non-empty, <= 1024 chars, third-person, no XML tags, states both what the skill does and when to use it
  • Prefer a single-quoted YAML string with inline USE FOR: and DO NOT USE FOR: cues
  • Example: description: 'Drafts release notes from validated repository context. USE FOR: release summaries, changelog preparation. DO NOT USE FOR: publishing releases or editing product code.'
• metadata.version: follow the target catalog's starting-version rule; if no local rule exists, "0.0.0" is a safe default for a new skill
• metadata.owner: include only when the target catalog requires explicit ownership; use a stable GitHub identity or equivalent team handle
• metadata.status: include only when the target catalog tracks lifecycle state; if used, keep it to active, experimental, deprecated, or archived
• metadata.tags: keep tags relevant, lowercase, and kebab-case
• metadata: use simple key/value metadata unless a relationship field explicitly needs a list or map
• license: optional top-level field
• compatibility: optional top-level field; only include it when the skill has real runtime, network, tool, or product constraints

Repository-specific prefix rules, ownership/lifecycle requirements, release policy, and validation commands belong in repo-local instructions or catalog docs, not in the portable skill package.

Instructions

Step 1 — Check for installed-copy provenance before editing

Before editing an existing SKILL.md (or its references/, assets/, agents/), check skills-lock.json at the repository root. Its skillPath values are relative to the local skills root (e.g. caveman-compress/SKILL.md), not absolute or fully-qualified paths — strip any leading skills-root segment (such as .agents/skills/ or skills/) from the target file's path before comparing. If a stripped entry's skillPath matches the target this way and its source differs from the current repository, the target is an installed copy, not the canonical source.

If it is an installed copy:

• Do not edit in place — local edits are overwritten on the next npx skills update and never reach other consumers.
• Tell the user the file is installed from <source>; changes belong there.
• Offer to switch to <source> and make the change there, or draft a bug/improvement issue against it instead.
• Only edit locally if the user explicitly confirms a one-off override and accepts it won't persist.

If no skills-lock.json exists, or source matches the current repository, proceed normally.

Step 2 — Decide whether this should be a skill at all

1. Check existing catalog first:
   • If an existing skill covers the request, recommend reuse or update instead of a duplicate
   • If a skill almost matches, recommend improving it or opening an issue
2. Don't scaffold if the request is better handled as:
   • plain repository documentation,
   • a template/checklist with no reusable agent behavior,
   • a standalone script with no skill-routing value, or
   • a tiny copy edit to an existing skill

Step 3 — Define representative requests before drafting

Capture at least three representative requests before writing long instructions:

• the user request or trigger phrase,
• the behavior the skill should produce,
• the mistake or gap the skill must prevent.

Use these as acceptance criteria. If you can't define realistic requests, the scope is underspecified or not reusable enough to become a skill.

Step 4 — Classify the skill and choose the smallest valid structure

Decide skill type:

• capability uplift: packages domain knowledge, tools, or reference material
• workflow / encoded preference: packages sequencing, review gates, style rules, or mutation order

Decide composition:

• standalone: no coordinating skill required
• orchestrator: routes to companion skills, owns shared gates
• subordinate: runs only under its orchestrator — document that dependency

Choose minimum folder structure:

• SKILL.md always
• references/ for long guidance, examples, tables, or platform-specific details
• assets/ for templates, checklists, sample outputs, and static files
• agents/ for specialized helper roles when runtime supports skill-local agents
• scripts/ only when deterministic automation materially improves safety or reliability

Keep references one level deep. Don't create nested chains that force partial reads.

Step 5 — Draft the minimum viable SKILL.md

Write the smallest useful main document first:

• concise frontmatter with strong discovery cues
• When to use and When not to use
• Required inputs
• Instructions
• Expected output
• Safety & constraints

Keep under 300 lines. Different runtimes have different context limits — files over 300 lines risk degradation on smaller runtimes and trigger CI warnings. Files over 500 lines fail CI. Move overflow to references/ early.

Prefer concise, specific instructions over background explanation. Assume the agent is capable; only add context it won't reliably infer.

Set degree of freedom intentionally:

• high freedom for context-dependent analysis or review
• medium freedom when a preferred pattern exists but adaptation is expected
• low freedom when workflow is fragile, safety-critical, or sequence-sensitive

Include at least one concrete example in SKILL.md or link to one in references/.

Step 6 — Add supporting files only when they reduce ambiguity

Move long or specialized content out of SKILL.md:

• references/ for deep guidance, large examples, API/platform notes, or long checklists
• assets/ for templates and reusable artifacts
• agents/ for helper set when runtime supports skill-local agents and workflow benefits from scoped second opinion
• scripts/ for deterministic operations that should be executed instead of regenerated

If you add scripts:

• document dependencies and side effects,
• validate inputs and fail with actionable errors,
• keep network access explicit and justified,
• never use remote-code execution patterns.

If runtime ignores bundled helper agents, follow the same roles inline.

If skill depends on MCP, declare in metadata.mcp and document client-specific tool naming in skill content.

Step 7 — Validate discovery, structure, and local policy

Run validation supported by the target environment after authoring changes:

• inventory or schema validation for the skill catalog, if available
• repo or catalog policy checks for naming, ownership, lifecycle, or composition metadata
• script, GraphQL, lint, or test validation when skill touches those surfaces

If no dedicated skill tooling:

• read SKILL.md and every directly referenced file end-to-end
• verify each representative request would trigger the skill correctly
• verify every referenced file path and workflow assumption is valid

Use representative requests from Step 3 to review:

• Does the description trigger on the right requests and avoid false positives?
• Can the agent locate all directly referenced files without chasing nested links?
• Are outputs, approval gates, and safety constraints explicit?

If subagents are available:

• agents/scoper.md before drafting to decide create vs update vs not-a-skill
• agents/devils-advocate.md during scoping and drafting to surface key concerns, or full structured interview when user asks to be grilled or significant ambiguity detected
• agents/reviewer.md after drafting to review discovery, structure, safety, and validation evidence
• agents/trigger-tuner.md when the main risk is weak activation cues

After portable package is correct, apply any repository-specific release or versioning rules.

Step 8 — Report what changed and what still needs input

Return authoring result as explicit contract:

• what was created or updated,
• how the skill was classified,
• which representative requests were used as acceptance criteria,
• which helper agents were used, if any,
• which validation commands ran and what they proved,
• any unresolved questions or recommended follow-up issues.

Core behavior to preserve

• Installed-copy provenance check before editing an existing skill
• Reuse before creation
• Portable first, repository overlays second
• Representative requests before long-form wordsmithing
• Progressive disclosure instead of overloading SKILL.md
• Explicit safety and approval gates for risky actions
• Real validation evidence instead of assumed correctness

Optional helper agents

Borrowed from Anthropic skill-creator pattern but narrowed to Fusion-specific scoping, review, and trigger tuning.

• agents/scoper.md — decide new skill vs update vs not a skill; choose smallest folder structure
• agents/reviewer.md — review drafted skill against discovery, structure, safety, and validation
• agents/trigger-tuner.md — sharpen description wording; compare activation-cue variants
• agents/devils-advocate.md — always-on quality collaborator; moderate mode during authoring, interrogator mode when asked or significant ambiguity detected

If runtime offers no subagents, keep the same review loop inline.

Examples

• User: "Create a skill for drafting incident retrospectives."
  • Result: create a new workflow-oriented skill in the target catalog, define at least three retrospective authoring scenarios, scaffold SKILL.md, and add assets/ only if templates are needed.
• User: "Improve the activation cues and structure of fusion-skill-authoring."
  • Result: update the existing skill, refresh supporting references/assets, and run the target repository's validation flow.
• User: "Add a new CLI flag to the application."
  • Result: do not use this skill because the request is product-code work, not skill authoring.

Expected output

Return:

• Created or updated file paths
• Skill classification: new/update/not-a-skill, capability vs workflow, standalone/orchestrator/subordinate
• Final activation cues and anti-triggers used
• Chosen folder structure and rationale
• At least three representative requests used as acceptance criteria
• Which helper agents were used, if any
• Validation commands run, pass/fail status, and interpretation
• Repository-specific overlays applied after portable draft
• Follow-up actions, unresolved questions, or recommended issue links

See references/skill-template-baseline.md for default folder structure and baseline template.

Validation

See references/validation-signals.md for success signals, failure signals, and recovery steps.

Skill Readiness Checklist

Use assets/skill-readiness-checklist.md as final-quality checklist. Repository-specific PR requirements belong in repository instructions, not in the installable skill asset.

Safety & constraints

Never:

• Request or expose secrets or credentials
• Run destructive commands without explicit user confirmation
• Invent validation results or evaluation evidence
• Modify unrelated files outside the requested scope
• Add hidden network access, remote-code execution, or unsafe script guidance
• Edit a skills-lock.json-tracked installed copy in place without first surfacing its source repo and getting explicit confirmation

Always:

• Keep SKILL.md concise; move overflow to direct references
• Make the discovery contract explicit in the description
• Prefer deterministic validation loops over hand-wavy advice
• Keep helper agents tightly scoped; core workflow still works when runtime doesn't invoke them
• Respect target catalog's naming, ownership, lifecycle, and release policy