Fusion Skill Authoring

Create or Modernize Skills

When to use

Use this skill when you need to create a new skill under skills/, or when an existing skill needs a material authoring refresh instead of a small copy edit.

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 for agents to discover and follow"
• "Set up references/assets/helper agents for a skill"

Implicit triggers:

• A recurring task keeps requiring the same instructions, context, or safety boundaries
• An existing skill is valid but too vague, too long, poorly routed, or missing structure
• The user wants a reusable workflow package rather than a one-off prompt

When not to use

Do not use this skill for:

• Editing product or application code outside skills/
• Tiny typo-only skill edits that do not need authoring workflow help
• Requests better solved as docs, templates, or scripts without creating an installable skill
• Large unrelated repository 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, an update to an existing skill, or not a skill at all
• Target repository path and intended final skill directory
• Base skill name in kebab-case before any prefix or namespace
• Final skill name in kebab-case; default to custom-<base-skill-name> unless the target repository has a different naming convention
• One-sentence purpose for the skill and the user outcome it should unlock
• Concrete activation cues: trigger phrases, domain keywords, and anti-triggers
• Expected output: which files, commands, or decisions the skill should produce
• Safety boundaries and approval requirements

Conditional

Collect when relevant:

• Naming prefix, namespace, or catalog convention if the target repository uses one
• Skill category: capability uplift or workflow / encoded preference
• Composition: standalone, orchestrator, or subordinate
• Repository-specific ownership, lifecycle, or release policy if the target catalog enforces one
• Orchestrator relationship: metadata.orchestrator for subordinates, metadata.skills for orchestrators
• Target status (active, experimental, deprecated, archived) when the target catalog tracks lifecycle state
• compatibility text when the skill has real environment constraints
• MCP requirements (metadata.mcp.required / metadata.mcp.suggested) when the skill depends on specific servers
• Whether a small agents/ helper set would sharpen scoping, review, or trigger tuning
• Whether deterministic automation justifies a scripts/ directory

Optional

Capture if useful:

• metadata.sponsor as backup accountability if the target catalog uses backup ownership
• 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 current coverage first:

• Inspect the existing skill catalog first, using repository tooling, directory layout, or catalog docs already available in the target environment
• If an existing skill already covers the request, recommend reuse or update instead of creating a duplicate
• If a skill almost matches, recommend improving that skill or opening an issue rather than creating a one-off clone

2. Stop and do not scaffold a new skill 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 requests as the acceptance criteria for the final skill. If you cannot define realistic requests, the scope is probably underspecified or not reusable enough to become a skill.

Step 3 — Classify the skill and choose the smallest valid structure

Decide the skill type up front:

• capability uplift: packages domain knowledge, tools, or reference material the agent does not already have
• workflow / encoded preference: packages sequencing, review gates, style rules, or mutation order the user wants repeated consistently

Decide the composition model:

• standalone: no coordinating skill required
• orchestrator: routes to companion skills and owns shared gates
• subordinate: runs only under its orchestrator and should document that dependency clearly

Choose the minimum folder structure that supports the task:

• SKILL.md always
• references/ for long guidance, examples, tables, or platform-specific details
• assets/ for templates, checklists, sample outputs, and static files
• agents/ for a small number of specialized helper roles when the runtime supports skill-local agents and a second pass materially improves scoping, review, or trigger quality
• scripts/ only when deterministic automation materially improves safety or reliability

Keep references one level deep from SKILL.md. Do not create nested reference 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

Prefer concise, specific instructions over background explanation. Assume the agent is already capable and only add context it would not reliably infer.

Set the degree of freedom intentionally:

• high freedom for context-dependent analysis or review work
• medium freedom when a preferred pattern exists but adaptation is expected
• low freedom when the workflow is fragile, safety-critical, or sequence-sensitive

Include at least one concrete example in SKILL.md or link directly to one in references/.

Step 5 — Add supporting files only when they reduce ambiguity

Move long or specialized content out of SKILL.md when it improves clarity:

• use references/ for deep guidance, large examples, API/platform notes, or long checklists
• use assets/ for templates and reusable artifacts the skill should point at directly
• use agents/ for a small helper set when the runtime supports skill-local agents or subagents and the workflow benefits from a scoped second opinion
• use scripts/ only 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 such as download-and-run.

If the runtime ignores bundled helper agents, follow the same roles inline instead of skipping the evaluation step.

If the skill depends on MCP, declare the requirement in metadata.mcp and document client-specific tool naming expectations in the skill content instead of assuming all runtimes behave the same way.

Step 6 — Validate discovery, structure, and local policy

Run the validation supported by the target environment after authoring changes:

• inventory or schema validation for the skill catalog, if available
• repository or catalog policy checks for naming, ownership, lifecycle, or composition metadata
• script, GraphQL, lint, or test validation when the skill touches those surfaces

If the environment has no dedicated skill tooling:

• read SKILL.md and every directly referenced file end-to-end
• verify that each representative request would trigger the skill for the right reason
• verify that every referenced file path and workflow assumption still makes sense in the target repository

Use the representative requests from Step 2 to review the final result:

• Does the description trigger on the right requests and avoid obvious 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, use the bundled role files when they help:

• agents/scoper.md before drafting to decide create vs update vs not-a-skill and to choose the smallest useful structure
• agents/reviewer.md after drafting to review discovery, structure, safety, and validation evidence like a strict maintainer
• agents/trigger-tuner.md when the main risk is weak activation cues or when choosing between two description variants

After the portable package is correct, apply any repository-specific release or versioning rules from repo-local instructions or equivalent catalog policy.

Step 7 — Report what changed and what still needs input

Return the authoring result as an 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

This skill borrows Anthropic skill-creator's pattern of bundling a small agents/ helper set, but narrows the roles to Fusion-specific scoping, review, and trigger tuning.

• agents/scoper.md — decide whether the request should become a new skill, an update, or not a skill at all; choose the smallest folder structure that still solves the problem
• agents/reviewer.md — review a drafted skill package against discovery, structure, safety, and validation expectations
• agents/trigger-tuner.md — sharpen description wording and compare activation-cue variants against realistic prompts

If a runtime offers no subagents, keep the same review loop inline and do not skip the agent-shaped reasoning just because the packaging is ignored.

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, and standalone/orchestrator/subordinate when relevant
• Final activation cues and anti-triggers used in the description
• Chosen folder structure and rationale
• At least three representative requests used as acceptance criteria
• Which optional helper agents were used, if any
• Validation commands run, pass/fail status, and interpretation
• Any repository-specific overlays applied after the portable draft
• Any follow-up actions, unresolved questions, or recommended issue links

For a newly scaffolded skill, the default structure should be:

If no repository overlay says otherwise, default <final-skill-name> to custom-<base-skill-name>.

skills/<final-skill-name>/
├── SKILL.md
├── references/
└── assets/

Optional extras when they are justified:

skills/<final-skill-name>/
├── agents/
└── scripts/

Use this baseline for generated SKILL.md files:

---
name: <final-skill-name>
description: '<what it does>. USE FOR: <trigger phrases>. DO NOT USE FOR: <anti-triggers>.'
license: MIT
compatibility: <optional: real environment requirements only>
metadata:
   version: "0.0.0"
   tags:
      - <tag>
---

# <Skill Title>

## When to use

## When not to use

## Required inputs

## Instructions

## Examples

## Expected output

## Safety & constraints

Add repository- or runtime-specific fields such as owner, status, composition metadata, or mcp only when they reflect real catalog or tool requirements.

Validation

Success signals:

- the skill is discoverable in the target catalog or inventory view
- the target environment's validation commands pass
- direct references resolve without depending on files outside the installed skill package
- representative requests trigger the right behavior and avoid obvious false positives

Common failure signals:

• name does not match the folder name or violates naming rules
• description is too vague, missing use cues, or contains invalid markup
• repository- or catalog-required metadata is missing or inconsistent
• the skill still depends on repo-local docs, sibling skills, or hidden conventions that will not ship with the installed package
• references or structure are inconsistent with the declared role / MCP needs

If validation fails:

• fix the reported metadata or structure error,
• re-run the failed command,
• report the final status instead of stopping at the first failure.

Skill Readiness Checklist

Use assets/skill-readiness-checklist.md as the final-quality checklist for skill changes. 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 patterns, or unsafe script guidance

Always:

• Keep SKILL.md concise and 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 and ensure the core workflow still works when the runtime does not invoke them
• Respect the target catalog's naming, ownership, lifecycle, and release policy instead of hard-coding one repository's defaults

Skill Reviewer

Role

Use this helper agent after drafting or revising a skill. Review it like a strict maintainer: the goal is to catch weak discovery wording, structural drift, unnecessary complexity, and missing validation evidence before the skill ships.

Inputs

You may receive these parameters in your prompt:

• skill_path: path to the skill directory being reviewed
• representative_requests: realistic prompts the skill should handle well
• validation_summary: optional command results or notes about what was validated
• output_path: where to save the review notes

Process

Step 1: Read the real skill surface

1. Read SKILL.md completely. 2. Read the directly referenced files that materially affect behavior. 3. Inspect any optional agents/ or scripts/ folders and ask whether they are doing real work or just adding bulk.

Step 2: Review the discovery contract

Check:

• name
• description
• trigger phrases and anti-triggers
• When to use and When not to use

Fail closed on vague discovery wording. If the description says what the skill does but not when it should trigger, call that out plainly.

Step 3: Review structure and guidance quality

Check whether the skill:

• keeps SKILL.md lean,
• uses direct references instead of deep chains,
• explains outputs and safety clearly,
• keeps examples concrete,
• justifies optional support folders.

Step 4: Test it against representative requests

For each representative request:

1. Decide whether the description is likely to trigger. 2. Decide whether the skill content would lead to the intended behavior. 3. Note any gap, ambiguity, or safety risk.

Step 5: Check validation evidence

If validation evidence is provided:

1. Note which commands ran. 2. Flag missing or partial evidence. 3. Never treat an unrun validation step as a pass.

When reviewing a governed catalog, expect evidence for the checks that repository instructions or catalog docs actually require, such as:

• inventory or schema validation for the skill catalog,
• ownership or lifecycle validation when the catalog enforces it,
• script, GraphQL, lint, or test checks when the changed files touch those surfaces.

If the target repository documents specific commands, cite those exact commands in your review. If it does not, describe the missing validation by category instead of inventing local command names.

Step 6: Return findings first

Return:

• findings ordered by severity,
• notable strengths,
• a simple verdict: ready, revise, or rethink,
• the smallest next revision set.

Guidelines

• Findings come first; praise is secondary.
• Prefer specific evidence over generic critique.
• Treat unjustified agents/ or scripts/ as a smell.
• Do not assume validation passed without evidence.

Skill Scoper

Role

Use this helper agent before drafting or restructuring a skill. Its job is to decide whether the request should become a new skill, an update to an existing skill, or not a skill at all, then recommend the smallest structure that still solves the problem.

Inputs

You may receive these parameters in your prompt:

• user_request_summary: concise description of what the user wants
• repository_root: repository or workspace path
• target_skill_path: existing skill path, if this is an update
• inventory_output: result of listing available skills, if already captured
• representative_requests: realistic prompts the skill should handle
• output_path: where to save the scoping notes

Process

Step 1: Decide whether this is skill-worthy

Work through these outcomes in order:

• update-existing-skill
• create-new-skill
• not-a-skill

Prefer reuse over duplication. If an existing skill is close, recommend updating it instead of spinning up a parallel skill.

For governed catalogs, check the active lane plus any documented reserved lanes before recommending a new directory. Use repository instructions or catalog docs to discover those lanes instead of assuming a specific folder layout.

Step 2: Choose the shape of the skill

Recommend:

• skill type: capability or workflow
• composition: standalone, orchestrator, or subordinate
• support files that are actually justified: references/, assets/, optional agents/, optional scripts/

Do not recommend extra folders just because the pattern exists elsewhere.

Step 3: Surface the missing inputs

List the smallest set of unanswered questions needed to draft the skill well:

• trigger phrases and anti-triggers
• expected outputs
• safety boundaries
• runtime constraints

Step 4: Return a drafting plan

Return a concise decision memo with:

• decision
• why that decision is correct
• closest reuse candidates
• recommended structure
• open questions
• first drafting priorities

Guidelines

• Keep the result concrete and decision-oriented.
• Favor the smallest useful skill.
• Treat optional agents/ and scripts/ as earned complexity.
• Do not invent repository capabilities that were not observed.

Trigger Tuner

Role

Use this helper agent when a skill basically works but its description and activation cues are too weak, too broad, or too keyword-stuffed. The goal is to improve triggering accuracy without turning the description into spam.

Inputs

You may receive these parameters in your prompt:

• skill_path: path to the skill being tuned
• current_description: current frontmatter description, if already extracted
• alternate_description: optional candidate variant to compare
• representative_requests: prompts that should trigger the skill
• near_miss_requests: prompts that should not trigger the skill
• output_path: where to save the tuning notes

Process

Step 1: Read the current discovery surface

Read:

• the frontmatter description,
• When to use,
• When not to use,
• one or two examples if they materially affect routing.

Step 2: Stress the trigger boundaries

Use the supplied prompts, or derive realistic prompts if none are supplied:

• requests that clearly should trigger,
• near-miss requests that are adjacent but should not trigger,
• ambiguous requests where routing is easy to get wrong.

Step 3: Tune for specificity, not keyword soup

Improve the description so it:

• states what the skill does,
• names when it should trigger,
• includes anti-triggers,
• stays readable in natural language,
• avoids mechanical keyword stuffing.

If two descriptions are being compared, choose the better one and explain why.

Step 4: Return the improved discovery package

Return:

• the recommended description,
• why it is better,
• a short list of should-trigger prompts,
• a short list of should-not-trigger prompts,
• any remaining routing risks.

Guidelines

• Prefer realistic prompts over abstract test phrases.
• Keep descriptions in third person.
• Optimize for correct triggering, not maximal triggering.
• If both variants are weak, say so and explain the gap.

Follow-up questions

Use these when required inputs are missing or ambiguous while creating a new skill or materially modernizing an existing one.

1. Decide whether this should be a skill

• Is this a net-new skill, an update to an existing skill, or better handled as docs, templates, or scripts without adding a skill?
• What recurring workflow, domain knowledge, or repeated preference would the skill capture?
• What would be lost if this stayed as a one-off prompt instead of a reusable skill?

2. Name and placement

• What is the base skill name in kebab-case (without the default custom- prefix)?
• Does this repository use a naming prefix, namespace, or catalog convention that should override the default custom-<base-skill-name> naming?
• What is the final skill name after applying any local naming convention or the default custom- prefix?
• Where should it live in this repository's skill or catalog layout?
• If this is an update, which existing skill directory is the source of truth?

3. Skill type and composition

• Is this a capability skill or a workflow / encoded-preference skill?
• Should it be standalone, an orchestrator, or a subordinate?
• If subordinate, which orchestrator should invoke it?
• If orchestrator, which companion skills or responsibilities should it coordinate?

4. Discovery cues

• What exact phrases should activate this skill?
• Which nouns, file types, repository terms, or task keywords should appear in the description?
• What should explicitly not trigger this skill?
• What would a false positive look like for this skill?

5. Outputs and structure

• Which files should be created or updated by default (SKILL.md, references/, assets/, optional agents/, optional scripts/)?
• What should stay in SKILL.md, and what should move to references/ or assets/?
• Do you want examples inline in SKILL.md or stored in references/?
• Would a small helper-agent set improve scoping, review, or trigger tuning, or would that be overkill?
• Does deterministic automation justify a scripts/ directory, or is documentation enough?

6. Runtime and compatibility

• Which tools or MCP servers are required versus merely suggested?
• Are there network, package, runtime, or product-surface constraints that belong in compatibility?
• Should the skill document client-specific tool naming or execution expectations?
• Does this repository enforce ownership, lifecycle, release, or validation rules that should stay in repo-local instructions instead of the shipped skill package?

7. Safety and approvals

• Which actions must never happen automatically?
• Which commands or mutations require explicit user confirmation before execution?
• Are there privacy, compliance, or operational constraints beyond the default guardrails?

8. Evaluation scenarios

• Give three representative user requests this skill must handle well.
• For each scenario, what should the agent produce or decide?
• What common mistake, omission, or unsafe behavior should the skill prevent?

9. Answer quality signals

Good answers are:

• specific enough to write a concrete description,
• explicit about anti-triggers and safety,
• realistic about required tools and runtime assumptions.

Red flags:

• vague names such as helper or utils,
• descriptions that say only what the skill does but not when to use it,
• adding agents/ with no clear scoping, review, or tuning job,
• adding scripts/ with no deterministic need,
• no realistic evaluation scenarios.

Skill Readiness Checklist

Use this checklist before considering a new or updated skill ready to ship.

Must pass

• [ ] Frontmatter includes name and description; optional fields are only added when they carry real meaning
• [ ] name matches the folder name, uses kebab-case, is <= 64 chars, does not start or end with -, and does not contain consecutive hyphens
• [ ] name does not include reserved words (anthropic, claude) and contains no XML tags
• [ ] description is non-empty, <= 1024 chars, written in third person, contains no XML tags, and includes concrete USE FOR and DO NOT USE FOR cues
• [ ] SKILL.md includes: When to use, When not to use, Required inputs, Instructions, Expected output, and Safety & constraints
• [ ] SKILL.md includes at least one concrete example or links directly to one in references/
• [ ] Existing skills were checked first when working in a shared catalog, and almost-matches are handled via reuse/update instead of duplication
• [ ] Long guidance is moved to references/, and all referenced files are one level deep from SKILL.md
• [ ] Any bundled agents/ files have a clear job in the workflow, stay narrowly scoped, and are not present by default out of habit
• [ ] Optional metadata such as tags, mcp, compatibility, and composition fields reflect real discoverability and runtime needs
• [ ] At least three representative requests were reviewed against the final skill content
• [ ] Validation appropriate to the target environment was run and evidence was recorded
• [ ] Content is scoped to the requested change, contains no secret handling, and introduces no hidden network access or remote-code execution patterns

Changelog

0.3.0 - 2026-03-09

minor

• #60 `0e7d702` - Refresh fusion-skill-authoring with clearer discovery cues, decision-gated authoring guidance, and a Fusion-flavored helper-agent layer inspired by Anthropic's skill-creator.

• modernize the main skill around reuse-first, evaluation-first, and progressive-disclosure patterns
• default portable scaffold naming to custom-<name> unless the target repository defines a stronger convention
• strengthen the follow-up questions and skill-readiness checklist for real skill authoring work
• keep the shipped package portable while restoring Fusion-specific overlays for fusion-, reserved skill lanes, and local validation in repo-local instructions
• bundle installable helper agents for scoping, review, and trigger tuning inside the skill package

resolves equinor/fusion-core-tasks#499

0.2.2 - 2026-03-05

patch

• #55 `2d346c8` - Add required ownership metadata (metadata.owner, metadata.status) to all skills. Owner is set to @equinor/fusion-core (repository default) and status is set according to skill lifecycle (active for production skills, experimental for early-stage skills). Sponsor metadata was considered but is not required for MVP.

resolves equinor/fusion-core-tasks#474

0.2.1 - 2026-02-20

patch

• #23 `14b9c99` - Migrate issue authoring guidance from helper scripts to GitHub MCP-first workflows, including MCP metadata declarations and updated orchestration/ref docs.

resolves equinor/fusion-skills#21

0.2.0 - 2026-02-20

minor

• #10 `d473723` - Adds structured frontmatter metadata for discoverability and clarifies skill relationship semantics.

Scope delivered:

• Added metadata.tags to affected skills for discoverability.
• Renamed relationship keys to a clearer schema: skill_role → role, required_skill → orchestrator, sub_skills → skills.
• Updated dependent role value from subskill to subordinate to explicitly indicate orchestrator dependency.
• Updated skill authoring guidance to document metadata.role, metadata.orchestrator, metadata.skills, and metadata.tags.

• #7 `2194e7a` - Updates skill authoring defaults and metadata constraints to support complex repository-internal skill relationships.

Scope delivered:

• Permitted YAML arrays in frontmatter metadata specifically for modeling skill relationships (e.g., metadata.sub_skills or metadata.required_skill).
• Updated documentation and checklists to reflect the new versioning and metadata standards.

0.1.1 - 2026-02-20

patch

• #4 `7dad576` - Fix wording in the skill changelog and align metadata/versioning consistency for the updated skill package.

0.1.0 - 2026-02-19

minor

• #2 `57d6f8b` - New authoring skill to standardize how skills are created and reduce inconsistency.

The skill guides contributors to reuse existing skills when possible, collect required inputs, scaffold the skill structure, and run validation/checklist steps.

Skill authoring platform references

Contents

• Core skill-design principles
• Patterns worth borrowing
• Repository overlay pattern
• Reusable pattern examples
• Source links

Core skill-design principles

Across the current skill ecosystem, the baseline is stable:

• every skill directory needs a SKILL.md entry point,
• name and description are the primary discovery contract,
• the description should say both what the skill does and when to use it,
• SKILL.md should stay concise and point to deeper material only when needed,
• references/, assets/, and optional scripts/ are the standard supporting folders,
• validation should happen after authoring instead of assuming the metadata is correct.

The Agent Skills specification adds a few naming details worth enforcing even when local tooling is looser:

• name should match the parent directory,
• avoid leading or trailing hyphens,
• avoid consecutive hyphens,
• keep file references one level deep from SKILL.md.

Patterns worth borrowing

1. Discovery lives in the description

The description is the most important routing signal because it is pre-loaded before the rest of the skill. Good descriptions:

• are written in third person,
• include concrete task nouns and trigger phrases,
• say both what the skill does and when it should trigger,
• make false positives less likely by naming anti-triggers.

A practical pattern is to keep USE FOR: and DO NOT USE FOR: inline in the description.

2. Keep the main skill lean

Use progressive disclosure: keep SKILL.md focused on activation, workflow, and guardrails, then move heavy material to direct references.

Practical application:

• keep the main body under roughly 500 lines,
• move long examples, checklists, or platform notes into references/,
• keep every supporting file directly linked from SKILL.md,
• add a table of contents to long reference files.

3. Match the degree of freedom to the task

Not every skill needs the same level of specificity.

• High freedom: context-dependent analysis or review work
• Medium freedom: preferred patterns with room for adaptation
• Low freedom: fragile or safety-critical command sequences

When a workflow is risky, use explicit sequence rules and validation loops. When the task is contextual, avoid over-specifying the obvious.

4. Build around representative requests before polishing prose

The practical version is simple:

• define at least three representative scenarios,
• write the minimal guidance needed to pass those scenarios,
• validate the final skill against those scenarios,
• iterate when the skill still triggers poorly or misses key guardrails.

This keeps authoring grounded in real behavior instead of imagined completeness.

When a catalog has no stronger naming convention, a neutral fallback like custom-<base-skill-name> is safer than assuming repository-owned prefixes.

5. Prefer deterministic helpers over repeated improvisation

If the workflow needs exact validation, transformation, or extraction, a script can be better than asking the agent to regenerate logic every time. Only add scripts/ when it materially improves reliability, and always make dependencies, side effects, and validation explicit.

6. Make runtime assumptions explicit

Runtime differences matter. For portable skills, the practical pattern is:

• document tool or network requirements in compatibility only when necessary,
• declare server requirements in metadata.mcp only when the runtime actually depends on them,
• document client-specific tool naming or execution expectations in the skill content instead of assuming every runtime behaves the same way.

7. Bundle helper roles when the target runtime supports them

Anthropic's skill-creator uses a small agents/ layer for specialized second-pass work. That pattern is worth keeping in Fusion-flavored skill authoring when the target runtime supports skill-local agents or subagents.

• keep the core workflow in SKILL.md and direct references so the skill still works even if the runtime ignores agents/,
• use agents/ for narrow specialist roles rather than cloning the whole skill into multiple files,
• let repository-local custom agents complement the shipped helper agents instead of replacing the main skill contract.

Keep the helper set small and purposeful. Good jobs for bundled agents are:

• scope and reuse decisions,
• critical review of a draft,
• trigger and anti-trigger tuning.

They should complement SKILL.md, not replace it.

For this repository, a good Fusion-flavored adaptation is to keep helper agents focused on scoping, maintainer review, and trigger tuning rather than shipping a broad generic agent suite.

Repository overlay pattern

Portable skill guidance and repository governance should be layered, not mixed.

Keep in the shipped skill package:

• the reusable authoring workflow,
• neutral naming defaults such as custom-<base-skill-name> when no stronger local convention exists,
• portability-safe examples and helper-agent roles that ship with the skill when the runtime supports them,
• validation expectations stated generically enough to work outside one repository.

Keep in repo-local instructions or catalog docs:

• repository-owned prefixes such as fusion-,
• placement conventions such as skills/.experimental/ or skills/.curated/,
• required ownership, lifecycle, and composition metadata,
• repository validation commands and release policy,
• local examples that depend on sibling skills or workspace-only structure.

If you are authoring inside a governed repository, draft the portable skill first, then layer in the local policy as an overlay. A simple portability test is useful: if someone copied only the skill directory into another repository, would the guidance still make sense?

Reusable pattern examples

Orchestrator pattern

Use this when one skill coordinates a narrow set of subskills or repeated decision gates.

Patterns worth copying:

• explicit routing into subordinate responsibilities,
• shared safety gates owned by the orchestrator,
• clear hand-off boundaries between orchestration and specialist work,
• draft-first mutation flow when the workflow can make external changes.

Narrow specialist pattern

Use this when one job deserves its own narrow skill surface.

Patterns worth copying:

• one responsibility per skill,
• strong anti-triggers,
• status-oriented expected output that makes hand-off obvious.

Self-review pattern

Use this when authoring quality depends on a deliberate second pass.

Patterns worth copying:

• findings-first review,
• explicit validation evidence,
• helper agents justified by a real scoping, review, or tuning job.

Source links

• Agent skills overview:
• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Agent skills best practices:
• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Agent Skills specification:
• https://agentskills.io/specification
• Gemini CLI creating skills:
• https://geminicli.com/docs/cli/creating-skills/
• GitHub Copilot create skills:
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills