git:20260925.46ead95 to git:20260927.370ca97

10 added, 18 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: Full validation requires isolated agent contexts or separate sessions for agent grading and review.

+ compatibility: Behavioral validation requires a different-model blind grader and an independent review context.

---

# 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.

Skills produced here follow the [Agent Skills format](https://agentskills.io/specification). Read [references/portability.md](references/portability.md) when checking frontmatter against its canonical-package rule, choosing an install location, adding harness-specific metadata, or making a claim about a harness. [references/skills.md](references/skills.md) is the convention for frontmatter fields, eval files, arms and runs, targets, grading, the run archive, and committed evidence; read it before steps 2, 5, 6, and 7.

- 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 evals and a different independent reviewer performs the final package review. The author never supplies a grade or review that must come from an independent context, not even provisionally or as labeled notes standing in for grades. When a required independent context is unavailable, prepare a self-contained handoff for a separate session that includes the eval assertions and every run output to grade. Until that session completes it, the grade or review stays unverified and the change does not ship; say so plainly instead of leaving shipping as the user's call.

+ An independent reviewer took no part in authoring the change and did not produce the artifact under review; an agent auditing a skill it did not write qualifies. Behavioral grading uses an independent context on a different model from the executor. One independent review checks the package and evidence. The author never supplies required independent grades or review, even provisionally. If either is unavailable, prepare a self-contained handoff with assertions, outputs, tool traces, and available child readouts; the missing judgment stays unverified and the change does not ship.

## 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. Revising optional advice, such as a suggested reading order, can qualify. So can removing history phrasing, pinned model names, workarounds for a named model, unsourced hardcoded facts, or duplication when required behavior does not change. Even a one-line approval, output-schema, or helper change cannot qualify. A focused check runs each affected eval once per target with the changed skill and a blind independent grader.

- - **Full validation** applies to new skills, fixes that add or change required behavior, all other substantive changes, and ambiguous eligibility. Substantive means changed instruction semantics, trigger description, or bundled resource.

- - **Cosmetic edits** skip behavioral evaluation: typo, formatting, and link-only edits, and moving or reformatting eval files, since `SKILL.md` never loads `evals/`. Step 4's structural checks and `scripts/check-evals.py` suffice.

+ A substantive change gets one regression check on affected evals, once per declared Executor target, under [references/skills.md](references/skills.md). New skills check realistic cases. Description changes also follow step 7. Cosmetic edits (typos, formatting, links, or moving eval files without changing their meaning) may skip behavior checks and use step 4 and `scripts/check-evals.py`.

- A read-only audit starts and ends at step 0. Authorized focused revisions and cosmetic edits 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.

+ A read-only audit starts and ends at step 0. Authorized revisions and new skills start at step 1; an additional audit before implementation is not required. Existing authorization for the material fix scope carries forward. The operator owns iteration and stopping; broader cross-model sweeps are separate work.

### 0. Audit an existing skill

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: the evidence-backed review, its prioritized fix list, and a final verdict are delivered, with no file changed. Revision begins only in a separate user-authorized request.

Change completion: the user has authorized the material fix scope and settled any authority or taste decisions that stay with them. Continue at step 1.

### 1. Resolve the intent

Ground the reusable guidance in real work already available: the conversation, the existing package, user corrections, successful task history, input and output examples, project documentation, schemas, review comments, issues, version history, and resolved failures. Name only the hard constraints, including decisions that remain with the user, and only real environment requirements. When a missing decision could materially change the result, scope, or authority and the available context leaves it open, ask one focused question at a time.

Completion: the job is written as one sentence, and the triggering conditions, near-misses, intended outcome, observable done state with any required artifact or handoff, hard constraints, environment requirements, and representative examples are each written down with a value or `not applicable`.

### 2. Scope targets and resources

Take the target set from the **Targets** section of [references/skills.md](references/skills.md); structural portability alone does not require expanding it.

Choose only resources with repeatable value. Outputs copied by the workflow belong in `assets/`. Reference material that only some paths need belongs in `references/`. Deterministic helpers belong in `scripts/` when prose cannot reliably protect the result. 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.

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. Use the least-prescriptive instruction that reaches the required outcome within its hard constraints: keep every System-Owned Invariant explicit, and leave the agent its reasoning and implementation path everywhere else.

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

### 4. Validate structure

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, ask before installing it from a pinned `agentskills/agentskills` commit, or run the fallback checks: every field matches the **Package format** table in [references/skills.md](references/skills.md), no other field appears, `metadata` holds string values only, and the body is at most 500 lines. Either way, check the canonical-package rule in [references/portability.md](references/portability.md), which the validator does not enforce.

Completion: the validator passes, or every named fallback check passes with the tool limitation recorded, and the canonical-package rule holds.

### 5. Check behavior

- Follow the selected route in [assets/baseline-test-template.md](assets/baseline-test-template.md). Write eval definitions to the skill's `evals/evals.json`, raw runs to the run archive, and the round's benchmark to `evals/benchmarks/`.

- For full validation, before the deciding runs, have the independent final reviewer run the pre-spend review. It checks eval validity: each assertion is decidable from what the grader sees, no assertion is stricter than the skill's contract, and each regression control's baseline plausibly meets the validity bar in **Arms and runs** of [references/skills.md](references/skills.md). The reviewer also checks that the skill's rules are consistent with each other and applies the whole checklist in [references/review-checklist.md](references/review-checklist.md) to the package, with the inputs it names. Revise from its findings before the deciding runs.

+ Use [assets/baseline-test-template.md](assets/baseline-test-template.md) for the affected regression check, blind grading, and failure diagnosis. Before calls, establish the caller's budget and the host's per-call usage and pricing support under **Cost and budget** in [references/skills.md](references/skills.md). The host owns runner automation and configuration; this package stays runner-free.

- Completion: for full validation, the pre-spend review ran and its findings were resolved before the deciding runs. The selected route's checks have run, the eval definitions and the round's benchmark file are written, and this skill's `scripts/check-evals.py` exits 0 on the target skill directory. Cosmetic-only edits record behavioral evaluation as not applicable.

+ Completion: affected checks ran on every declared target, every failure was inspected against its original transcript and classified, and any needed prior-skill diagnosis is recorded. Eval definitions, raw archive records, and the round's benchmark exist, and `scripts/check-evals.py` exits 0 on the target skill. Missing authorized runs or unresolved attribution remain unverified. Cosmetic-only edits record behavior checks as not applicable.

### 6. Decide and review

- 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.

- For full validation, applying the ship rule in [references/skills.md](references/skills.md) to the graded results is a mechanical read. The independent final reviewer confirms that read and, when cost rises past the rule's bound, writes the reason the rule requires. When required independent grading or review is unavailable, the independence rule at the top of this file applies; a checklist exception cannot replace it.

+ Apply the ship rule in [references/skills.md](references/skills.md). Have one independent reviewer apply [references/review-checklist.md](references/review-checklist.md) to the package, assertions, artifacts, and evidence. This review checks that assertions are decidable from the grader's packet and no stricter than the contract. It does not require a separate pre-spend review or a repeated final-review cycle.

- Any substantive follow-up edit reselects its route and returns through step 4 and the affected evals before shipping. Rerun only evals whose prompt, files, or assertions changed, or whose assertions test text that the diff touches. Reuse baseline runs whose bytes did not change; each carried-forward result keeps the revision label it came from. When an eval reruns, its reused baseline outputs are regraded in the same blind packet as the new runs.

+ A substantive follow-up edit returns through step 4 and the affected evals. Recheck evals whose outcomes could change under the revised package or test material, including changed instructions, executable helpers, bundled resources, prompts, inputs, or assertions. Preserve previous artifacts and grades under their original revision labels. Diagnose failures using the prior skill only where needed; do not combine unmatched cohorts into a delta.

- 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.

+ Completion: structural checks pass, required independent grading and review are complete, every failure has an evidence-backed disposition, and none is attributable to the change under test. Claims stay within the exercised cases and targets; unresolved attribution remains unverified.

### 7. Test the description

For a new skill, or whenever the description changed, follow [assets/trigger-queries-template.md](assets/trigger-queries-template.md).

- Completion: for a new or description-changed skill, every query in `evals/eval_queries.json` passes under the thresholds in [references/skills.md](references/skills.md) and the results are recorded; otherwise, a diff of the description against the preserved prior version is empty. A judgment that cannot be run is recorded as not run and never counted as a pass.

+ Completion: for a new or description-changed skill, the query set has run under the trigger rules in [references/skills.md](references/skills.md), every failure has been inspected, and the recorded attribution satisfies its ship rule; otherwise, a diff of the description against the preserved prior version is empty. A judgment that cannot be run is recorded as not run and never counted as a pass.

### 8. Package and install

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 in [assets/trigger-queries-template.md](assets/trigger-queries-template.md) 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 each harness in step 2's target set records a smoke pass, or a not run with the user's recorded decision to ship without it.

## Gotchas

- 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.

- 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/evals.json` and `evals/eval_queries.json` in the same change rather than leaving a one-off exception.

## Credits

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).