fusion-skill-authoring

SKILL.md

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