Skill Update

Generate or refine Claude Code skills following Anthropic best practices.

Hard caps (enforced by `scripts/skill_linter.py`)

SKILL.md ≤ 150 lines
reference/*.md ≤ 200 lines (reference/scenarios/*.md ≤ 400 lines)
README.md ≤ 100 lines
Every SKILL.md has YAML frontmatter with name + description
No DO NOT / MUST NOT / NEVER outside an ## Anti-Patterns section
No challenge-specific identifiers (machine names, lab IDs, lab IPs, preserved flags)
Every Markdown link resolves to an existing file
Every reference file is linked from at least one other file (no orphans)

Principles

Brevity first. Every file short, simple, human-readable. Challenge every token.
Progressive disclosure. SKILL.md navigates; reference/ holds detail; reference/scenarios/ holds concrete exploit flows.
Separation of concern. SKILL.md = WHAT + when. reference/role-*.md = HOW agents behave when spawned.
Single canonical home for any cross-cutting rule (output discipline, credential loading, brute-force, etc.). Other files reference, never restate.

File structure

skills/<skill-name>/
├── SKILL.md           # ≤150 lines, YAML + navigation
├── reference/
│   ├── *-principles.md  # ≤150 lines (decision tree)
│   ├── INDEX.md
│   ├── *.md             # patterns, ≤200 lines
│   └── scenarios/
│       └── <category>/
│           └── *.md     # ≤400 lines, self-contained
└── README.md          # optional, ≤100 lines

SKILL.md template

---
name: <skill-name>
description: What it does AND when to use. Include trigger phrases.
---

# <Skill Name>

<one-paragraph scope>

## When to use

- <bullet>

## Workflow / Quick start

<≤30 lines>

## References

- [reference/...](reference/...)

## Anti-Patterns

- <when negative framing is genuinely needed, put it here>

Run it

The procedure is a workflow — every step is code-enforced, so none can be skipped.

Workflow('skill-update', { output_dir: 'projects/<engagement>' })   // harvest an engagement
Workflow('skill-update', { learnings: [{ text, technique_type }] }) // judge a known set
Workflow('skill-update', { mode: 'audit' })                         // read-only, writes nothing

Add dryRun: true to see the write plan without writing. Parent-orchestrator only.

Phases. Intake (baseline skill_linter.py --json) → Harvest (reframe learnings) → Judge (four gates + blind refuters) → Route (author the block) → Write (persist verbatim) → Sweep (confidentiality guard) → Verify (linter delta, not an absolute clean tree — the base carries pre-existing violations).

Every promote/reject/write decision is pure JS in .claude/workflows/lib/wf-helpers.mjs (promotionGate, capBudget, writeGate, lintDelta, skillUpdateGate). No agent decides whether a learning is promoted or a write is allowed.

The four-gate promotion test

Process the techniques and failure modes from completed engagements. Promote a learning to the skill base only if all four hold:

Generalizable. Reusable pattern, not target-specific lore. No machine names, lab IDs, target IPs, preserved flags, writeup attributions.
Material improvement. Adds coverage, efficiency, or decision-quality for future engagements.
Not already captured elsewhere in the skill base. (scripts/skill_linter.py flags duplicates.)
Minimal footprint. Prefer extending an existing entry over adding a new file. Keep the base lean and high-signal.

Reframing recipe

Always frame as a reusable pattern: "when encountering X condition, try Y approach" — never "on box-N, Y worked". Use <TARGET_IP>, <DC_FQDN>, <DOMAIN> placeholders in tool examples.

Output

Three buckets, built in code so a run cannot claim an edit it did not make: Updated. / Skipped. (with the gate that failed) / No changes.

Reference

STRUCTURE.md — directory layout requirements.
FRONTMATTER.md — YAML rules.
CONTENT.md — writing guidelines.
ROUTING.md — technique type → target file.

Anti-Patterns

Creating CHANGELOG.md / SUMMARY.md / VERIFICATION.md auxiliary files.
Meta-documentation about the creation process inside the skill itself.
Verbose inline templates and examples (link to reference/ instead).
Re-introducing duplicate rule prose (brute-force, output-dir, env-reader).
Files past their cap — split into reference/ immediately.

skill-update