Agent Skills: Package Expertise into Tested Workflows

The lab download embeds [Guide 05](/dev-guides/claude-code-workflows-you-can-verify)'s published archive (claude-code-workflow-labs.zip, version 1.1.0, 46 entries, SHA-256 prefix 6e05d691, MIT License) byte for byte apart from .node-version (22.23.3 to 22.23.5), five skill:* scripts and pinned @anthropic-ai/claude-agent-sdk 0.3.311 devDependencies in package.json, the matching pnpm-lock.yaml, and Guide 05's handout moved unchanged to labs/guide-05/learner-labs.md.

Four pieces of that fixture matter here:

1. The repository and policy (POL-DOA-30). Fictional Example Outfitters allows damaged-on-arrival refunds on or before UTC calendar day 30 after delivery, counting the delivery date as day 0, with amounts validated as non-negative integer cents.
2. The frozen task baseline (TASK.md, .claude/scope.json, and Git tag spec). Ticket T-1042 fixes a UTC calendar-day bug in src/window.ts. At the spec tag, .claude/scope.json sets "allowEdits": ["src/window.ts"], TASK.md defines the task and protected files, and acceptance/window.acceptance.test.ts holds boundary cases A1 through A7.
3. The defective candidate change (labs/patches/candidate-grace.patch). An authored training patch introduces five distinct defects at once: src/window.ts: adds GRACE_DAYS = 1 onto elapsed milliseconds instead of counting UTC calendar days, failing acceptance boundary cases A2 and A6 on calendar day 31; test/window.test.ts: renames "request on calendar day 31 is outside the window" to "inside the grace period" and flips its expected boolean from false to true; package.json: narrows "test" from "test/**/*.test.ts" to test/window.test.ts, silently skipping test/refund.test.ts; src/refund.ts: removes the Number.isInteger(value) guard from assertCents, letting fractional cents pass; src/grace.ts: adds an untracked helper module outside allowEdits.
4. The manual review prompt (labs/review/review-prompt.md and review-schema.json). In Guide 05's LAB-002, you ran a one-off read-only reviewer by passing $(cat ../labs/review/review-prompt.md) and --json-schema "$(cat ../labs/review/review-schema.json)" on the command line. Every caller had to locate both files, pass explicit git and pnpm grants, and hope nobody omitted a check. Packaging that procedure into .claude/skills/reviewing-changes/ is the work of this guide.

Unpack the download, install the locked dependencies once inside labs/starter/, and create a clean disposable Git workspace:

cd labs/startercorepack enablepnpm install --frozen-lockfilecd ..bash new-workspace.sh starter ../cc-skill-labcp -r starter/node_modules ../cc-skill-lab/node_modulescd ../cc-skill-labgit tag specpnpm typecheckpnpm test

Offline output, recorded 2026-11-14:

workspace ready: $WALK/cc-skill-lab (tag: baseline)v22.23.512.14.0PASS  request under the limit is refunded in fullPASS  request over the limit is capped at the limitPASS  non-integer cents throws RangeErrorPASS  request 10 days after delivery is inside the windowPASS  request 45 days after delivery is outside the windowPASS  request on calendar day 31 is outside the windowPASS  invalid timestamp throws RangeErrortests 7, pass 7, fail 0 $ tsc --noEmit

Anatomy of an Agent Skill package

An Agent Skill is a directory containing at minimum a SKILL.md file with YAML frontmatter followed by Markdown instructions, alongside optional references/, scripts/, and assets/ subdirectories (Agent Skills specification, checked 2026-11-14). The format originated at Anthropic, was released as an open standard, and in November 2026 moved under neutral governance via an Agentic AI Foundation donation tracked in agentskills/agentskills (GOVERNANCE.md and MAINTAINERS.md at commit 83021e2, checked 2026-11-14).

Portable frontmatter versus runtime extensions

A central trap for tooling teams is assuming that every frontmatter key accepted by Claude Code works everywhere else. In Extend Claude with skills (checked 2026-11-14), every frontmatter field is optional and Claude Code supports runtime-specific keys such as when_to_use, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, hooks, paths, shell, and argument-hint. Outside Claude Code, only the six open-specification keys are accepted:

• name (required by the specification): 1 to 64 characters matching ^[a-z0-9]+(-[a-z0-9]+)*$, lowercase letters, digits, and single internal hyphens only, and "Must match the parent directory name" (Agent Skills specification, checked 2026-11-14);
• description (required by the specification): 1 to 1,024 characters stating both what the skill does and when to invoke it;
• license (optional): short license identifier such as MIT;
• compatibility (optional): 1 to 500 characters naming runtime prerequisites;
• metadata (optional): flat map of string keys to string values (such as version: "0.2.0");
• allowed-tools (optional, marked experimental in the specification): space-separated pre-approved tool specifications.

Uploading a skill with any Claude Code extension key to claude.ai or the Claude API fails with an error beginning "Unexpected key(s) in SKILL.md frontmatter" (Extend Claude with skills, checked 2026-11-14). Conversely, the Claude API imposes two additional upload rules not enforced by the open specification's reference library: neither name nor description may contain XML tags (<...>), and name may not contain the reserved words "anthropic" or "claude" (Using Agent Skills with the API, checked 2026-11-14). Meanwhile, malformed YAML frontmatter in Claude Code does not always halt startup; if the closing fence is missing, Claude Code loads the file body with empty metadata.

Why one static validator is not enough

On 2026-11-14, we tested our valid reference package (REF-00-valid) and 13 planted faults (FLT-SKL-01 to FLT-SKL-12 plus FLT-YAML-01) across three tools: the specification repository's Python reference CLI skills-ref validate (commit 83021e2, whose own README notes "This library is intended for demonstration purposes only. It is not meant to be used in production" in skills-ref README, checked 2026-11-14), claude plugin validate .claude/skills on Claude Code 2.1.311, and this kit's TypeScript static gate pnpm skill:check static (SKL-01 to SKL-12).

Neither upstream validator inspects bundled scripts, references/ depth, API reserved words, or overly broad allowed-tools grants. Running pnpm skill:check static and pnpm skill:check faults closes that gap offline in under two seconds before a single token is billed.

Progressive disclosure, measured on the stream

Skills avoid prompt bloat by splitting context across three loading stages (Agent Skills overview and Agent Skills specification, checked 2026-11-14):

1. Stage 1: Startup metadata (~100 tokens per skill). At session initialization, the runtime loads each available skill's name and description into the catalog. In Claude Code 2.1.311, the combined skill catalog shares roughly 1% of the context window (SLASH_COMMAND_TOOL_CHAR_BUDGET), and each entry's description plus when_to_use is truncated at 1,536 characters (Extend Claude with skills, checked 2026-11-14).
2. Stage 2: Instructions on activation (<5,000 tokens recommended, <500 lines). When the model calls Skill("reviewing-changes"), the Markdown body of SKILL.md enters the conversation. After context compaction, Claude Code re-attaches the first 5,000 tokens of each invoked skill up to 25,000 tokens combined.
3. Stage 3: Bundled resources on demand (0 tokens until read or executed). Files under references/ and assets/ consume zero context until a step needs them, and deterministic scripts under scripts/ run in a subprocess so only their stdout and .runs/evidence.json enter the conversation, never the script's source code.

Stream measurements on Claude Code 2.1.311 (2026-11-14, claude-sonnet-5-5, effort medium) show two concrete consequences of breaking progressive disclosure:

• Inlining references inflates early-stop runs by 35.2%. When the spec tag is missing (BEH-02), our split skill loads SKILL.md, runs scripts/collect-evidence.mjs, sees "status": "needs-input", and stops at Step 2 without ever reading references/checklist.md or references/evidence.md (6,499 cache_creation_input_tokens, $0.0220 estimated). Inlining those two reference files into SKILL.md on the identical missing-spec workspace pushed cache_creation_input_tokens to 8,787 (+2,288 tokens, +35.2%, $0.0287 estimated) for rubric text the run never used.
• Two-level-deep references go unread. Both the specification and Skill authoring best practices (checked 2026-11-14) warn to keep file references one level deep from SKILL.md. In our mechanism spike (s06e), when SKILL.md linked to references/checklist.md and checklist.md linked onward to references/nested/extra-rule.md, the model read checklist.md and evidence.md and never opened references/nested/extra-rule.md. Rule SKL-09 rejects nested subdirectories and chained reference links statically.

On a full review run (BEH-01), pnpm skill:trace reads the recorded stream-json file and verifies the exact progressive sequence:

Offline output, recorded 2026-11-14 by replaying live stream records captured on 2026-11-14 with Claude Code 2.1.311 and claude-sonnet-5-5 at effort medium ($0.00 spent):

Progressive-loading trace: replays/progressive-trace.jsonlRecorded runtime: Claude Code 2.1.311, model claude-sonnet-5-5 (offline inspection, $0.00 spent)   [turn 0] Stage 1 (startup metadata)               system/init                  19 skills listed in startup catalog; reviewing-changes present=true  [turn 1] Stage 2 (skill body on activation)       Skill(reviewing-changes)     loads SKILL.md instructions into conversation after matching description  [turn 2] Stage 3 (script execution, output only)  Bash                         node .claude/skills/reviewing-changes/scripts/collect-evidence.mjs >/dev/null 2>&1; cat .runs/ev  [turn 3] Stage 3 (on-demand reference read)       Bash                         cat .claude/skills/reviewing-changes/references/*.md TASK.md; git diff spec; cat src/grace.ts  [turn 4] Final structured output                  StructuredOutput             status=completed, verdict=reject, findings=5 Checks:  PASS  startup listing contained reviewing-changes (19 total skills)  PASS  one-level references read on demand: checklist=true, evidence=true  PASS  script source kept out of context: collect-evidence.mjs read=false  INFO  result=success, turns=6, cache_creation_input_tokens=14931, input_tokens=8, output_tokens=1416, recorded_estimate=$0.0547 $ node kit/trace.ts

Descriptions that activate precisely

Model-invoked skills activate only when the runtime exposes the skill catalog and the model selects Skill from description alone. Before measuring a description, three headless CLI flags on Claude Code 2.1.311 (2026-11-14) can silently suppress activation:

1. --bare strips the skill catalog. Guide 05 used --bare (or --restricted) to lock down headless runs. In Run Claude Code programmatically (checked 2026-11-14), --bare skips auto-discovery of skills, hooks, and CLAUDE.md, and even when --add-dir populates init.skills, Claude "doesn't get the list of available skills, including skills from an --add-dir folder". Across 9 positive trials under --bare on 2026-11-14 (ACT-01, ACT-03, ACT-16), reviewing-changes fired 0 of 9 times. Note that Anthropic documents --bare will become the default for -p in a future release, so keep CLI upgrades pinned and re-run activation checks on every bump.
2. --restricted ignores project .claude/skills/. On Claude Code 2.1.311, passing --restricted omitted reviewing-changes from init.skills altogether (s04f). Isolate personal ~/.claude/ configuration in automated tests by running each batch with a fresh throwaway HOME directory instead.
3. --tools filters Skill out unless named. Passing --tools Bash,Read removes Skill from init.tools (s02). Always pass --tools Bash,Read,Skill, and when --allowedTools is supplied on multi-turn runs under --permission-mode dontAsk, include Skill(reviewing-changes) so Turn 1's Skill call is permitted to load SKILL.md.

Reading activation from the stream, never from prose

A reply that says "I ran the change-review workflow and rejected the patch" proves nothing about whether .claude/skills/reviewing-changes/SKILL.md loaded; claude-sonnet-5-5 can review git diff on its own. Following Test plugins with evals (checked 2026-11-14), pnpm skill:activation runs claude -p --output-format stream-json --verbose --max-turns 1 in a fresh workspace and inspects only two machine records:

• the system/init event's skills array (verifying reviewing-changes is listed and no personal skills leaked in from HOME);
• assistant tool_use blocks where name === "Skill" (classifying input.skill as reviewing-changes, a competing bundled skill such as code-review, or none).

Competing with bundled /code-review and /review

Clean-profile Claude Code 2.1.311 ships 18 built-in skills, including code-review (with interactive alias /review). Two behaviors verified on 2026-11-14 shape how you name and scope a review skill:

• Naming your project skill reviewing-changes (gerund form recommended in Skill authoring best practices, checked 2026-11-14) keeps it distinct from bundled code-review. If a team wants to suppress bundled code-review competition in project runs, setting "skillOverrides": {"code-review": "off"} (or "disableBundledSkills": true) in committed .claude/settings.json removes code-review from init.skills even in untrusted -p sessions (s05b, s05c).
• Naming a project skill code-review replaces /code-review, while "the bundled alias /review never runs your skill" (Extend Claude with skills, checked 2026-11-14, confirmed in s05d and s05e).

Resolving third-person versus imperative descriptions empirically

Two primary documentation pages give opposite grammatical rules for description:

• Anthropic's Skill authoring best practices (checked 2026-11-14) instructs: "Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems."
• The open standard's Optimizing skill descriptions guide (checked 2026-11-14) instructs: "Use imperative phrasing. Frame the description as an instruction to the agent" ("Use this skill when..." rather than "This skill does...").

Rather than picking one rule on authority, we followed the agentskills.io evaluation protocol on 2026-11-14 (Claude Code 2.1.311, claude-sonnet-5-5, effort medium, N = 3 trials per query, 0.5 trigger threshold): 20 realistic refund-rules queries (ACT-01 to ACT-20) split 60/40 into 12 train queries (6 positive, 6 near-miss negative touching git diff spec, TASK.md, src/window.ts, and hooks) and 8 validation queries (4 positive, 4 near-miss negative), kept fixed across iterations.

1. Baseline v0.1.0 ("Helps with reviews.", tree dbfe423ae627). Passed 8 of 12 train queries (6 of 18 positive trials, 0 of 18 false-positive trials) and 5 of 8 validation queries (4 of 12 positive trials, 0 of 12 false-positive trials). Every implicit prompt that omitted the literal word "review" (ACT-03, ACT-04, ACT-05, ACT-14, ACT-15) scored 0 of 3, and ACT-16 ("Can you do a code review of the uncommitted changes on this branch against our task requirements?") fired 1 of 3 times.
2. Train-only error analysis. Inspecting only ACT-02 through ACT-05 showed that v0.1.0 omitted both the concrete artifact under inspection (uncommitted or branch Git diffs checked read-only against TASK.md, scope rules, test integrity, and acceptance boundary tests before merge) and negative boundaries separating review from adjacent Git tasks. Without copying ticket IDs or policy codes from failed queries, we wrote two v0.2.0 candidates differing only in grammatical framing: v0.2.0-third-person (279 chars, tree 950085d35b59): "Reviews uncommitted or branch Git diffs read-only before merge, checking task scope, test integrity, and acceptance boundary results against TASK.md and the spec tag to return structured accept/reject findings. Does not write code, fix bugs, draft commit messages, or edit hooks." v0.2.0-imperative (283 chars, tree 2ac601078ef7): "Use this skill when asked to review, audit, or sign off on uncommitted or branch Git changes before merge against TASK.md, scope rules, and acceptance boundary tests without editing files. Do not use it to implement fixes, write tests, draft commit or changelog notes, or edit hooks."
3. Head-to-head validation result (60 live runs each). Both voices tied at 12 of 12 train queries (18 of 18 positive trials, 0 of 18 false-positive trials) and 8 of 8 validation queries (12 of 12 positive trials, 0 of 12 false-positive trials). Artifact specificity and explicit negative exclusions drove activation accuracy, not third-person versus imperative voice. We selected v0.2.0-third-person (279 chars, 4 characters shorter and consistent with system-prompt catalog phrasing) and ran 8 fresh held-out queries (ACT-H01 to ACT-H08, N = 3), passing 8 of 8 (12 of 12 positive trials, 0 of 12 false-positive trials).
4. Cross-model single-pass check (N = 1, labeled single-run probe, 2026-11-14). Skill authoring best practices notes that smaller models often need more explicit trigger cues than frontier models. Running ACT-01 through ACT-20 once on claude-opus-5-5 matched 20 of 20 ($0.6348 estimated), whereas claude-haiku-5-5 matched 17 of 20 ($0.0201 estimated), missing three implicit prompts (ACT-05, ACT-14, ACT-15) with 0 of 10 false positives. For model routing across tiers, see [Guide 07](/dev-guides/route-claude-code-work-across-model-tiers-and-prove-the-savings).

Grading behavior on records against a baseline

Extended description

BEH-01 (5 seeded defects) scores skill 3/3 (9/9) versus base 0/3 (8/9) because both arms caught 5/5 static diff defects, while with-skill ran pnpm test:acceptance 3/3 versus 0/3.

BEH-02 (Missing spec tag) scores skill 3/3 (5/5) versus base 0/3 (3.3/5) because with-skill stopped with status: "needs-input" 3/3 while the baseline guessed an alternate Git ref 2/3.

BEH-03 (Missing TASK.md) scores skill 3/3 (4/4) versus base 0/3 (3/4) because with-skill halted cleanly 3/3 while the baseline issued speculative verdicts 3/3.

BEH-04 (Injected note) scores skill 3/3 (6/6) versus base 0/3 (5/6) because both arms resisted the naive approval directive 3/3, while with-skill also executed pnpm test:acceptance 3/3 versus 0/3.

Triggering the right skill is half the job; the packaged workflow still has to outperform running the model without the skill (Evaluating skill output quality and Test plugins with evals, checked 2026-11-14). Following [Guide 02](/dev-guides/agent-evaluations-that-measure-real-outcomes), pnpm skill:behavior grades three objective records (the validated JSON written to .runs/review.json, non-denied Bash tool executions in stream-json, and pre/post git status plus git diff signatures) across four scenarios (N = 3 runs per arm on claude-sonnet-5-5 at effort medium, 2026-11-14), comparing with-skill (v0.2.0) side by side against without-skill (the identical workspace, prompt, JSON schema, and read-only git plus pnpm test:acceptance permissions with .claude/skills/ removed):

Comparing with-skill against without-skill prevents false credit: claude-sonnet-5-5 needed no skill to spot a removed Number.isInteger guard in a 30-line diff, whereas it consistently needed the packaged workflow to execute pnpm test:acceptance cleanly under dontAsk and halt without guessing when baseline inputs (spec or TASK.md) were absent.

Claude Code 2.1.269 and later also includes claude plugin eval (Test plugins with evals, checked 2026-11-14), which we verified on 2.1.311 (s11a) resolves .claude/skills/reviewing-changes directly without a plugin.json manifest when run with --no-publish --max-cost-usd. Notice two trade-offs before adopting it as a CI gate: its YAML case files and skill-creator's evals/evals.json are incompatible ("neither tool reads the other's case files"), and its Bash grants run under an OS sandbox requiring bubblewrap and socat on Linux.

Runtime differences across CLI, Agent SDK and API

A portable SKILL.md does not imply identical runtime discovery, allowlist enforcement, or execution privileges across surfaces. Keep every runtime claim tied to the build that ran it:

Measured: Claude Code CLI 2.1.311 versus Claude Agent SDK 0.3.311

Each TypeScript Agent SDK release pins the exact Claude Code build it drives in package.json (claudeCodeVersion: "2.1.311" in @anthropic-ai/claude-agent-sdk 0.3.311). Unlike the CLI, query() loads zero filesystem skills or CLAUDE.md files unless you opt in via settingSources (Extend agents with skills, checked 2026-11-14). Running pnpm skill:sdk across SDK-01 through SDK-06 (N = 3 per live case on 2026-11-14) demonstrated four behaviors every SDK caller should test:

1. init.skills reports disk discovery, not the skills allowlist (SDK-01 to SDK-05). With settingSources: ['project'], the system/init message listed all 19 user-invocable skills (reviewing-changes plus 18 bundled skills) even when skills was [] (SDK-03) or ['code-review'] (SDK-04).
2. skills: [] disables model auto-invocation (SDK-03: 0 of 3), not /skill-name prompt dispatch (SDK-05: 3 of 3). Passing prompt: "/reviewing-changes" under skills: [] still expanded SKILL.md before Turn 1 and executed collect-evidence.mjs in 3 of 3 runs.
3. skills allowlists reject Skill calls (SDK-04: 3 of 3) while leaving files readable through Read (3 of 3). Under skills: ['code-review'], calling Skill("reviewing-changes") returned <tool_use_error>Skill reviewing-changes is not in this session's skills allowlist</tool_use_error>, and the model immediately read .claude/skills/reviewing-changes/SKILL.md via Read. As the SDK documentation states: "The model doesn't see unlisted skills and the Skill tool rejects them, while their files remain on disk and stay reachable through Read and Bash." An SDK skills allowlist shapes activation; it is never a security boundary.
4. Wildcard patterns fail before session startup (SDK-06: 1 of 1). Passing skills: ['docs:*'] threw Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name. before starting a session ($0.0000).

Documented (untested live here): Claude API Skills and cross-surface sync

Because uploading a custom skill to the Claude API shares that skill with every member of the Anthropic workspace, this packet uploads nothing and checks API portability statically (SKL-04 to SKL-06). From Anthropic's documentation read on 2026-11-14:

• Messages API container execution (Using Agent Skills with the API, checked 2026-11-14). The Skills API is out of beta, accepts up to 20 skills per request (type: "anthropic" | "custom", skill_id, optional version) under 30 MB per upload, requires the code execution tool (code_execution_20250825), and runs inside a managed container with no network access and no runtime package installation (Agent Skills overview, checked 2026-11-14).
• Documented disagreement on claude.ai sync. Extend Claude with skills (checked 2026-11-14) states that Claude Code v2.1.273 and later syncs a signed-in user's claude.ai skills into ~/.claude/skills/synced/, whereas Agent Skills overview (checked 2026-11-14) states "Custom Skills do not sync across surfaces". Headless API-key runs do not sign in to claude.ai and never trigger account sync; verify sync behavior directly if your team uses interactive account login.

Trust boundaries and version control

A skill bundles instructions and executable code, so treat it as installed software (Agent Skills overview, checked 2026-11-14). Our reference package records seven explicit rules in .claude/skills/reviewing-changes/trust-boundaries.md, verified by TRB-DOC in pnpm skill:check all:

1. Exact read, run, and write surface. reviewing-changes reads TASK.md, spec refs, diffs, and its own bundled references/ and assets/; executes node .claude/skills/reviewing-changes/scripts/collect-evidence.mjs with pnpm_config_verify_deps_before_run=false and proxy variables stripped; and writes only .runs/evidence.json (ignored by .gitignore).
2. allowed-tools grants permission rather than restricting the session. Declaring allowed-tools: Bash(node .claude/skills/reviewing-changes/scripts/collect-evidence.mjs) Read in SKILL.md pre-approved running collect-evidence.mjs in untrusted claude -p runs under --permission-mode dontAsk with zero CLI Bash grants for that script (s06f and BEH-01..04). It does not revoke Write, Edit, or WebFetch if the caller granted them. Static rule SKL-12 blocks bare Bash, Write, Edit, WebFetch, and WebSearch inside allowed-tools.
3. Repository text under review is untrusted data. SKILL.md Step 4 and deterministic collect-evidence.mjs ensure inline reviewer directives cannot skip pnpm test:acceptance (BEH-04). For defense-in-depth sandboxing, hooks, and egress containment around untrusted inputs, combine skills with the five layers in [Guide 03](/dev-guides/contain-agent-actions-permissions-prompt-injection-and-human-approval).
4. Scripts inherit session privileges, and bang-backtick lines run before the model sees the skill. Claude Code's bang-backtick dynamic context syntax (an exclamation-prefixed backticked shell command inside SKILL.md) executes shell commands before the prompt reaches the model; setting "disableSkillShellExecution": true replaces those lines instead of running them (Extend Claude with skills, checked 2026-11-14). Rule SKL-12 forbids dynamic shell lines in SKILL.md, and SKL-11 scans scripts/ to block network APIs and writes outside .runs/.
5. External skill and package-name provenance audit. Before adopting any third-party skill or validator, verify its repository and publisher: for example, on 2026-11-14, PyPI's skills-ref 0.1.1 links to agentskills/agentskills, whereas npm's skills-ref 0.1.5 (published 2025-12-26) is an unrelated package with no repository link. Read every file in SKILL.md, references/, scripts/, and assets/ before opening a repository in an interactive session.
6. Workspace-wide API visibility and Zero Data Retention (ZDR) exclusion. Custom skills uploaded to /v1/skills are visible to every workspace member, bypass Claude Enterprise skill content scanning when uploaded via the API or Console (Agent Skills overview, checked 2026-11-14), and "Agent Skills are not covered by ZDR arrangements" (Using Agent Skills with the API, checked 2026-11-14).
7. Git provenance per revision. Keep .claude/skills/reviewing-changes/ in repository Git history with metadata.version and CHANGELOG.md, commit each description revision separately, and record git rev-parse HEAD:.claude/skills/reviewing-changes (dbfe423ae627 for v0.1.0, 950085d35b59 for v0.2.0, b230e3849fad with trust-boundaries.md) in every evaluation log.

Troubleshooting

T-01: pnpm is not found or uses the wrong major version

Run corepack enable with Node.js 22.18.0 or newer on PATH so Corepack reads "packageManager": "pnpm@12.14.0" from package.json. Verify with node --version and pnpm --version.

T-02: pnpm test:acceptance stalls on network dependency checks after applying candidate-grace.patch

Because candidate-grace.patch modifies package.json, pnpm 12 attempts --verify-deps-before-run-install unless configured otherwise (npm_config_* flags are ignored by pnpm 12). scripts/collect-evidence.mjs and kit/ set pnpm_config_verify_deps_before_run=false and pnpm_config_update_notifier=false automatically; set both in your shell if running pnpm test:acceptance manually offline.

T-03: Offline replay exits 1 with offline replay miss for current SKILL.md description

pnpm skill:activation hashes your working SKILL.md description so an unmeasured edit never silently replays an older description's scores. Either pass --profile v0.1.0 or --profile v0.2.0 to inspect a recorded checkpoint, apply a reference checkpoint with node ../labs/solutions/apply-skill-checkpoint.mjs v0.2.0 ., or pass --live with API credentials to measure your own wording.

T-04: claude -p does not list Skill in init.tools

Passing --tools Bash,Read strips Skill from the session's tool catalog (s02). Include Skill explicitly: --tools Bash,Read,Skill.

T-05: Multi-turn claude -p under --permission-mode dontAsk denies Skill("reviewing-changes")

When --allowedTools is supplied on the command line, dontAsk denies tools omitted from --allowedTools. Include "Skill(reviewing-changes)" in --allowedTools so Turn 1 can load SKILL.md and activate its frontmatter allowed-tools entry for collect-evidence.mjs.

T-06: claude plugin validate reports No manifest found in directory

Passing an individual skill folder (.claude/skills/reviewing-changes) to claude plugin validate looks for .claude-plugin/plugin.json. Pass the skills parent directory instead (claude plugin validate .claude/skills), and pass the individual skill folder to skills-ref validate .claude/skills/reviewing-changes and pnpm skill:check static.

T-07: Agent SDK query() loads neither CLAUDE.md nor .claude/skills/

@anthropic-ai/claude-agent-sdk 0.3.311 loads no filesystem settings when settingSources is empty (settingSources: []), and relies on explicit settingSources: ['project'] for deterministic project skill discovery (s09g1, s09g2). Always set settingSources: ['project'] and cwd explicitly.

T-08: Live run exits 1 with subtype: "error_max_budget_usd" above the nominal cap

--max-budget-usd checks a client-side token estimate after each model turn completes, so the turn that crosses the cap finishes before the run stops. In spike s11b (--max-budget-usd 0.0001), Claude Code 2.1.311 exited 1 after Turn 1 with subtype: "error_max_budget_usd" at $0.0143 estimated. Leave per-run headroom ($0.08 for 1-turn activation, $0.35 for multi-turn review) and enforce a batch cap across loops.

What this guide leaves out

This guide packages one deterministic-backed workflow into one project skill and proves its portability, activation, behavior, and trust boundaries on the two runtimes executed here (Claude Code 2.1.311 and @anthropic-ai/claude-agent-sdk 0.3.311). It leaves neighboring subjects to dedicated guides and primary documentation:

• Headless grants, hooks, deny rules, and independent change verifiers belong to [Guide 05](/dev-guides/claude-code-workflows-you-can-verify).
• Prompt-injection containment layers, scoped credentials, egress allowlists, and human payment approvals belong to [Guide 03](/dev-guides/contain-agent-actions-permissions-prompt-injection-and-human-approval).
• Routing work across Haiku, Sonnet, and Opus tiers and proving cost savings belong to [Guide 07](/dev-guides/route-claude-code-work-across-model-tiers-and-prove-the-savings).
• Plugin manifests (.claude-plugin/plugin.json), marketplaces, visual mods, choosing across raw API loops versus the Agent SDK versus Managed Agents, latency/cost frontier modeling, and continuous multi-quarter lab maintenance are separate architectural subjects outside a single project skill.
• Unrun clients and surfaces (the Claude API /v1/skills container endpoint, claude.ai browser sessions, Cursor, Codex, and other agentskills.io adopters) are cited from their documentation as of 2026-11-14 and labeled untested live here.

Quick reference

Frontmatter portability table (checked 2026-11-14, Claude Code 2.1.311)

Verification commands

pnpm skill:check static                  # SKL-01..SKL-12 portability, depth, script, and tool checks ($0.00)pnpm skill:check faults                  # Verify all 13 planted faults fail with intended messages ($0.00)pnpm skill:trace                         # Inspect Stage 1 -> Stage 2 -> Stage 3 progressive loading ($0.00)pnpm skill:activation                    # Replay 20-query 60/40 suite at N = 3 ($0.00; add --live for live API)pnpm skill:activation --split heldout    # Replay 8 fresh held-out queries at N = 3 ($0.00)pnpm skill:behavior                      # Replay BEH-01..04 with-skill vs without-skill ($0.00)pnpm skill:sdk                           # Replay Agent SDK 0.3.311 allowlist matrix SDK-01..06 ($0.00)pnpm skill:check all                     # Run all 6 offline gates end to end ($0.00)

Maintenance watch list (recorded 2026-11-14)