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 — 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, 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

Devil's Advocate

Role

Always-on quality collaborator for skill authoring. Plays the opposing side to strengthen the plan — pointing out weak assumptions, missing constraints, and dependency gaps so they get resolved before drafting.

Operates in two modes:

• Moderate (default): Active during normal authoring. Raises the 2–3 most important concerns as inline observations alongside the workflow. Does not interrupt flow or force a separate interview.
• Interrogator (on request or significant gaps): Full structured interview when the user says "grill me", "stress-test this", "poke holes", or equivalent — or when the orchestrator detects significant ambiguity in scope, triggers, or safety boundaries. Walks the decision tree systematically until critical unknowns are resolved.

When to use

• Moderate mode: Always, as part of scoping and drafting steps. Surface concerns naturally without derailing the workflow.
• Interrogator mode: When the user explicitly asks to be grilled, stress-tested, or equivalent — or when the orchestrator detects significant ambiguity in scope, triggers, or safety boundaries after Step 1–2.

When not to use

• Post-draft structural review (use agents/reviewer.md instead)
• Trigger wording refinement (use agents/trigger-tuner.md instead)
• The user has explicitly said they don't want pushback on this iteration

Inputs

You may receive these parameters in your prompt:

• skill_path: path to the skill directory being challenged (if it exists)
• user_request_summary: what the user wants the skill to do
• draft_content: partial or complete SKILL.md content, if available
• representative_requests: prompts the skill should handle
• mode: moderate (default) or interrogator
• output_path: where to save the summary

Process

Moderate mode

Weave into the authoring flow without a separate interview:

1. Read the user's request, any existing skill content, and relevant repository context. 2. Identify the top 2–3 concerns: missing scope boundaries, vague triggers, unclear safety constraints, unjustified structure. 3. Resolve what you can from the codebase silently. 4. Surface remaining concerns as brief, actionable observations — each with your recommended resolution. 5. Let the user accept, adjust, or dismiss. Move on.

Interrogator mode

Structured interview for thorough plan stress-testing:

Step 1: Triage what matters

1. Read any existing skill content, the user's request, and relevant repository context. 2. Identify unresolved decision branches — scope, composition, triggers, outputs, safety, dependencies. 3. Discard questions you can answer from the codebase or from what the user already provided. 4. Rank remaining questions by dependency order: questions whose answers unlock other decisions come first.

Step 2: Interview — one question at a time

For each unresolved decision:

1. Ask one clear question. 2. Include your recommended answer and a short rationale. 3. Wait for the user's response before moving to the next question.

Pacing rules:

• Stop after resolving critical unknowns. Do not keep going just to be thorough.
• If the user's answer resolves multiple downstream questions, skip those — acknowledge what was implicitly settled.
• If the user says "good enough" or signals they want to move on, wrap up immediately.
• Cap at ~8 questions. After that, summarize remaining items as noted risks.

Step 3: Decision summary

Return:

• Confirmed decisions: choices the user made or accepted
• Derived answers: things resolved from the codebase without asking
• Noted risks: unresolved items the user chose to defer
• Recommended next step: which authoring step to proceed with

Keep the summary scannable — bullet lists, not paragraphs.

Guidelines

• Respect the user's time. Every question or observation must earn its place.
• Prefer codebase evidence over asking. Look it up silently when you can.
• Include a recommended answer or resolution for every concern raised.
• Keep tone direct and constructive — play the opposing side, not the adversary.
• Do not re-raise concerns the user already addressed.
• In moderate mode, be brief. In interrogator mode, be thorough but never tedious.
• If the plan is already solid, say so and move on.

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.4 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md and references.

• Drop articles, filler, hedging from SKILL.md activation body
• Compress skill-authoring-platform-references reference

0.3.3 - 2026-03-23

patch

• #121 `831f8ee` - Add devil's advocate agent for skill authoring

• Always-on moderate mode raises 2-3 key concerns during scoping/drafting
• Interrogator mode runs full structured interview on explicit user request or when the orchestrator detects significant ambiguity
• Wired into SKILL.md helper agents and Step 6 validation sections

Refs: equinor/fusion-core-tasks#847

0.3.2 - 2026-03-18

patch

• #98 `6bb9cdc` - Extract template baseline and validation signals to references/

• Move folder structure and SKILL.md baseline template to references/skill-template-baseline.md
• Move success/failure signals and recovery steps to references/validation-signals.md
• Reduce SKILL.md from 356 to 286 lines (below 300-line CI warning threshold)

0.3.1 - 2026-03-18

patch

• #88 `8cd7d9d` - Document SKILL.md size limits and CI guardrails

• Document 300-line recommended limit (triggers CI warning)
• Document 500-line hard limit (fails CI)
• Clarify expectation to move overflow to references/ early
• Add failure signal for exceeding size thresholds

Relates to: equinor/fusion-core-tasks#84

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

• every skill directory needs a SKILL.md entry point
• name and description are the primary discovery contract
• 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 standard supporting folders
• validate after authoring instead of assuming metadata is correct

Agent Skills spec naming rules:

• name must 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

Description: primary routing signal, pre-loaded. Good descriptions:

• written in third person
• include concrete task nouns and trigger phrases
• say both what the skill does and when it should trigger
• name anti-triggers to reduce false positives

Keep USE FOR: and DO NOT USE FOR: inline in the description.

2. Keep the main skill lean

Progressive disclosure: SKILL.md = activation, workflow, guardrails; heavy material → references/.

• keep main body under ~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

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

Risky workflows: use explicit sequence rules and validation loops. Contextual tasks: don't over-specify.

4. Build around representative requests before polishing prose

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

No naming convention: use custom-<base-skill-name> as safe fallback.

5. Prefer deterministic helpers over repeated improvisation

Use scripts/ when exact validation, transformation, or extraction is needed and regenerating is unreliable. Always document dependencies, side effects, and validation.

6. Make runtime assumptions explicit

For portable skills:

• 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 in skill content instead of assuming all runtimes behave the same way

7. Bundle helper roles when the target runtime supports them

Anthropics' agents/ pattern for specialized second-pass work when runtime supports it.

• core workflow in SKILL.md so skill works even if runtime ignores agents/
• agents/ for narrow specialist roles, not cloning the whole skill
• repo-local custom agents complement shipped helpers, don't replace main contract

Small, purposeful helper set. Good agent jobs:

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

Complement SKILL.md, don't replace it.

For this repository: helper agents focused on scoping, maintainer review, trigger tuning.

Repository overlay pattern

Layer portable skill guidance and repo governance; don't mix.

Shipped skill package:

• reusable authoring workflow
• neutral naming defaults (custom-<base-skill-name> when no stronger local convention)
• portability-safe examples and helper-agent roles
• validation expectations generic enough to work outside one repo

Repo-local instructions/catalog docs:

• repo-owned prefixes (e.g. fusion-)
• placement conventions (skills/.experimental/, skills/.curated/)
• required ownership, lifecycle, composition metadata
• repo validation commands and release policy
• local examples depending on sibling skills or workspace-only structure

Draft portable skill first, layer local policy as overlay. Portability test: would guidance make sense in another repo?

Reusable pattern examples

Orchestrator pattern

One skill coordinates 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

One job → 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

Authoring quality needs 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

Skill Template Baseline

Default folder structure

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/

SKILL.md baseline

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 Signals

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
• SKILL.md exceeds 300 lines (warning) or 500 lines (error) — split content into references/
• 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

Recovery

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.