fusion-skill-authoring

What this skill does

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