Creates or modernizes repository skills with clear activation cues, purposeful support files, and practical review loops. USE FOR: creating a new skill, tightening an existing skill, improving discovery wording, and structuring references/assets/optional helper agents when they genuinely add value.

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 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 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. 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 6 — 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 7 — 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 3 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 8 — 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 Installed copy provenance check before editing an existing skill 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 revie

fusion-skill-authoring