skill-standards

<objective> The canonical standards for skill authoring — frontmatter, XML structure, naming, descriptions, progressive disclosure, skill types, reference patterns, code-fence and bash constraints, validation, and script testing. </objective>

<success_criteria> Skills conform to these standards when, at minimum: (a) SKILL.md is under 500 lines unless it qualifies for <eager_foundation_exception>, (b) the body uses pure XML structure with no markdown headings, (c) <objective> and <success_criteria> tags are present, (d) the description matches the invocation path — directive when description-match activation applies, passive when invoked only by exact name or a parent capability — (e) the skill is independent of its caller, and (f) an /audit-skill run on the skill seals approved. </success_criteria>

<reference_note> This is a reference skill: it standardizes skill authoring and carries no standalone workflow. </reference_note>

<rule_catalog> Every rule this skill and its references state has one stable identifier and one severity in ${CLAUDE_SKILL_DIR}/references/rule-catalog.md. Read it before recording or repairing a finding against these standards. </rule_catalog>

<repo_local_overlay> Inside a repository, check for spx/local/skills.md at the repository root. Read that file after this reference if it exists and apply it as the repo-local specialization (e.g., marketplace-specific naming conventions or additional constraints). A local overlay supplements skill behavior; it does not declare product truth. </repo_local_overlay>

<skill_organization>

Skills follow a reference pattern to avoid duplication:

1. Foundational skill (e.g., /test) — core principles and domain-agnostic patterns.
2. Language-specific skills (e.g., /author-python-test, /author-typescript-test) — reference the foundational skill, provide only language-specific implementations.
3. Reference skills (e.g., /typescript-code-standards, /skill-standards) — standards explicitly invoked by composing skills, never selected as standalone user workflows.

For language-specific skill prose that references a foundation, use the unqualified invocation name (/test) so it resolves to whichever foundational skill is installed.

Skill-tool composition: A skill may invoke another skill when the parent workflow explicitly composes that capability. Composition obeys these limits:

1. The parent carries the runtime's skill-invocation capability in allowed-tools and names the exact installed skill to invoke.
2. The target remains callable through the active runtime's skill-invocation surface; no runtime setting may block composed or reference-skill invocation.
3. The parent owns sequencing, validates the returned shape, and merges the child result into its own output contract.
4. A composition step invokes only capabilities required by the workflow; it never discovers or invokes adjacent skills speculatively.
5. Reference-only prose may name foundational concepts without invocation, while reference skills are loaded through the runtime's skill-invocation capability when their full standards govern the work.

Caller independence: A skill governs its own behavior and nothing else. It never names, describes, detects, constrains, refuses, branches on, or otherwise depends on its caller or invocation context. A description may state the skill's invocation contract — for example, that other skills load it and a user does not invoke it — because its behavior never depends on who the caller is. The dependency runs one way: a caller may know the skill it invokes; the skill never knows its callers.

The harness environment is not a caller. The environment a skill runs in — an interactive session, a programmatic run, or a hosted runner — fixes the shell contract every command the skill instructs must meet, whoever invoked it. A skill that names the command form its environment accepts, such as one physical command line where a runner requires it, follows a property of its own run and depends on no caller. The same holds for the fallback location a skill selects for its payload scratch directory where the harness names none, such as the directory a hosted runner designates: the hosting environment fixes it, so naming it is a property of the run. Choosing a form by who invoked the skill, by the agent or skill that dispatched it, or by what its task message asks for remains caller dependence.

Context placement, agent selection, and dispatch policy belong to the caller. A skill remains independently invocable even when the product normally reaches it through an agent or another skill. Correct an invalid invocation in the router, agent, or composing skill that made the decision; never add a dispatch gate or caller check to the invoked skill.

Composed skill dependencies. A composing SKILL.md names each dependency with the instruction Use skill `{plugin}:{skill}`. and, on a harness that exposes a skill-composition tool, grants that tool as one complete allowed-tools item; on a harness without one it grants nothing for composition. Source authored for more than one harness never spells one harness's skill tool name. {!# Source-only maintainer guidance: in this marketplace the instruction is therequire_skilldirective and the grant is theuse_skill tool token; the build renders the target's name and removes an unavailable capability as one complete list item. Generated guidance describes only the harness it ships to. #!}

</skill_organization>

{!% if target == 'claude' %!} <frontmatter>

Every SKILL.md starts with YAML frontmatter. The canonical catalog of supported fields lives in the Claude Code docs at https://code.claude.com/docs/en/skills#frontmatter-reference. Read the docs page when a question is about execution behavior; read this section when it is about how this marketplace authors skills.

Field	Required	Constraint
name	No	Lowercase letters, numbers, hyphens. ≤64 chars. Must match the directory name when set. If omitted, the directory name is used.
description	Recommended	Style follows the invocation path in <descriptions>. Combined with when_to_use the listing is capped at 1,536 chars; put the key trigger first.
when_to_use	No	Extra trigger phrases or example requests appended to description in the skill listing. Shares the 1,536-char cap.
argument-hint	No	Free-text hint shown during / autocomplete (e.g. [issue-number]).
arguments	No	Named positional arguments for $name substitution in the body. Space-separated string or YAML list; names map to argument positions in order.
allowed-tools	No	Tools Claude may use without per-call approval while the skill is active. Space-separated string or YAML list. Restrict for audit and reference skills.
disable-model-invocation	No	true to block programmatic invocation entirely — Claude cannot load the skill, including via the Skill tool, and the skill cannot be preloaded into subagents. Use for deploy-style user-only commands. Default false.
user-invocable	No	false to hide from the / autocomplete menu while keeping Claude able to invoke via the Skill tool. Description stays in context. Use for reference skills that other skills load programmatically. Default true.
model	Forbidden	Skills retain the invoking session's configuration, including when a configured subagent invokes the skill.
effort	Forbidden	Skills retain the invoking session's reasoning configuration.
context	No	fork to run the skill in a forked subagent context. Combine with agent.
agent	No	Subagent type to use when context: fork is set (Explore, Plan, general-purpose, or a custom agent). Defaults to general-purpose.
hooks	No	Hooks scoped to this skill's lifecycle. See the Claude Code hooks reference for shape.
paths	No	Glob patterns that limit auto-activation to matching files. Comma-separated string or YAML list.
shell	No	bash (default) or powershell for the skill's inline and fenced command-injection blocks. The powershell value requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1.

Visibility vs invocability. Two fields gate how a skill is reached. They are not aliases — pick deliberately. Automation re-entry — a scheduled wakeup, heartbeat, or /loop — arrives as a user-style prompt because the harness offers no Claude-private heartbeat, so it follows the User /{skill} column exactly:

Frontmatter	User /{skill}	Claude (Skill tool)	Subagent preload	Automation re-entry	Description in context
(default)	Yes	Yes	Yes	Yes	Always
disable-model-invocation: true	Yes	No	No	Yes	Not in context
user-invocable: false	No	Yes	Yes	No	Always

Pick the gate by role:

• A reference skill another SKILL.md loads via the Skill tool, or a background-knowledge skill, uses user-invocable: false — hidden from the / menu, still loadable by Claude and preloadable into subagents.
• A user-only side-effecting command (a deploy command) uses disable-model-invocation: true. NEVER set it on a skill other skills or subagents must load: it blocks the Skill-tool call (surfacing Skill <name> cannot be used with Skill tool due to disable-model-invocation) AND blocks subagent preloading.
• A skill any automation loop re-enters — a scheduled wakeup, heartbeat, or /loop target — MUST be user-invocable (leave the default; never user-invocable: false). Automation fires as a user-style prompt, so user-invocable: false rejects it and no Claude-private heartbeat exists to bypass that. When a loop body is otherwise reference-like, expose a user-invocable entry the loop targets rather than gating the body. Such a loop body keeps a passive description — it is invoked by exact name (the timer or a parent skill), not by description-match, so a directive description would only cause false auto-activations. A user-invocable skill with a passive description is the correct shape here, not a defect.

Audit skills (audit-*) must add allowed-tools: Read, Grep, Glob and only the specific Bash verb patterns their workflow runs — read-only verbs, and the spx verification run verbs that write the audit's own run journal — never bare Bash, plus {{! tool('use_skill') !}} when the audit composes another skill. An audit that passes payload files to run-recording commands adds the harness's file-write tool beside its read tools; the tool writes only payload files in the session scratch directory, and the audit changes no file beyond those payload files and the run journal its own recording commands write. Such an audit grants no Bash stage that builds a payload in the shell, and never grants Edit.

Directory match is mandatory. skills/author/ → name: author. A mismatch breaks skill lookup.

Field skills: is NOT supported on SKILL.md. It exists only on subagent definitions (agents/*.md), where it preloads skill content as reference material into the subagent's startup context. The official docs page above lists every field a SKILL.md actually accepts; skills: is not among them. To make a reference skill available to another skill, set user-invocable: false on the reference and have the parent invoke it by installed name through the runtime's skill-invocation surface — there is no preload field on the consumer side.

Command-capability fields. A SKILL.md carries every capability a slash command had — argument-hint/arguments, allowed-tools restriction, plus !-dynamic context and @ file references in the body. The authoring and audit rules for that surface live in ${CLAUDE_SKILL_DIR}/references/command-capabilities.md; read it before authoring a skill that takes arguments, injects state, or restricts tools, and read its <guard_block_partition> when a dangerous-command guard blocks a command.

</frontmatter> {!% else %!} <frontmatter>

Every Codex SKILL.md starts with YAML frontmatter and uses only fields accepted by Codex's current skill validator. name matches the skill directory, description states the selection contract, and tool restrictions grant only capabilities the workflow needs. Do not project Claude-only visibility, preload, heartbeat, hook, or invocation semantics onto Codex fields. Frontmatter declares no model or reasoning override; a skill retains its invoking session's configuration.

Reference skills stay hidden from ordinary user selection while remaining available to composed workflows through Codex's documented skill invocation surface. Audit skills change no file beyond the payload files they write in the session scratch directory and the spx verification run journal their own verbs write. A field or reachability behavior without a documented Codex contract is omitted.

Read ${CLAUDE_SKILL_DIR}/references/command-capabilities.md before authoring arguments, dynamic context, tool restrictions, or file references for Codex, and read its <guard_block_partition> when a dangerous-command guard blocks a command.

</frontmatter> {!% endif %!}

<naming_conventions>

The name field is the user invocation path (/{skill-name}). Match user speech patterns.

Rules:

• Use domain acronyms: author not author-product-tree-artifacts
• Use terms users actually say: test not python-unit-test-framework
• Think "CD-ROM" not "Compact Disc Read Only Memory"
• Directory name MUST match: skills/author/ → name: author

Naming form: invoked workflow skills use imperative verbs. Reference skills use noun phrases ending in the domain they standardize, such as skill-standards or typescript-test-standards.

Vocabulary precedence: Skill-name grammar does not override declared methodology vocabulary. When a term can belong both to a skill-name form and to another taxonomy, read the source that declares that taxonomy and inspect file history before calling the term a naming defect.

Treat generated runtime output and implementation names as lower-layer evidence, never as the authority for vocabulary classification.

# ✅ Matches user speech
name: author # Users say "author a spec"
name: author-typescript-test # Users say "author a TypeScript test"
name: bootstrap # Users say "bootstrap the Product Tree"

# ❌ Nobody says these
name: author-product-tree-artifacts # Too verbose
name: typescript-unit-framework # Wrong order

</naming_conventions>

{!% if target == 'claude' %!} <descriptions>

The description field governs skill selection. Claude has a character budget for all skill metadata — when exceeded, skills become invisible.

This section selects a description's style by invocation path. /agent-prompt-standards <description_style> governs the wording within that style: the directive form, the NEVER clause, artifact-before-language order, and user speech.

Description-match entry points take a directive description.

Reference skills carry a passive description, with the frontmatter <reference_skills> requires.

Protocol and loop-body skills that a parent skill loads, or that a timer fires by exact name (a heartbeat re-entry target), keep a passive description while staying user-invocable — they are never reached by description-match, so a directive description would only cause false auto-activations. See the gate-by-role rules in <frontmatter>.

Audit skills describe the audit they perform: the subject, judgment, and distinguishing criteria. Their descriptions contain no routing, dispatch, preload, agent, or execution-context statement. Audit skills stay model-invocable, carry the allowed-tools <frontmatter> names for them, and never use disable-model-invocation.

description: >-
  Test-evidence audit methodology — judges test evidence against the assertions
  it claims to verify, covering source ownership, coupling, falsifiability, and
  full-chain coverage.

Conflict resolution: If Claude picks the wrong skill, descriptions are too similar. Make trigger terms distinct — "sales data in Excel" vs "log files and system metrics".

</descriptions> {!% else %!} <descriptions>

Descriptions state when Codex selects a skill and distinguish adjacent skills with concrete trigger terms. Use directive wording for description-match entry points and passive wording for references or protocols invoked by exact name. Keep the trigger first, avoid overlapping descriptions, and describe the skill's own subject rather than the caller that reaches it.

</descriptions> {!% endif %!}

<xml_structure>

Skills use pure XML structure — no markdown headings (#, ##, ###) anywhere in the body. Keep markdown formatting within content (bold, italic, lists, tables, code blocks, links).

Why pure XML: unambiguous section boundaries, consistent cross-skill structure, better token efficiency, and more reliable runtime interpretation.

Required tags (every skill):

Tag	Content
<objective>	The observable output the skill produces, in a definite shape — one sentence, not an actor or an activity, not a summary of the skill. See /agent-prompt-standards <objective_shape>.
<success_criteria>	The properties that prove the output is sound — not a re-list of the workflow steps.

Router-pattern tags (skills that route to multiple workflows):

Tag	Content
<essential_principles>	Principles that apply regardless of which workflow runs. Inline.
<intake>	Question to ask the user to determine routing.
<routing>	Table mapping responses to workflow files.
<reference_index>	List of available reference files.
<workflows_index>	List of available workflow files.

Workflow-file tags (files inside workflows/):

Tag	Content
<required_reading>	Which reference files to load before running this workflow.
<process>	Step-by-step procedure.
<success_criteria>	When this workflow is complete.

Conditional tags (include when the skill's complexity or purpose calls for them):

Tag	When to include
<quick_start>	Tool skills with a meaningful fast path. Omit for foundation, gate, validator, and reference skills — completeness is the point.
<context>	Background needed before starting.
<workflow>	Sequential steps (non-router skills).
<advanced_features>	Progressive disclosure for deep-dive topics.
<validation>	Verification checks.
<examples>	Input/output pairs.
<anti_patterns>	Common mistakes to avoid.
<security_checklist>	Skills with security implications.
<testing>	Testing workflows or validation steps.
<common_patterns>	Reusable recipes.
<reference_guides>	Pointers to detailed reference files.
<failure_modes>	Named failures from actual usage — what happened, why, how to avoid.

This table is representative, not exhaustive: a skill may add semantically named domain sections beyond it (this file's <frontmatter>, <descriptions>, and reference-pointer sections such as <platform_constraints> and <script_standards> are examples).

Nesting: XML tags can nest for hierarchical content.

<examples>
  <example number="1">
    <input>User input</input>
    <output>Expected output</output>
  </example>
</examples>

Close every tag. Unclosed tags break parsing.

<context> bash blocks fire on every skill load. ${CLAUDE_SKILL_DIR}/references/command-capabilities.md <dynamic_context> carries the firing and filtering rules.

Semantic names: <workflow> not <steps>, <success_criteria> not <done>, <anti_patterns> not <dont_do>.

Reference tags in prose by name: "Using the schema in <schema> tags…", "Follow the workflow in <workflow>…". Makes structure self-documenting.

Intelligence rules — match structure to complexity:

Skill class	Expected tags
Simple (single domain)	<objective>, <success_criteria>, optionally <quick_start>
Medium (multiple patterns)	Required + <workflow> and/or <examples>
Complex (multi-domain, API, sec)	Required + router pattern + appropriate conditional tags
Foundation / gate / validator	Required + <workflow>. Omit <quick_start> — no abbreviated path exists.
Reference	Required; add <workflow> only when the reference defines an ordered procedure. A declarative standards or vocabulary catalog omits procedural tags.
Auditor (agent-preloaded)	The canonical auditor skeleton — read ${CLAUDE_SKILL_DIR}/references/auditor-skeleton.md when authoring or auditing an audit-* skill. Omit <quick_start>.

Don't over-engineer simple skills. Don't under-specify complex ones.

</xml_structure>

<eager_foundation_exception>

When a foundation skill requires the same material on every fresh invocation, inline that canonical material and govern the total eager payload instead of the SKILL.md line count. The exception requires the same material on every invocation, removal of mandatory secondary reads, separate conditional detail, internal consistency, improved effectiveness, and a rendered payload of at most 40,000 Unicode code points measured by every audit. Never use it to inline optional detail or avoid routing.

</eager_foundation_exception>

{!% if target == 'claude' %!} <progressive_disclosure>

SKILL.md is an overview. Reference files carry detail. Claude loads reference files only when needed.

Rules:

• Keep SKILL.md under 500 lines unless <eager_foundation_exception> applies.
• References live in references/ one level deep from SKILL.md. Do not nest references that read other references — Claude may only partially read transitive files.
• Reference files over 100 lines need a table of contents at the top, so partial reads still see the full scope.
• Use forward slashes in every path — references/guide.md, never references\guide.md. Works across platforms.

Apply <eager_foundation_exception>. A 500-line overview followed immediately by mandatory references is not progressive disclosure; total eagerly loaded content is the relevant cost.

Token efficiency: simple task loads SKILL.md only (~500 tokens); medium loads SKILL.md + one reference (~1000); complex loads SKILL.md + multiple (~2000+).

✅ One level deep
SKILL.md → references/advanced.md (complete info)
         → references/examples.md (complete info)

❌ Nested
SKILL.md → references/advanced.md → references/details.md → actual info

Name reference files descriptively — xml-structure-examples.md, not examples.md. The filename is also a table-of-contents entry in <reference_index>.

Every reference file must be cited. A file in references/ that is not mentioned by SKILL.md or any workflow file is orphaned — it costs ~1,800+ tokens per speculative read (Claude tends to open siblings of cited references) and signals either dead content or a missing cross-reference. Either remove the file with git rm or add an explicit <required_reading> from the workflow that needs it. Verify before committing: grep -rn "<filename>" <skill-dir>/.

</progressive_disclosure> {!% else %!} <progressive_disclosure>

Keep SKILL.md under 500 lines unless <eager_foundation_exception> applies. Move detailed patterns into descriptively named files one level below references/. Cite every bundled reference from the skill or the workflow that requires it. Avoid nested reference chains, orphaned files, and duplicated standards.

Apply <eager_foundation_exception>. A 500-line overview followed immediately by mandatory references is not progressive disclosure; total eagerly loaded content is the relevant cost.

</progressive_disclosure> {!% endif %!}

<conciseness>

Every sentence of a skill and its bundled files meets /agent-prompt-standards <conciseness>, which owns the sentence-removal test, what to omit and include, and concrete-over-abstract guidance.

</conciseness>

<skill_types>

Six skill types. Each has a distinct purpose and primary output.

Type	Purpose	Primary output	Key sections
Builder	Create new artifacts	Code, documents, widgets, configs	Required clarifications, output spec, domain standards, templates in assets/
Guide	Teach procedures	Step-by-step workflows, tutorials	Numbered workflow, input→output example pairs, decision trees
Automation	Execute multi-step processes	Processed files, transformed data	Tested scripts in scripts/, error handling, dependencies, I/O contracts
Analyzer	Extract insights	Reports, summaries, reviews	Analysis scope, evaluation criteria, output format, synthesis
Validator	Enforce quality	Pass/fail verdicts, scores	Criteria with thresholds, scoring rubric, remediation guidance; user-invocable: false when invoked only by agents or explicit runtime skill invocation
Reference	Share domain knowledge	Standards loaded by other skills	user-invocable: false, passive description, read-only capabilities

Type-selection rule of thumb:

• Creates new artifacts → Builder
• Teaches how-to → Guide
• Executes processes → Automation
• Extracts insights → Analyzer
• Checks quality → Validator
• Shares knowledge multiple skills need → Reference

</skill_types>

<reference_skills>

Reference skills hold shared domain knowledge that multiple skills need. Consuming workflows state each one as the instruction Use skill `{plugin}:{skill}`. per the composed-dependency rule in <skill_organization>. A /{skill-name} mention in prose records the dependency but never loads the reference.

When to create a reference skill. Two or more skills in the same plugin need the same domain knowledge (standards, patterns, anti-patterns, conventions). Alternatives fail: duplicating the content creates maintenance drift, and putting it in one skill's references/ directory makes it unreachable from the other skill's ${CLAUDE_SKILL_DIR}.

Required frontmatter:

---
name: {domain}-standards
user-invocable: false
description: >-
  {Domain} standards enforced across all skills. Loaded by other skills, not invoked directly.
allowed-tools: Read
---

• user-invocable: false — prevents false activations from user prompts.
• Passive description (no ALWAYS/NEVER) — directive descriptions trigger false activations for a reference.
• allowed-tools: Read — reference skills only read. Add the harness's skill-composition tool only when explicitly composing another read-only reference skill.

How consuming skills reference it. Name the reference skill in running text for traceability, then state the dependency as Use skill `{plugin}:{skill}`. before applying its rules. A bare See /{skill-name} instruction is insufficient.

# In author-typescript-test/SKILL.md:

Use skill `typescript:typescript-test-standards`. Apply its test file naming, execution-level, and reusable-pattern rules.

# In audit-typescript-test/SKILL.md:

Before auditing: Use skill `typescript:typescript-test-standards`. Apply its complete catalog of TypeScript test rules.

Naming convention: {domain}-standards for standards. Examples: typescript-test-standards, skill-standards, agent-prompt-standards.

Extraction completeness test. When factoring a standards reference out of a builder/auditor pair, the extraction is complete only when the corresponding audit skill loads the new reference and nothing else for standards. If the auditor still reads files from the builder's references/ directory for standards, content is still stranded there — finish the move. The same rule catches partial extractions: a standards file in a creator skill's references/ directory that the auditor needs is a bug, not an architecture.

</reference_skills>

<templates_and_variables>

The runtime variable scopes and bundled-file path examples live in ${CLAUDE_SKILL_DIR}/references/runtime-variables.md. Read it before referencing bundled files.

{!% if target == 'claude' %!} Hook authoring patterns — the SessionStart + $CLAUDE_ENV_FILE value-propagation mechanism, hook command: paths, and the plugin hooks/ directory layout — live in ${CLAUDE_SKILL_DIR}/references/plugin-hooks.md, which also names $CLAUDE_CODE_SESSION_ID as the agent-published session identity a skill reads without a hook. Read it before wiring hook commands or consuming session identity from a skill. {!% else %!} Codex session-identity guidance for $CODEX_THREAD_ID lives in ${CLAUDE_SKILL_DIR}/references/plugin-hooks.md. Read it before consuming session identity from a skill. {!% endif %!}

</templates_and_variables>

{!% if target == 'claude' %!} <platform_constraints>

Two platform footguns affect skill authoring: dprint's markup_fmt handling of nested code fences, and Claude Code's bash-safety checker for ! expansion. Read ${CLAUDE_SKILL_DIR}/references/platform-constraints.md before using multi-backtick fences or ! command syntax.

</platform_constraints> {!% else %!} <platform_constraints>

Read ${CLAUDE_SKILL_DIR}/references/platform-constraints.md before using multi-backtick fences. Apply only constraints that the reference identifies for Codex.

</platform_constraints> {!% endif %!}

<xml_tag_formatting>

Always add a blank line before a closing pseudo-XML tag that follows an unordered list. Without it, markdown parsers indent the closing tag as part of the last list item.

# ❌ WRONG

<section>

- Item 1
- Item 2
</section>

# ✅ CORRECT

<section>

- Item 1
- Item 2

</section>

</xml_tag_formatting>

<script_standards>

Skills that ship scripts/ must validate inputs with verbose, deterministic, actionable error messages and test every script before inclusion. The full validation-message and script-testing rules live in ${CLAUDE_SKILL_DIR}/references/script-standards.md. Read it before authoring a skill that bundles scripts.

</script_standards>

<path_boundary>

A consumer's harness declares which directories a session may touch: the working directory, any additional working directories, the plugin's own files, and a scratch location. A skill instructs Claude, so every path a skill names becomes a path Claude writes — a skill that names a path outside that set directs the write out of the boundary the operator approved.

Scratch storage comes from a unique-per-invocation source, never a named path. Use mktemp -d or mktemp -t in shell and tempfile.mkdtemp or TemporaryDirectory in Python. Each derives a unique directory from the environment's own temporary root, so no skill ever needs to spell a temporary path. Never write /tmp, /var/tmp, /private/tmp, /private/var/tmp, ~/tmp, $HOME/tmp, ${HOME}/tmp, or a ${TMPDIR:-/tmp} fallback: a fixed path is identical across concurrent invocations, so two runs of the same skill overwrite each other, and it sits outside the declared set. mktemp already resolves an unset TMPDIR, so the fallback spelling buys nothing and reintroduces the literal. Naming the environment's root by variable is portable, but appending a segment to it is not — every invocation in one environment resolves the same root, so $TMPDIR/agent.sock collides exactly as /tmp/agent.sock does, and moving a fixed name between the two roots relocates the collision instead of removing it. Code that creates a scratch directory removes it on every exit path, including failure. Scratch Claude creates through a shell command stays in place: no skill directs Claude to run a deleting command. {!# scratch-path-allow #!}

A payload path is copied, never retyped. An audit-* skill that passes payload files it writes with the file-write tool to run-recording commands requires four steps of the audit:

1. Copy the scratch directory the harness names into each payload path character for character.
2. When a file-write result reports a path that the scratch directory does not contain by whole path components, stop before the command that reads that file and name the reported path.
3. Pass each run-recording command its payload path exactly as the file-write result reports it, written out literally as the argument, never held in a shell variable or expanded.
4. When a command exits nonzero with a diagnostic that names its payload file as absent, run that command once more with the path copied from the file-write result; on a second failure, stop with the blocked result naming the run token.

No payload path is retyped from memory: a path rebuilt by hand differs from the written file by one character, and the command then reads no file. A file a bundled script writes at a path the skill names, such as a start input, has no file-write result: the audit passes it by that path written out literally, and a command whose diagnostic names that file as absent runs no second time.

A write outside the invocation checkout is confirmed before it happens, not resolved and taken. A home-directory configuration path, another repository's checkout, or any location the operator did not name in the request needs confirmation that states the absolute destination. Being able to resolve a path is not authorization to write to it, and one confirmation covers one write — the next asks again. Prefer the in-checkout location whenever both exist, because a write there is reviewable in that repository's history.

One content may name a prohibited path: the rule prohibiting it. A standard listing the spellings an author may not write, or an audit row naming what to flag, states the rule rather than breaking it. Judge the surrounding intent — a path a skill presents as prohibited is not a violation, and a path a skill presents as a step to follow is one regardless of how it is fenced.

A permission prompt is a result, not an obstacle. When a tool layer declines a path, that decline is the boundary working. Never document a way around it — a shell redirect standing in for a refused tool write, a broader permission substituted for a narrow one, a path rewritten to dodge a check. Name a path inside the boundary instead. A skill that teaches evasion converts one operator's approval into every future session's bypass.

An automated classifier's refusal admits one retrace-bound retry. A decline names its source: the operator refusing a permission prompt, a guard — a hook or a dangerous-command guard — naming its rule, or the harness's permission classifier stating that it refused. Apart from the split rerun below, only a classifier refusal of a request the operator's instruction already authorized admits a retry, only where the skill directs one, and only after Claude retraces the request as sent, the classifier's reason, and each step that shaped the request. The retry carries only the correction the retrace found, never a rewording that hides the objection; a second refusal, and every other decline, is the result.

A dangerous-command guard block on a compound command admits one split rerun. A block on a command holding one operation with every string written literally ends that command family, and so does a block on a command whose composition the parts cannot carry: a process substitution, a pipe between two operations, a background &, a subshell, or a list that mixes && and ||. A block on a compound command — lists separated by ; or a newline, parts joined by && alone or by || alone, and shell expansions — admits one rerun of its parts one at a time, in their original order, with every string written literally; a part the guard blocks on its own ends that part's family. ${CLAUDE_SKILL_DIR}/references/command-capabilities.md <guard_block_partition> defines the three outcomes and how each value resolves to a literal. The rerun needs no skill's direction and is the only retry a guard decline admits.

</path_boundary>