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 — 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

1. 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 2 — 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 3 — 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 4 — 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 5 — 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 6 — 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 2 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 7 — 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

• 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

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