12 added, 20 removed. Audit A to A.
---
name: creating-portable-skills
description: Use when creating, updating, or migrating an Agent Skill, or when finding problems in its description, triggers, structure, portability, or evidence. Produces prioritized findings or a portable, installable Agent Skills package. Explanation-only requests stay with general reasoning.
license: MIT
compatibility: 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 Agent Skills package with structural validation, appropriately scoped behavioral evidence, and separate trigger and installation checks.
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.
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.
## Workflow
- Before starting a new skill, ask the user to choose **ordinary personal skill** or **public or unusually load-bearing skill** verification. For an authorized revision or migration, ask after the audit and scope approval, before changing files. Do not ask during a read-only audit. Skip the question only when the user has already chosen in the current request; otherwise, briefly recommend one mode and let the user decide.
-
- Ordinary personal verification uses the routine listing-query tier. Public or unusually load-bearing verification uses the public or unusually load-bearing listing-query tier. The choice changes only the listing-query tier defined in [assets/trigger-queries-template.md](assets/trigger-queries-template.md); it does not change the required matched comparison, structural validation, native checks, or declared model-harness target set.
-
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.
### 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.
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.
### 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 user-selected verification mode is recorded, 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 fits one sentence, and the triggers, near-misses, outcome, done state, hard constraints, requirements, and examples are known or explicitly 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. 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. 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.
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.
Completion: the draft and every planned resource implement the intent and required outcome with every System-Owned Invariant protected.
### 4. Validate structure
Run `npx skills-ref validate <skill-directory>`. If it cannot run because the environment lacks Node or network access, state that limitation and 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.
Completion: the validator passes, or every named fallback check passes with the tool limitation recorded.
### 5. Compare behavior
- Treat changed instruction semantics, a changed trigger description, or a changed bundled resource as substantive. Before comparing behavior, enumerate every substantive changed instruction or resource group. The baseline template permits one scoped candidate instruction group, so create and complete a separate record for each unrelated group; do not let evidence or a candidate decision for one group stand in for another. For a group limited to description or trigger routing, use matched unforced activation cases instead of forced-load behavior: compare whether each variant activates for the same trigger requests and stays inactive for the same near-misses. Copy [assets/baseline-test-template.md](assets/baseline-test-template.md) to the host's test-record location (`tests/<skill-name>/` when no convention exists), preserving earlier dated evidence. Complete each record using its case-construction, grading, candidate-decision, evidence-label, Claim Ceiling, and matched-comparison waiver rules. Typo, formatting, and link-only edits are exempt.
+ 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, 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). For a change limited to description or trigger routing, compare unforced activation on the trigger set instead of forced-load behavior.
- Completion: every substantive changed group is enumerated and has its own completed record and candidate decision; each record covers every declared target and predeclared case, the evidence it earned, and what remains unverified.
+ Completion: every substantive change is covered by graded discriminating cases showing the intended improvement with no regression, and the case files and log lines are emitted.
### 6. Decide and review
- Have a separate fresh-context agent apply the completed baseline record's candidate-decision rules, 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 evidence record 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 every affected comparison cell. It also invalidates native package-harness and model-harness evidence bound to the superseded revision until those cells rerun.
+ 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.
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.
- Completion: the completed baseline record has a final candidate decision, and every checklist item passes or has a user-approved deliberate exception where the checklist permits one.
+ 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.
### 7. Test the description
- Copy [assets/trigger-queries-template.md](assets/trigger-queries-template.md) beside the baseline record and complete it using its query-construction, separate-agent judging, tier, scoring, evidence, and tuning rules.
-
- When a required listing judgment is unavailable, record it as unverified and record a shipment-only waiver with the template if the user explicitly authorizes shipment. The waiver does not change the state or Claim Ceiling. Failed listing evidence cannot be waived.
+ 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.
- After a description edit, rerun the template's complete listing query set and the affected behavioral comparison.
+ After any description edit, rerun the complete query set and the affected behavioral comparison.
- Completion: every declared target passes the template's listing-proxy rules or has an explicit user shipment waiver for an unavailable judgment, with its unverified state and Claim Ceiling preserved.
+ 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.
### 8. Package and install
- Recheck the host conventions from step 2 and confirm the canonical directory is self-contained. Complete the native package-harness and model-harness sections in [assets/trigger-queries-template.md](assets/trigger-queries-template.md): install from the current local source through each declared harness's documented path, verify installed content identity, and record discovery, loading, and triggering separately for every applicable target cell. Use a disposable project or workspace by default. Using a user-level skill location or overwriting an existing same-name installation requires explicit user approval.
-
- When a native check is unavailable, complete the template's Waiver section if the user authorizes shipment.
+ 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 native check fails, return to correction or obtain an explicit user decision to remove the failing cell from the declared target scope. A failed required state cannot be waived or satisfy completion.
+ When a roster harness is unavailable, log it as not run rather than guessing; a failed smoke check returns to correction.
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 required native state passes or is unavailable, remains unverified with its claim limit preserved, and has an explicit user shipment waiver; no failed required state remains.
+ Completion: the source validates, and every roster harness has a logged smoke result of pass or not run, with no failure outstanding.
## 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.
## 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).