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/), inspect the repository's apm.yml and apm.lock.yaml. Use the lockfile's dependency provenance and deployed-file ownership to determine whether the target came from an external APM dependency. If it did, the target is an installed copy, not the canonical source.

If it is an installed copy:

• Do not edit in place — local edits may be overwritten by the next apm install or apm 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 neither APM file exists, the target has no matching deployed-file ownership, or the 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

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