/skill-creator

Skill creator

Turn a repeatable workflow into a compact specialist package, or improve an existing package without erasing its effective domain knowledge. Optimize for correct behavior on real requests rather than conformity to one Markdown template.

Choose the mode

• Create — build a new package from concrete usage examples.
• Improve — diagnose and revise an existing package while preserving working behavior.
• Merge — combine overlapping packages, reconcile triggers and resources, and define migration boundaries.
• Validate — inspect structure, resource routing, triggers, and behavior without changing the package unless asked.

Read the current package, repository conventions, validators, and catalog metadata before asking questions. Ask only for intent that cannot be recovered and would materially alter trigger scope, side effects, or output.

Model real usage

Collect or derive representative prompts:

• direct requests that should trigger;
• common paraphrases and incomplete requests;
• near-miss requests that belong to another skill;
• multi-turn requests where the skill becomes relevant later;
• risky, unavailable, or ambiguous cases that require a branch;
• examples of successful output and known failure modes.

For each positive example, outline the execution path from inputs to verified outcome. Identify decisions that depend on context and operations that should remain deterministic.

Audit an existing package

When improving or merging, inventory:

• frontmatter trigger coverage and collisions;
• user inputs, inferred context, and unnecessary questions;
• decision branches and missing failure paths;
• domain rules versus generic advice;
• output and side-effect contract;
• verification that exercises behavior rather than checking ingredients;
• every reference, script, and asset, including reachability and duplication;
• runtime-specific assumptions and portability constraints.

Preserve concise, evidence-backed instructions and tested resources. Remove false precision, unsupported claims, authorial house style, and formatting rules that do not affect behavior.

For merges, map which package owns each trigger, workflow, resource, and output. Resolve contradictory rules explicitly and state whether old package names need a compatibility or migration path.

Design the resource graph

Keep core selection logic, invariants, workflow, output, and verification in SKILL.md. Move material only when it improves execution:

• references/ for conditional domain knowledge, provider or framework variants, schemas, and extended examples;
• scripts/ for repeated deterministic work, parsing, conversion, or validation that should not be regenerated each run;
• assets/ for templates, fixtures, media, or boilerplate copied into outputs rather than read as instructions.

Link every reference directly from SKILL.md at the decision that requires it and say when to read it. Avoid forcing unrelated references into context. Add a Contents section near the top of reference files longer than 100 lines.

Do not duplicate the same rule in the main file and a reference. Test added scripts by running representative inputs, including failure cases.

Write the trigger

Use the repository's frontmatter contract. The description must state both capability and trigger context in concrete language. Include important modes when they affect discovery, but do not turn the description into a workflow summary.

Front-load the distinctive capability and strongest trigger in the opening clause. Runtimes may shorten catalog descriptions as more skills are installed, so do not depend on a qualifier or disambiguating phrase near the end. Keep the whole description concise enough to preserve useful routing detail under pressure.

Check the trigger against:

1. positive examples;
2. paraphrases that omit the skill's preferred nouns;
3. adjacent tasks that should not trigger;
4. broad requests where another skill should remain primary;
5. contexts where this skill is necessary even if not explicitly named.

Avoid vague “helps with” wording and avoid runtime branding unless the workflow truly depends on that runtime.

Write adaptive instructions

Set the degree of freedom from task variability:

• use principles and decision criteria when multiple approaches are valid;
• use parameterized patterns when a preferred approach has meaningful variants;
• use deterministic scripts and strict sequencing for fragile, repeatable operations.

The body should tell the next agent how to inspect context, choose a branch, execute, handle unavailable inputs, produce a bounded output, and verify the result. Do not mandate phase numbering, a heading style, checklist syntax, tone, or arbitrary line target beyond the repository's actual constraints.

Prefer observable rules. Replace “make it polished” with the evidence, behavior, or acceptance check that demonstrates polish in this domain.

Define side effects and output

State whether the skill answers, audits, edits files, runs commands, opens applications, or changes external state. Separate report-only work from mutation and require approval where the underlying action is consequential.

Define the minimum complete output, source/provenance expectations, how blocked facts are represented, and what limitations must be reported. Avoid a single fixed output form when audit, generation, and implementation modes need different artifacts.

Build behavioral evals

Create a small eval set with expected behavior, not only trigger labels:

Prompt:
Expected trigger decision:
Expected mode and context inspection:
Expected questions, if any:
Expected artifact or changes:
Expected verification:
Disallowed behavior:

Cover positive, negative, near-miss, incomplete-input, multi-turn, and failure-recovery cases. For a reconstructed skill, include at least one regression case for each major defect being fixed.

When feasible, forward-test the package in a clean context using raw prompts and artifacts. Do not leak the intended answer or audit diagnosis into the test. Compare observed behavior with the expected contract and revise the package when failures expose a generalizable gap.

Package and validate

1. Keep SKILL.md at the package root and within the repository's line limit.
2. Confirm the directory name and frontmatter name agree.
3. Parse frontmatter using the repository validator.
4. Resolve every relative Markdown link.
5. Confirm references are directly and conditionally routed from SKILL.md.
6. Confirm references longer than 100 lines have a contents section.
7. Run and test deterministic scripts that changed.
8. Run the repository's skill validator on every touched package.
9. Re-run representative behavioral evals after structural changes.

Output contract

Deliver:

• the complete package, including changed resources;
• a concise behavior summary and trigger boundary;
• validation and eval results;
• resources added, removed, or rerouted;
• preserved behavior and intentional breaking changes;
• remaining limitations or untested environments.

Read the authoring guide when selecting a multi-file resource structure, designing eval cases, merging packages, or diagnosing portability and routing failures.

Agent Skill authoring guide

Use this reference when the package needs conditional resources, behavioral evals, merge decisions, or portability diagnosis.

Contents

• Choosing package contents
• Single-file example
• Conditional-reference example
• Behavioral eval design
• Improving an existing skill
• Merging overlapping skills
• Routing and portability failures

Choosing package contents

Keep instructions in SKILL.md when the agent needs them for every invocation: context inspection, branch selection, invariants, side-effect boundaries, output, and verification.

Use a reference when knowledge is needed only for a selected framework, provider, file format, or advanced mode. Route it from the exact decision point.

Use a script when the operation is deterministic, repeated, easy to get subtly wrong, or expensive to regenerate. Scripts need input validation, useful failures, and representative execution tests.

Use an asset when a file is copied, adapted, or rendered rather than read as instructions. Keep placeholders out of finished outputs and document required substitutions in the main workflow.

Single-file example

---
name: release-notes
description: Draft and verify user-facing release notes from a repository change range. Use when preparing a product or library release.
license: MIT
---

# Release notes

Identify the release range and audience from tags, branches, and repository policy. Ask only when the range or release status remains ambiguous.

## Classify changes

Map every user-visible claim to a commit or diff. Include internal work only when it changes compatibility, security, reliability, or operation.

## Output

Produce grouped notes, migration instructions beside breaking changes, and a provenance table.

## Verify

Re-check every claim against the range, run available link checks, and report unverified release facts.

This package does not need a reference because its branches and domain rules fit comfortably in the main file.

Conditional-reference example

deploy-service/
├── SKILL.md
└── references/
    ├── fly.md
    └── railway.md

The main workflow should route, not summarize both providers:

Detect the existing provider from configuration and deployment metadata.

- For Fly.io, read `references/fly.md` before changing provider configuration.
- For Railway, read `references/railway.md` before changing provider configuration.

Read only the selected provider reference. Ask when no provider evidence exists and choosing one would create an external commitment.

Each provider reference owns its commands, configuration, failure modes, secrets handling, deployment verification, and rollback. Do not repeat shared build checks in both references.

The paths above are illustrative package contents, not links in this guide.

Behavioral eval design

A trigger-only list cannot reveal whether the skill asks needless questions, chooses the wrong mode, mutates too much, or verifies only ingredients.

Write expected behavior for each case:

Prompt: Improve our existing deployment skill; it assumes Fly but we moved to Railway.
Trigger: yes
Mode: improve
Inspection: existing SKILL.md, both provider resources, deployment files, validators
Questions: only unresolved migration or compatibility intent
Output: revised trigger and Railway branch; stale Fly behavior removed or scoped
Verification: links resolve, validator passes, Railway eval succeeds, Fly near-miss does not route incorrectly
Disallowed: creating a second overlapping skill without explaining the boundary

Useful eval categories:

• direct positive request;
• paraphrase without the skill name;
• adjacent negative request;
• broad request where another skill should lead;
• incomplete input recoverable from repository evidence;
• missing input that genuinely requires a question;
• unsafe or unavailable operation;
• multi-turn request that changes mode;
• regression case from a prior failure.

Evaluate artifacts and actions, not rhetorical quality alone. A good result may be concise if it made the right decisions and verified them.

Improving an existing skill

Start with observed failure modes and package evidence. Compare:

1. what the trigger promises;
2. what the body can actually do;
3. what references and scripts supply;
4. what the output contract claims;
5. what verification demonstrates.

Common defects include:

• a trigger advertises modes absent from the workflow;
• mandatory questionnaires ignore repository evidence;
• examples harden into universal style rules;
• exact counts and limits lack a domain reason;
• a checklist verifies wording or components but not behavior;
• references are linked without a condition or duplicate the main file;
• implementation snippets contradict the stated invariant;
• the package edits when the user requested only an audit.

Preserve effective specialist knowledge while replacing the mechanism that caused the failure. Re-run a regression eval for each repaired class.

Merging overlapping skills

Build a table of trigger intents, inputs, workflows, resources, outputs, and side effects. Choose a primary package based on the clearest domain boundary, not the preferred name.

Decide for every overlap whether to:

• unify it as shared core behavior;
• keep it as a conditional branch;
• move provider or format depth to a reference;
• retain a separate skill because the user intent or side-effect boundary differs;
• deprecate an old package with an explicit migration path.

Test the merged trigger against prompts that formerly selected each source skill and against adjacent prompts that should still remain outside it.

Routing and portability failures

Check for:

• orphaned resources;
• links that resolve only from the repository root rather than the package file;
• references that point to files shown only as examples;
• nested reference chains that hide necessary instructions;
• runtime-only tool names presented as universal capabilities;
• dependencies on separately installed unpublished skills;
• commands that assume a package manager, shell, or directory without detection;
• assets described as references or references copied as output assets;
• generated metadata that no longer matches the skill.

Fix portability by routing tool use by capability, declaring real compatibility constraints, resolving paths relative to their containing file, and keeping every required resource inside the delivered package.