git:20260909.44d3eef to git:20260924.069589f

39 added, 41 removed. Audit A to A.

---

name: creating-portable-skills

description: Use when creating, updating, or migrating a skill, when editing a skill's SKILL.md, evals, graders, or trigger queries, or when finding problems in its description, triggers, structure, portability, or evidence. Produces prioritized findings or a portable, installable skill package. Explanation-only requests stay with general reasoning.

license: MIT

- compatibility: Requires isolated agent contexts or separate sessions for agent grading and review.

+ compatibility: Full validation requires isolated agent contexts or separate sessions for agent grading and review.

---

# Creating Skills

- Create, revise, migrate, or audit a skill from its intent, required outcome, and only the hard constraints that define acceptable completion or remain under user authority. The result is either a prioritized read-only audit or a self-contained skill package with structural validation, appropriately scoped behavioral evidence, and separate trigger and installation checks.

+ Create, revise, migrate, or audit a skill from its intent, required outcome, and only the hard constraints that define acceptable completion or remain under user authority.

- Skills produced here follow the [Agent Skills format](https://agentskills.io/specification): a directory with a `SKILL.md` (frontmatter plus body) and optional `references/`, `assets/`, and `scripts/`. Canonical frontmatter uses only `name`, `description`, `license`, `compatibility`, and `metadata`. Read [references/portability.md](references/portability.md) when authoring frontmatter, choosing an install location, or making a harness-specific claim.

+ Skills produced here follow the [Agent Skills format](https://agentskills.io/specification): a directory with a `SKILL.md` (frontmatter plus body) and optional `references/`, `assets/`, and `scripts/`. Read [references/portability.md](references/portability.md) for the canonical frontmatter fields and their limits, and when choosing an install location or making a harness-specific claim.

- An independent reviewer must not have participated in the authoring discussion or produced the artifact under review. One independent grader inspects each matched case; a different fresh-context reviewer performs the final package review. If the current environment cannot start those independent contexts, prepare a self-contained handoff for a separate session and keep the affected grade or review unverified until that session completes it. Do not substitute the author's own review.

+ An independent reviewer is any agent that took no part in the authoring discussion and did not produce the artifact under review; an agent auditing a skill it did not write already qualifies and needs no separate context. For full validation, an independent grader grades the matched cases and a different independent reviewer performs the final package review. When a required independent context is unavailable, prepare a self-contained handoff for a separate session; that grade or review stays unverified until the session completes it, because the author's own review never substitutes.

## Workflow

- Creating a new skill starts at step 1. Auditing, updating, or migrating an existing skill starts at step 0. A read-only audit ends at step 0; approved changes continue through the remaining workflow.

+ Select the validation route before entering the workflow:

+ - **Focused validation** applies only to a localized, low-risk guidance revision with unchanged task scope, activation boundary, required outcomes, System-Owned Invariants, executable helpers, and evaluation/review policy. An optional method hint can qualify; a one-line approval or output-schema change cannot.

+ - **Full validation** applies to new skills, all other substantive changes, and ambiguous eligibility. Substantive means changed instruction semantics, trigger description, or bundled resource; typo, formatting, and link-only edits remain exempt from behavioral evaluation.

+ A read-only audit starts and ends at step 0. Authorized focused revisions start at step 1; other existing-skill work starts at step 0, and new skills start at step 1. Existing authorization for the material fix scope carries forward.

### 0. Audit an existing skill

- Have a separate fresh-context agent that has not participated in the current authoring work read the whole package and the host repository's instructions. Give it the skill, the review checklist, and the stated intent without the author's conclusions. Have it apply [references/review-checklist.md](references/review-checklist.md) top to bottom, then present a prioritized fix list where each item names the problem, impact, and change risk.

+ Have an independent reviewer apply [references/review-checklist.md](references/review-checklist.md) to the whole package and the host repository's instructions, with the inputs the checklist names, and present its prioritized fix list.

Read-only completion: deliver the evidence-backed review, prioritized recommendations, and final verdict without changing files. The execution ends there. Revision begins only in a separate user-authorized request.

- Change completion: the user has approved the material fix scope, including any authority or taste decisions that stay with them. Continue at step 1.

+ Change completion: the material fix scope is authorized, including any authority or taste decisions that stay with the user. Continue at step 1 without requesting authorization already supplied.

### 1. Resolve the intent

Use the conversation, existing package, repository context, and examples already available. Ground the reusable guidance in real work: user corrections, successful task history, input and output examples, project documentation, schemas, review comments, issues, version history, and resolved failures. Establish the skill's one job, triggering conditions and near-misses, intended outcome, and observable done state, including any required artifact or handoff. Name only the hard constraints, including decisions that remain with the user; identify real environment requirements and representative examples. When a missing decision could materially change the result, scope, or authority, ask one focused question at a time; do not re-ask what the available context resolves.

- Completion: the job fits one sentence, and the triggers, near-misses, outcome, done state, hard constraints, requirements, and examples are known or explicitly not applicable.

+ Completion: the job is written as one sentence, and the triggers, near-misses, outcome, done state, hard constraints, requirements, and examples are each written down with a value or `not applicable`.

### 2. Scope targets and resources

- Use the caller-declared model and harness target set. When none is declared, use the current model and harness as one target; structural portability alone does not require expanding the set. The declared harnesses scope the step 8 smoke roster; behavioral comparisons run as single matched pairs on the current model rather than iterating declared targets. Record actual target identities and material configuration when available.

+ Use the caller-declared model and harness target set. When none is declared, use the current model and harness as one target; structural portability alone does not require expanding the set. Behavioral comparisons run on the current model and on any other target the caller names. Record actual target identities and material configuration when available.

Choose only resources with repeatable value. Outputs copied by the workflow belong in `assets/`. Reference material needed only for one branch belongs in `references/`. Deterministic helpers belong in `scripts/` when prose cannot reliably protect the result. Keep the package standalone. Check the host repository's contribution docs, agent instructions, changelog policy, skill discovery path, and validators.

Completion: the target set and applicable host conventions are recorded, with a file list and one-line reason for every bundled file.

### 3. Draft

For a new skill, copy [assets/skill-template.md](assets/skill-template.md) to the host's skill discovery path or documented skill location. For a revision, preserve a loadable prior version before editing; the last commit is sufficient in a versioned repository. For a migration, copy the source package to the destination collection and revise the copy without changing the source.

- Use the least-prescriptive instruction that reaches the required outcome within its hard constraints. Read the System-Owned Invariants and candidate qualifier rules in [references/review-checklist.md](references/review-checklist.md) before relaxing an existing instruction. Preserve exact formats, deterministic checks, authority boundaries, reusable resources, and genuinely fragile ordering. Let the agent choose its reasoning and implementation path elsewhere. If the skill names several tools or approaches, give a default or a selection rule instead of an equal menu. Add a concise example only when it resolves a real ambiguity or demonstrates an exact format.

- Before drafting, read the **Information hierarchy** and **Portability** sections of [references/review-checklist.md](references/review-checklist.md) and apply them as authoring constraints.

+ Use the least-prescriptive instruction that reaches the required outcome within its hard constraints. Preserve exact formats, deterministic checks, authority boundaries, reusable resources, and genuinely fragile ordering. Let the agent choose its reasoning and implementation path elsewhere. Before drafting, read the **System-Owned Invariants**, **Information hierarchy**, **Instruction economy**, and **Portability** sections of [references/review-checklist.md](references/review-checklist.md) and apply them as authoring constraints; they also govern relaxing an existing instruction.

- Completion: the draft and every planned resource implement the intent and required outcome with every System-Owned Invariant protected.

+ Completion: every file in step 2's list exists, and each hard constraint from step 1 appears in the draft.

### 4. Validate structure

- Run a trusted, already-installed `skills-ref validate <skill-directory>` and

- record its version and source. Do not use the similarly named npm package; it

- is not the official reference validator. If the official validator is not

- already available, either use the manual checks below or ask before downloading

- the official Python implementation from a pinned `agentskills/agentskills`

- commit. Manually check: `name` is at most 64 characters, lowercase kebab-case,

- has no leading, trailing, or consecutive hyphens, and matches the directory;

- `description` is 1 to 1024 characters; the body is at most 500 lines;

- frontmatter uses only the canonical fields; `compatibility`, when present, is

- at most 500 characters; and `metadata`, when present, contains string values

- only.

+ Run the Agent Skills reference validator, `skills-ref validate

+ <skill-directory>` ([specification](https://agentskills.io/specification#validation)),

+ from a trusted install, and record its version and source; some published

+ builds name the same command `agentskills validate`. Do not use the similarly

+ named npm package; it is not the reference validator. If the reference

+ validator is not already available, either use the manual checks below or ask

+ before installing it from a pinned `agentskills/agentskills` commit. Manually check every field against the table in

+ [references/portability.md](references/portability.md), that no other field

+ appears, that `metadata` holds string values only, and that the body is at

+ most 500 lines.

Completion: the validator passes, or every named fallback check passes with the tool limitation recorded.

- ### 5. Compare behavior

+ ### 5. Check behavior

- Treat changed instruction semantics, a changed trigger description, or a changed bundled resource as substantive; typo, formatting, and link-only edits are exempt. Follow [assets/baseline-test-template.md](assets/baseline-test-template.md): declare a small discriminating case set, optionally retain a small number of explicitly labeled passing-baseline controls for load-bearing contracts, run matched with/without pairs in fresh contexts, grade binary through an independent grader, and emit the durable case files and log lines to the host's test location (`tests/<skill-name>/` when no convention exists). Controls can prove non-regression, never improvement. For a change limited to description or trigger routing, compare unforced activation on the trigger set instead of forced-load behavior.

+ Follow the selected route in [assets/baseline-test-template.md](assets/baseline-test-template.md). It owns the focused check and the full comparison protocol, including case construction, regression controls, grading, cost, and the ship rule. Emit case files and log lines to the host's test location (`tests/<skill-name>/` when no convention exists).

- Completion: every substantive change is covered by graded discriminating cases showing the intended improvement, every retained control still passes, no case regresses, and the case files and log lines are emitted.

+ Completion: the selected route's checks have run and its case files and log lines are emitted; cosmetic-only edits record behavioral evaluation as not applicable.

### 6. Decide and review

- Have a separate fresh-context agent apply the baseline comparison's decision rule, then run [references/review-checklist.md](references/review-checklist.md) top to bottom. Give the reviewer the skill, intended outcome, hard constraints, artifacts, traces, and graded case results without the author's conclusions. Use its findings to identify wasted paths, ambiguous or unused instructions, recurring corrections that belong in `Gotchas`, and helper logic repeatedly reinvented across runs that belongs in `scripts/`. Any substantive follow-up edit returns through structural validation and the affected cases before shipping.

+ For focused validation, directly inspect the changed guidance and actual check output against the intended outcome and hard constraints, using the applicable items in [references/review-checklist.md](references/review-checklist.md). The author may do this inspection; it is not independent evidence. A whole-package audit, matched improvement experiment, and separate final reviewer are not required.

- The general checklist-exception path does not apply to independent grader or final reviewer availability or context independence. If either role is unavailable or cannot run in an independent context, its state remains unverified and blocks completion until a separate context completes it.

+ For full validation, have the independent final reviewer apply the template's ship rule to the graded results, then apply the whole checklist with the inputs it names, and revise from its findings. Required independent grading or review remains unverified and blocks completion when unavailable; a checklist exception cannot replace it.

- Completion: the baseline comparison has a ship or return-to-correction decision, and every checklist item passes or has a user-approved deliberate exception where the checklist permits one.

+ Any substantive follow-up edit reselects its route and returns through step 4 and the affected cases before shipping.

- ### 7. Test the description

+ Completion: focused validation has passing structural and affected behavior checks, direct artifact inspection, and a claim limited to what was exercised; full validation has a ship decision and every checklist item passes.

- For a new skill, or whenever the description changed, follow [assets/trigger-queries-template.md](assets/trigger-queries-template.md): build the should-trigger and near-miss query set, record it in `tests/<skill-name>/triggers.md`, and judge it through separate fresh-context agents using the template's protocol and thresholds. When a revision leaves the description untouched, the existing trigger contract stands — skip the rerun; the routing contract did not change.

+ ### 7. Test the description

- After any description edit, rerun the complete query set and the affected behavioral comparison.

+ For a new skill, or whenever the description changed, follow [assets/trigger-queries-template.md](assets/trigger-queries-template.md) for the query set, judging, thresholds, and tuning. A revision that leaves the description untouched skips the run.

- Completion: for a new or description-changed skill, every should-trigger query passes and no near miss activates, with results logged (a judgment that cannot be run is recorded as not run, never counted as a pass); otherwise the existing trigger contract is confirmed unchanged.

+ Completion: for a new or description-changed skill, the template's thresholds are met and the results are logged, with a judgment that cannot be run recorded as not run and never counted as a pass; otherwise a diff of the description against the preserved prior version is empty.

### 8. Package and install

- Recheck the host conventions from step 2 and confirm the canonical directory is self-contained. Run the smoke check from [assets/trigger-queries-template.md](assets/trigger-queries-template.md): install from the current local source into a disposable project on each roster harness — the harness target set declared in step 2 — ask one should-trigger query, confirm the skill activates, and record one log line per harness. Using a user-level skill location or overwriting an existing same-name installation requires explicit user approval.

- When a roster harness is unavailable, log it as not run rather than guessing; a failed smoke check returns to correction.

+ For a new package, or a change to packaging or the install path, recheck the host conventions from step 2, confirm the canonical directory is self-contained, and run the smoke check from [assets/trigger-queries-template.md](assets/trigger-queries-template.md), which owns the install, the proof of which copy activated, and the result states, on each harness in step 2's target set. Using a user-level skill location or overwriting an existing same-name installation requires explicit user approval.

If packaging exposes a defect that changes the package, apply step 6's re-entry rule before completing this step.

- Completion: the source validates, and every roster harness has a logged smoke result of pass or not run, with no failure outstanding.

+ Completion: the source validates, and each roster harness logs a smoke pass, or a not run with the user's logged decision to ship without it.

## Gotchas

- - The description carries the triggering burden. State its owned trigger branches and reserve workflow details for the body.

- - A later substantive edit invalidates the affected comparison even when an earlier draft passed.

- Check the target collection and system-provided skills for name collisions. Verb-led gerund names (`creating-portable-skills`, not `skill-creator`) are usually more specific.

- - Do not encode a host repository's local rules into a portable skill. Changelog policy, tracker choice, and CI vendor stay in that repository.

+ - Keep a host repository's local rules, such as changelog policy, tracker choice, and CI vendor, in that repository rather than in the portable skill.

- When the skill's intent shrinks, update evals, cases, and trigger queries in the same change rather than leaving a one-off exception.

## Credits

The review vocabulary distills [writing-great-skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills) by Matt Pocock (MIT) and [writing-skills](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) by Jesse Vincent (MIT). Format, evaluation, and description doctrine follow the [Agent Skills specification](https://agentskills.io), its skill-creation guides, and Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) (Apache 2.0).