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

• 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

• 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 &#x26; 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