# Deep Skill Audit Checks

`audit.sh` runs the structural `heal.sh --check --strict` pass, eight content
checks, an advisory static package-readiness score, and advisory craft
instrumentation. The checks protect usability without rewarding ceremony or
package size.

Executable thresholds and severities come from
`skills/skill-builder/references/skill-conformance-profiles.yaml`.

## Verdicts

| Severity | Result |
|---|---|
| FAIL | The skill contract is incomplete or unsafe. |
| WARN | A concrete usability issue should be reviewed. |
| PASS | No configured defect was found. |

`--strict` makes WARN exit nonzero. Advisory scoring never changes the verdict.

## Checks

### `description-has-triggers` and `trigger-clarity` (WARN)

The frontmatter description must state when the skill should load. Accepted
forms are an inline or block `Triggers:` / `Use when:` marker, or—for the first
check only—a `metadata.triggers` list accepted by the active profile.

### `constraints-frontloaded` (WARN)

Skills longer than 100 lines need an early `Constraints` or `⚠️` section within
the first 80 body lines. Concise kernels pass without a ceremonial section
because their boundaries are already visible in one read.

### `rationale-present` (WARN)

When a constraints section contains bullets, at least half should explain why
the constraint exists. A skill with no constraint bullets passes this check.

### `verification-checkpoints` (WARN)

A workflow with two or more named subphases should contain a checkpoint or an
explicit verify-before boundary. One-step procedures pass without a checkpoint.

### `output-spec-explicit` (FAIL)

A nonempty frontmatter `output_contract` passes. Skills without that AgentOps
field must instead provide one output section containing every component
required by the selected profile. This lets small inline adapters declare a
sentence-shaped result without inventing an artifact directory, filename,
schema, validator, and downstream controller.

### `quality-rubric` (WARN)

Skills longer than 100 lines need at least three bullets under `Quality`,
`Checks`, `Checklist`, `Rubric`, `Best Practices`, or `Acceptance`. Concise
kernels pass because their evidence and stop conditions are directly visible.

### `references-modularization` (WARN)

The canonical repo-runtime kernel limit is 250 lines. Move genuinely detailed
material into linked references instead of expanding the always-loaded kernel.

## Craft instrumentation (Pass 4, advisory)

`craft_score.py` adds three advisory blocks to the report. None of them ever
changes the verdict or exit code; they name gaps for the author and the fresh
validator to judge.

- **Craft score** — presence of the 12 craft elements enumerated in
  [skill-template.md](skill-template.md) section 7, reported as
  `craft n/12; missing: <element-ids>`. Detection is cheap pattern matching
  over authored prose (HTML comments are stripped, so `init.sh` scaffold stubs
  never count). Presence, never quality.
- **Provenance resolution** — repo paths and `.agents/ao` verdict/intent digest
  citations (full or abbreviated `prefix...suffix`) extracted from prose must
  resolve against the repository; each dead citation is a named finding.
  Fenced code blocks are treated as examples, not citations.
- **Loop safety** — any section with iteration prose (`repeat`, `iterate`,
  `loop`) must contain a checkable stop-condition phrase (`stop after`,
  `at most N`, `until ... exit 0`); an agent-dispatch loop must also carry a
  budget phrase. Vague goals ("until it feels done") do not count as stop
  conditions.

The scorer's detection power is itself mutation-tested:

```bash
bash skills/skill-builder/scripts/test-craft-mutations.sh
```

## Authoring prose scan (Pass 5, advisory)

`authoring_scan.py` adds an advisory `authoring` block naming mechanical
suspects for three failure modes from
[authoring-doctrine.md](authoring-doctrine.md). Like density and craft, it
never changes the verdict or exit code — the no-op test is model-relative and
prohibitions are sometimes correct guardrails, so a human (or fresh validator)
owns the judgment.

- **`noop-phrase`** — phrasing the model already obeys by default ("be
  thorough", "make sure to", "carefully"), reported with the offending line.
  The fix is a sharper, behavior-changing instruction, not a louder wish.
- **`negation-without-positive`** — a bullet/paragraph whose every clause
  prohibits ("Never edit generated files.") with no positive counterpart in
  the same unit. Pairing the prohibition with the target behavior ("Edit the
  source and regenerate; never edit generated files directly.") clears it.
- **`step-missing-done-condition`** — a `###` subphase under a
  Workflow/Process/Methodology/Execution section with no checkable
  done-condition phrasing ("Done when", "Checkpoint:", "Stop after",
  "until ... exit 0"). One finding per offending subphase.

Detection power is mutation-tested:

```bash
bash skills/skill-builder/scripts/test-authoring-mutations.sh
```

## Calibration rule

Before tightening a check, run it across every canonical skill. A proposed
rule that fails valid concise skills is miscalibrated unless the repository
contract itself requires those skills to change. Do not add boilerplate solely
to satisfy a heuristic.

```bash
for skill in skills/*; do
  [[ -f "$skill/SKILL.md" ]] || continue
  bash skills/skill-builder/scripts/audit.sh "$skill" >/dev/null
done
```

# Skill Authoring Doctrine

Principles for writing `SKILL.md` bodies so an agent follows the same
*process* on every run. Structure (frontmatter, sections, output contracts)
lives in [skill-template.md](skill-template.md) and
[audit-checks.md](audit-checks.md). This reference governs the sentences
inside that structure. The deep audit's advisory `authoring` block
(see [audit-checks.md](audit-checks.md)) mechanically flags three detectable
failure modes; everything else is author judgment.

Idea provenance: distilled clean-room from the skill-authoring ideas at
<https://github.com/mattpocock/skills> (MIT). Concepts only — no upstream
prose, names, prompts, scripts, or examples are reproduced here.

## 1. The no-op test

A sentence belongs in the skill only when it alters what the agent would
otherwise do. Vague intensifiers such as "be thorough" fail: they spend
tokens without changing the default. Prefer a concrete, observable
instruction ("read every `references/*.md` before editing") or a single
strong pretrained cue the model already knows how to obey.

Whether a line is load-bearing depends on the model. Authors who disagree
should settle it by executing the skill, not by debating intent. Because of
that relativity, the audit's `noop-phrase` finding is advisory: it names
suspects from a fixed phrase list; the author decides.

## 2. Negation

Telling the agent what to avoid tends to surface the forbidden pattern in
context and raise its salience. Prefer naming the desired behavior
("write one-line comments") so the unwanted pattern is never primed.

Hard bans remain valid when nothing positive can replace them (this
repository's ban on `claude -p` is one). Even then, put the recovery path
in the same paragraph — ban plus what to do instead — which matches this
repo's "Anti-pattern: X. Corrective: Y" habit. The audit's
`negation-without-positive` finding flags a paragraph where every clause
forbids and none directs.

## 3. Completion criteria

End each workflow step on a condition the agent can evaluate, and make that
condition cover the whole obligation. Two properties matter:

- **Checkable** — done vs not-done is decidable. "Understanding reached" is
  not; "every changed path appears in the manifest" is.
- **Exhaustive** — the bar covers the full duty. "Produce a change list"
  allows a partial list; "every modified file accounted for" does not.

A fuzzy exit invites *premature completion*: attention drifts from the work
to finishing, and the step ends early. Tighten the exit criterion before
restructuring the skill — that is the cheap local fix. The audit's
`step-missing-done-condition` finding flags workflow subphases that lack any
done phrasing ("Done when", "Checkpoint:", "Stop after", "until … exit 0").

## 4. Leading words

A leading word is one pretrained concept token that holds a behavioral
region: *tight* (loop), *red* (failing check), *fresh* (context),
*frontier*, *quarantine*. Used as a token — not re-explained each time —
it builds a shared meaning across the skill and leans on priors the model
already has, buying behavior for almost no context cost.

Look for restated qualities that want collapsing: three near-synonyms for
"fast and deterministic" are one idea; *tight* says it once. Invented terms
need a single clear definition; pretrained words are free. A leading word
that does not beat the model's default is itself a no-op — strengthen the
word rather than adding more prose.

## 5. Description discipline

The frontmatter description loads every turn, so prune it hardest. It has
two jobs: name what the skill does, and list genuinely distinct trigger
branches. One trigger per branch — synonym padding for the same branch is
duplication that burns context and dulls matching. Prefer trigger wording
callers actually use, especially shared leading words, so the description
aligns with real prompts. This sharpens, rather than replaces, the
structural `description-has-triggers` and `trigger-clarity` checks.

## 6. Context load vs cognitive load

Every skill bills one of two accounts. A model-discoverable skill keeps its
description in the window every turn — a standing **context load** whether
or not it fires. A human-only skill costs nothing per turn but spends
**cognitive load**: the human indexes which skills exist and when to call
them.

Choosing the account is a required authoring decision. This repository
already exposes the levers: `user-invocable` frontmatter, `tier` and
`disposition` metadata, and the generated router (`docs/SKILL-ROUTER.md`)
that reduces cognitive load once human-reached skills multiply. Prefer
model discovery only when autonomous reach or cross-skill invocation is
required; otherwise keep the window clean. Splitting one skill into several
also spends one of those loads — split only when a distinct trigger
vocabulary or independently reachable behavior pays for the new entry.

## Applying the doctrine

When creating or healing a skill, walk the body once per principle: remove
no-op lines, convert bare bans into positive targets (keeping paired
guardrails), give each workflow step a checkable exhaustive exit, collapse
restatements into leading words, prune the description to one trigger per
branch, and confirm the intended load account. The advisory `authoring`
audit block names the mechanical suspects; the author owns the judgment
calls.

# Codex Parity Repair

Use this workflow when `skills/<name>/SKILL.md` is canonically correct but
`skills-codex/<name>/SKILL.md` has drifted into bad Codex UX in the checked-in runtime artifact.

## Principles

1. `skills/<name>/SKILL.md` remains the canonical workflow contract.
2. `skills-codex/<name>/` is the checked-in Codex runtime artifact and may need direct maintenance.
3. Durable Codex-only body edits that should survive broader refactors belong in `skills-codex-overrides/<name>/SKILL.md`.
4. Codex operator-layer prompt edits belong in `skills-codex-overrides/<name>/prompt.md`.

## Audit First

Run:

```bash
bash scripts/audit-codex-parity.sh
```

Or target one skill:

```bash
bash scripts/audit-codex-parity.sh --skill swarm
```

The audit flags the failure classes that Codex maintenance keeps missing today:

- Claude-era task primitives
- Claude-only backend reference names and team terminology
- duplicated runtime phrases created by blind search/replace

## Repair Loop

For each flagged skill:

1. Read `skills/<name>/SKILL.md` to confirm whether the canonical contract is correct.
2. Read `skills-codex/<name>/SKILL.md` to see the broken checked-in Codex body.
3. Read `skills-codex-overrides/<name>/prompt.md` and `skills-codex-overrides/catalog.json`.
4. If the source contract is wrong, fix `skills/<name>/SKILL.md` first.
5. If the shipped Codex artifact is wrong, update `skills-codex/<name>/SKILL.md`.
6. If the source is correct but Codex needs a durable tailoring layer, create or update `skills-codex-overrides/<name>/SKILL.md`.
7. Re-run validation:
   - `bash scripts/audit-codex-parity.sh`
   - `bash scripts/validate-codex-generated-artifacts.sh --scope worktree`
   - `bash scripts/validate-codex-override-coverage.sh`

## LLM Repair Guidance

When doing the actual rewrite, the LLM should:

- preserve the behavior contract from `skills/<name>/SKILL.md`
- remove Claude-only primitive/tool names from the Codex body
- replace mechanical rewrites with real Codex-native instructions
- keep durable Codex-only delta in `skills-codex-overrides/<name>/SKILL.md` when it should remain distinct from the checked-in artifact

If a skill keeps needing Codex-only body surgery, update
`skills-codex-overrides/catalog.json` so the treatment matches reality instead
of pretending the skill is still parity-only.

# Advisory Context Density Checks

This reference defines the density block of skill-builder's deep audit mode
(absorbed from the retired `/skill-auditor`). It is report-only.
It helps reviewers find skill prose that does not carry one of the six Context
Density Rule fields before that prose is passed into a fresh context session.

## Fields

| Field | Meaning | Advisory signals |
|---|---|---|
| `intent` | What behavior or capability the skill is trying to produce | intent, goal, behavior, capability |
| `boundary` | Where the work starts/stops | boundary, bounded context, write scope, non-goal |
| `evidence` | How the skill knows work is true or complete | evidence, test, verdict, validation, acceptance |
| `decision` | Why this approach was chosen | decision, rationale, why, because, chosen |
| `constraint` | Limits, safety rails, and non-negotiables | constraint, guardrail, limit, scope |
| `next_action` | The next command, artifact, or handoff | next action, next steps, completion marker |

## Behavior

- Missing fields produce `density.status: "warn"`.
- Missing fields do not change the aggregate audit verdict.
- Missing fields are not CI failures.
- False positives should be recorded as findings or bead notes before any check
  is promoted.
- This check does not satisfy execution-packet enforcement. The packet-boundary
  invariant is owned by `soc-2c1p.1`.

## Runnable Examples

```bash
bash skills/skill-builder/scripts/audit.sh skills/plan
bash skills/skill-builder/scripts/audit.sh skills/implement
bash skills/skill-builder/scripts/audit.sh skills/validate
```

The expected result is a JSON `density` object with six `fields[]` entries. The
field count is the contract; the individual pattern matches are advisory.

version: 1
default_profile: repo-runtime
profiles:
  repo-runtime:
    id: repo-runtime
    kernel_max_lines: 250
    trigger_forms:
      accepted:
        - inline-marker
        - block-marker
        - metadata-list
      description_markers:
        - "Triggers:"
        - "Use when:"
      metadata_list_min_items: 3
    output_contract:
      section_headings:
        - Output
        - Output Specification
        - Output Format
        - Deliverables
        - Returns
      required_components:
        artifact-path:
          markers:
            - "artifact directory"
            - "**path:**"
            - ".agents/"
            - "stdout"
        filename-convention:
          markers:
            - "filename convention"
            - "**filename:**"
        serialization-schema:
          markers:
            - "serialization/schema format"
            - "**format:**"
            - "schema"
        validator-command:
          markers:
            - "validator command"
            - "**exit code:**"
            - "validation command"
            - "validate with"
        downstream-handoff:
          markers:
            - "downstream handoff"
            - "consumed by"
            - "confirming the fixture loaded"
    clean_room:
      enabled: true
      external_content_policy: observe-structure-only
      prohibited_copy_categories:
        - prose
        - prompts
        - scripts
        - examples
        - names
      copy_detection:
        minimum_fragment_characters: 24
        minimum_name_characters: 8
        protected_frontmatter_fields:
          - description
        ignored_exact_lines:
          - "---"
        ignored_line_prefixes:
          - "#"
    rule_order:
      - description-has-triggers
      - constraints-frontloaded
      - rationale-present
      - verification-checkpoints
      - output-spec-explicit
      - quality-rubric
      - references-modularization
      - trigger-clarity
    rules:
      description-has-triggers:
        severity: WARN
        accepted_forms:
          - inline-marker
          - block-marker
          - metadata-list
      constraints-frontloaded:
        severity: WARN
      rationale-present:
        severity: WARN
      verification-checkpoints:
        severity: WARN
      output-spec-explicit:
        severity: FAIL
      quality-rubric:
        severity: WARN
      references-modularization:
        severity: WARN
      trigger-clarity:
        severity: WARN
        accepted_forms:
          - inline-marker
          - block-marker
  external-observation:
    id: external-observation
    kernel_max_lines: 250
    trigger_forms:
      accepted:
        - inline-marker
        - block-marker
        - metadata-list
      description_markers:
        - "Triggers:"
        - "Use when:"
      metadata_list_min_items: 3
    output_contract:
      section_headings:
        - Output
        - Output Specification
        - Output Format
        - Deliverables
        - Returns
      required_components:
        filename-convention:
          markers:
            - "filename convention"
            - "**filename:**"
        serialization-schema:
          markers:
            - "serialization/schema format"
            - "**format:**"
            - "schema"
    clean_room:
      enabled: true
      external_content_policy: observe-structure-only
      prohibited_copy_categories:
        - prose
        - prompts
        - scripts
        - examples
        - names
      copy_detection:
        minimum_fragment_characters: 24
        minimum_name_characters: 8
        protected_frontmatter_fields:
          - description
        ignored_exact_lines:
          - "---"
        ignored_line_prefixes:
          - "#"
    rule_order:
      - description-has-triggers
      - constraints-frontloaded
      - rationale-present
      - verification-checkpoints
      - output-spec-explicit
      - quality-rubric
      - references-modularization
      - trigger-clarity
    rules:
      description-has-triggers:
        severity: WARN
        accepted_forms:
          - inline-marker
          - block-marker
          - metadata-list
      constraints-frontloaded:
        severity: WARN
      rationale-present:
        severity: WARN
      verification-checkpoints:
        severity: WARN
      output-spec-explicit:
        severity: FAIL
      quality-rubric:
        severity: WARN
      references-modularization:
        severity: WARN
      trigger-clarity:
        severity: WARN
        accepted_forms:
          - inline-marker
          - block-marker

# Unified SKILL.md Template + Auditor Checklist

> **Authority:** Executable rule IDs, severities, trigger forms, output-handoff
> requirements, clean-room behavior, and the 250-line limit come from
> [skill-conformance-profiles.yaml](skill-conformance-profiles.yaml).

This is the canonical template `skill-builder` materializes and its deep audit mode validates against. Two artifacts in one document because both modes need identical truth.

This template governs *structure*. The prose inside that structure is governed
by [authoring-doctrine.md](authoring-doctrine.md) — the no-op test, negation,
completion criteria, leading words, description discipline, and the context
load vs cognitive load decision. Apply both when authoring or healing a skill.

---

## 1. Canonical SKILL.md template

```markdown
---
name: <slug-with-hyphens>
description: |
  <one-line: verb + object + domain>

  **Use when:**
  - <Trigger 1>
  - <Trigger 2>

  **Perfect for:**
  - <Scenario 1>

  **Not ideal for:**
  - <Anti-scenario 1>
skill_api_version: 1
user-invocable: <true|false>
context:
  window: <isolated|fork|inherit>
  intent:
    mode: <none|task|questions>
  sections:
    exclude: [HISTORY]
metadata:
  tier: <judgment|execution|library|session|product|contribute|meta|background|orchestration|cross-vendor|knowledge>
  dependencies: [<other-skill-names>]
  stability: <experimental|stable>
output_contract: <path-to-schema-or-description>
---

# <Title matching slug>

<1-2 sentence purpose paragraph>

## Overview / When to Use

<Detailed explanation of what + why + when>

## ⚠️ Critical Constraints

<Safety rules, data quality, governance — front-loaded, NOT buried>

- **Rule N:** <constraint>. **Why:** <rationale tied to a real consequence>

## Workflow / Methodology

<Step-by-step with verification checkpoints between phases>

### Phase 1: <name>
<instructions>
**Checkpoint:** <what to confirm before next phase>

### Phase 2: <name>
...

## Output Specification

<Complete executable handoff>

**Artifact directory:** <directory or path>
**Filename convention:** <naming convention>
**Serialization/schema format:** <format and schema>
**Validator command:** <exact validator invocation>
**Downstream handoff:** <consumer or next workflow>

## Quality Rubric

<Checklist of deliverable criteria + sanity checks + common mistakes>

- [ ] <Check 1>
- [ ] <Check 2>

## Examples

<Usage scenarios>

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|

## See Also / References

<Cross-skill links + references/*.md links>
```

---

## 2. Auditor 15-check checklist

Audits run in **two passes**. Pass 1 runs `heal.sh --check --strict` for structural hygiene and gates on the exit code. Pass 2 adds 8 NEW checks not covered by heal.

### Pass 1 — delegated to heal.sh (7 checks)

| Check | heal.sh code | Severity |
|-------|--------------|----------|
| Frontmatter `name` present | MISSING_NAME | FAIL |
| Frontmatter `description` present | MISSING_DESC | FAIL |
| `name` matches directory | NAME_MISMATCH | FAIL |
| All `references/*.md` linked from SKILL.md | UNLINKED_REF | WARN |
| References point at existing files | DEAD_REF | WARN |
| Scripts referenced exist | SCRIPT_REF_MISSING | WARN |
| User-invocable in dispositions ledger | MISSING_DISPOSITION | FAIL in strict mode |

### Pass 2 — 8 NEW checks beyond heal.sh

> The check id `description-has-triggers` (NOT `description-multiline`) is the canonical name. AgentOps' established convention is single-line `description: '...'`; the auditor must NOT false-fail that style. Three valid forms are accepted (any one passes).

| # | Check id | What passes | Severity |
|---|----------|-------------|----------|
| 1 | `description-has-triggers` | A profile-accepted marker inside the description value, or a metadata list meeting the profile minimum | Profile |
| 2 | `constraints-frontloaded` | Kernels over 100 lines put `Constraints` or `⚠️` within the first 80 body lines; concise kernels pass | Profile |
| 3 | `rationale-present` | Each constraint bullet contains `why`, `because`, `this matters`, or similar rationale token | Profile |
| 4 | `verification-checkpoints` | If skill has multi-phase Workflow/Methodology, body contains `Checkpoint`, `confirm`, or `Wait for` markers between phases | Profile |
| 5 | `output-spec-explicit` | Nonempty `output_contract`, or one output section supplies every profile-required component | Profile |
| 6 | `quality-rubric` | Kernels over 100 lines have 3+ bullets under Quality/Checks/Checklist/Rubric/Best Practices/Acceptance; concise kernels pass | Profile |
| 7 | `references-modularization` | SKILL.md is at or below the profile's 250-line kernel limit | Profile |
| 8 | `trigger-clarity` | Frontmatter `description` contains a profile-accepted marker an LLM can match | Profile |

### Verdict rule

```
fails > 0   → FAIL
warns > 0   → WARN
otherwise   → PASS
```

---

## 3. PRODUCT.md alignment mapping

Each NEW Pass-2 check maps to AgentOps' design principles in PRODUCT.md, so the auditor enforces architectural intent rather than arbitrary stylistic preferences.

| Auditor check | PRODUCT.md anchor |
|---------------|-------------------|
| `constraints-frontloaded` (⚠️ near top) | Operational Principle #6 (atomic changes compose) — constraint visibility prevents large rework |
| `rationale-present` | Operational Principle #1 (agents are ephemeral; system carries state) — rationale must be inside the artifact, not in human memory |
| `verification-checkpoints` | Operational Principle #5 (two-tier execution) — checkpoints prevent worker drift between phases |
| `output-spec-explicit` | Pillar #4 (Kubernetes control loops) — declared state must be machine-readable |
| `quality-rubric` | Operational Principle #3 (context quality determines output quality) |
| `references-modularization` | Finding `f-2026-05-01-025` (SKILL.md churn budget — every Skill() invocation reloads 5-15KB) |
| `trigger-clarity` | Operational Principle #1 (agents are ephemeral) — invocation criteria must be in artifact |
| `description-has-triggers` (renamed from `description-multiline`) | Product surfaces — structured invocation criteria make the right capability discoverable without loading every skill body. Three valid forms preserve AgentOps' single-line convention. |

---

## 4. Section spine — REQUIRED order

```
H1 title
└── Overview / When to Use
└── ⚠️ Critical Constraints      ← MUST appear within first 80 lines after frontmatter
└── Workflow / Methodology       ← MUST contain checkpoints between phases when multi-phase
└── Output Specification         ← MUST include the complete executable handoff
└── Quality Rubric               ← MUST contain 3+ bullets
└── Examples
└── Troubleshooting
└── See Also / References
```

The `## Examples` and `## Troubleshooting` sections are recommended but not enforced (heal.sh catches missing references; the auditor leaves these to taste).

---

## 5. Frontmatter requirements (cross-reference)

Validates against `schemas/skill-frontmatter.v1.schema.json`. Required fields:

- `name` (string, lowercase-hyphen, must match directory)
- `description` (string, see check #1 for accepted forms)
- `skill_api_version` (integer, const: 1)

Plus expected:

- `metadata.tier` (one of the 11 enum values)
- `context.window` (one of: `isolated`, `fork`, `inherit`)
- `output_contract` (path to JSON Schema or description string)

---

## 6. Codex parity contract (per learning `2026-05-03-codex-skill-shape-is-dual-file`)

For every shipped AgentOps skill, both files must exist:

- `skills-codex/<name>/SKILL.md` — slim frontmatter (NO `skill_api_version`)
- `skills-codex/<name>/prompt.md` — short Execution Profile (~10-20 lines)

`scripts/audit-codex-parity.sh` is a content scanner; it will NOT catch frontmatter shape violations. Explicit grep checks (no `skill_api_version:` in codex SKILL.md; `prompt.md` exists) belong in the skill's own validation block.

---

## 7. The 12 craft elements (advisory Pass-4 instrumentation)

`scripts/craft_score.py` detects the presence of these 12 authoring elements
(never their quality) and reports an advisory `craft n/12` with named gaps in
the deep audit. `scripts/init.sh` scaffolds one `<!-- craft:<id> ... -->` stub
per element; the scorer strips HTML comments, so stubs never satisfy an
element — only authored prose counts.

| # | Element id | One-line authoring prompt |
|---|------------|---------------------------|
| 1 | `causal-insight-line` | State the one causal insight that makes this skill work (`Insight:` / `**Why:**` / a `because` clause). |
| 2 | `named-failure-mode` | Name the concrete failure mode this skill exists to prevent (`fails when`, `failure mode`, a Failure behavior section). |
| 3 | `frozen-prompts` | Provide any reusable prompt as a fenced block marked copy-paste-only. |
| 4 | `named-loop-stop-condition` | If the skill iterates, name the loop and give a checkable stop condition in the same section (`stop after`, `at most N passes`, `until ... exit 0`). |
| 5 | `quantified-rules` | Quantify at least one rule with a number and unit (`at most 3 attempts`, `250 lines`). |
| 6 | `negative-space` | State what this skill is NOT for (`non-goals`, `not for`, `do not use when`). |
| 7 | `anti-pattern-with-corrective` | Pair each anti-pattern with its corrective in the same section (`avoid X; instead Y`). |
| 8 | `provenance-citation` | Cite at least one resolvable source: a repo path or a `.agents/ao` verdict/intent digest (abbreviated `prefix...suffix` accepted). |
| 9 | `measurable-done` | Give a machine-checkable done signal (`done when`, `exit 0`, a validator command). |
| 10 | `router-shape` | Map trigger phrases to modes/entry points in a routing table or Modes section. |
| 11 | `trigger-rich-description` | Put `Triggers:` / `Use when` phrases callers actually say in the frontmatter description. |
| 12 | `runnable-commands` | Include at least one fenced block with runnable commands. |

---

## 8. Out-of-scope for v1 (stocktake territory)

The following deeper audits are described in a future `skills/skill-builder/references/skill-stocktake.md` but NOT yet implemented anywhere — defer to v2:

- Actionability (does it produce concrete artifacts?)
- Scope fit (right tier for the task?)
- Uniqueness (overlap with other skills?)
- Currency (referenced tools/APIs still current?)
- LLM-decidable trigger clarity (deeper than `trigger-clarity` check above)