@diottodev/runic 1.0.0 → 1.1.0

package/engineering/write-a-skill/skills/write-a-skill/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.
+license: MIT
+metadata:
+  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill"
+  original_author: "Matt Pocock (@mattpocock)"
+  original_license: MIT
+  voice: "Matt Pocock — direct, concrete, imperative, example-driven"
+  version: 1.0.0
+---
+
+# Writing Skills
+
+> Derived from [Matt Pocock's write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) (MIT). Matt's voice and 3-phase workflow preserved verbatim. Additions: validation tools + references + cs-* wrapper (see *Tooling + Companions* below).
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (if needed)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+
+**Goal**: Give your agent just enough info to know:
+
+1. What capability this skill provides
+2. When/why to trigger it (specific keywords, contexts, file types)
+
+**Format**:
+
+- Max 1024 chars
+- Write in third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good example**:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad example**:
+
+```
+Helps with documents.
+```
+
+The bad example gives your agent no way to distinguish this from other document skills.
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...")
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] Concrete examples included
+- [ ] References one level deep
+
+## Tooling + Companions
+
+Validation tools + cs-* wrapper sit alongside this skill. Run all 6 review-checklist items programmatically:
+
+```
+python scripts/skill_review_checklist_runner.py path/to/skill-folder
+```
+
+See [references/companion_tooling.md](references/companion_tooling.md) for the tool catalogue, cs-skill-author persona agent, and `/cs:write-a-skill` slash command.
+
+---
+
+**Version:** 1.0.0
+**Derived:** Matt Pocock (MIT) + this repo's wrapper

package/engineering/write-a-skill/skills/write-a-skill/references/companion_tooling.md

@@ -0,0 +1,67 @@
+# Companion Tooling
+
+Validation tools + cs-* wrapper layered on top of Matt's write-a-skill. Use these when authoring a new skill in this repo.
+
+## Validation Tools (stdlib Python)
+
+| Tool | Purpose | Run before |
+|---|---|---|
+| `scripts/skill_description_validator.py` | Validates description: ≤1024 chars, third person, "Use when" trigger, action verb in first sentence | First draft of SKILL.md |
+| `scripts/skill_structure_validator.py` | Validates folder structure: SKILL.md present, ≤100 lines, references one level deep, no circular refs | Pre-commit |
+| `scripts/skill_review_checklist_runner.py` | Runs all 6 review-checklist items from Matt's write-a-skill against a skill folder | Final check before PR |
+
+All three tools:
+- Stdlib-only (no external dependencies)
+- Run with embedded sample if no path provided
+- Output text or JSON (`--output json`)
+- Exit code: 0 if PASS, 1 if FAIL/WARN
+
+## cs-skill-author Persona Agent
+
+Lives at `../agents/cs-skill-author.md`. Voice: forcing-question interrogator. Surfaces Matt's skill-authoring workflow as an interrogation before any new skill commit.
+
+**Opening question:** "What capability does this skill provide, and what's the trigger phrase that distinguishes it from existing skills?"
+
+**Six forcing questions** (matches the review checklist):
+1. What's the description? Is it ≤1024 chars + third person + has "Use when ..."?
+2. Is SKILL.md under 100 lines? If not, where will the split land (REFERENCE.md / EXAMPLES.md / references/)?
+3. Are there time-sensitive claims (dates, "as of YYYY")?
+4. Is terminology consistent — same word for the same concept throughout?
+5. Concrete examples — at least 1 code block, ideally good/bad contrast?
+6. References one level deep, no circular refs?
+
+## `/cs:write-a-skill` Slash Command
+
+Lives at `../commands/cs-write-a-skill.md`. Three-step flow:
+
+1. Run `cs-skill-author` interrogation (6 questions)
+2. Draft skill files per Matt's structure pattern
+3. Run all 3 validation tools; show verdict; fix until PASS
+
+Use when: starting a new skill in this repo from scratch.
+
+## Why Wrap Matt's Original
+
+Matt's write-a-skill is a tight, principled, ~93-line skill — perfect as-is for individual authoring sessions. The wrapper layers add three things this repo benefits from at scale:
+
+1. **Programmatic enforcement** of Matt's review checklist (the validation tools) — prevents human review-checklist drift across 100+ skills.
+2. **Forcing-question interrogation** (the cs-skill-author persona) — adapts Matt's "review with user" phase to the cs-* persona pattern used elsewhere in this repo.
+3. **Citation-backed references** — Matt links to his own materials; the wrapper adds 5+ authoritative external sources per reference (Anthropic skill docs + community precedent + research) for newcomers learning the pattern.
+
+This is the [hybrid voice approach](../SKILL.md): Matt's words for the principles, our additions for the tooling.
+
+## Attribution
+
+Original: [matt-pocock/skills/skills/productivity/write-a-skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) (MIT).
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — write-a-skill** (https://github.com/mattpocock/skills/, MIT, 2024) — the upstream source
+- **Anthropic — Skills documentation** (https://docs.claude.com/en/docs/agents/skills) — official guidance on skill structure
+- **Anthropic Engineering Blog — Skills patterns** (continuously updated) — patterns for skill authoring
+- **Karpathy, A. — "Software 3.0" + LLM coding pitfalls** (X.com posts 2024-2025) — discipline reference applied throughout this repo's karpathy-coder skill
+- **Pareto principle applied to documentation** — concise = trustworthy; 80% of value in 20% of words
+- **Hyrum's Law** as applied to skill descriptions — once a description shape is observed, downstream agents depend on it
+- **Conway's Law as applied to skill libraries** — skill organization mirrors team responsibilities; progressive disclosure mirrors information needs across team boundaries

package/engineering/write-a-skill/skills/write-a-skill/references/description_design_patterns.md

@@ -0,0 +1,139 @@
+# Description Design Patterns for Skills
+
+This reference answers exactly one decision: **how do we write a skill description that an agent actually picks correctly when faced with a long skill list?**
+
+Pair with `scripts/skill_description_validator.py` for automated enforcement.
+
+## Matt Pocock's Foundational Rule
+
+> "The description is **the only thing your agent sees** when deciding which skill to load."
+>
+> — Matt Pocock, write-a-skill
+
+Implication: the description is not marketing copy. It's a routing signal for the agent. Every word competes with every other skill's description for activation attention.
+
+## The Four Format Rules (per Matt)
+
+1. **Max 1024 chars** — beyond this, agents lose the early sentences when condensing context
+2. **Third person** — first-person ("I help with...") confuses agent self-identification; second-person ("You can...") confuses pronoun reference
+3. **First sentence: what it does** — front-load the verb + object
+4. **Second sentence: "Use when [specific triggers]"** — agent's most reliable activation cue
+
+## Good vs Bad Examples (Matt's pattern, expanded)
+
+**Good** (Matt's PDF example):
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Why good:**
+- Front-loaded verbs: Extract, fill, merge
+- Concrete objects: text, tables, PDF files, forms
+- Explicit trigger: "Use when working with PDF files"
+- Specific keywords for matching: "PDFs", "forms", "document extraction"
+
+**Bad** (Matt's):
+
+```
+Helps with documents.
+```
+
+**Why bad:**
+- "Helps" is content-free
+- "Documents" is generic — every doc skill has this
+- No trigger
+- No keyword variety
+
+**Bad in different way** (over-specified):
+
+```
+This skill performs comprehensive PDF document processing including but not limited to extraction, manipulation, format conversion, content analysis, metadata management, and security operations on PDF files, with support for various PDF versions and embedded media types.
+```
+
+**Why bad:** verbose, no triggers, agent can't extract the key keywords from the wall of text.
+
+## The Trigger Sentence Pattern
+
+The "Use when" sentence is the highest-leverage part of the description. Patterns that work:
+
+**Keyword triggers** (when user types specific words):
+```
+Use when user mentions PDFs, forms, or document extraction.
+```
+
+**File-type triggers** (when agent sees specific files):
+```
+Use when working with `.tsx` files or React component tests.
+```
+
+**Context triggers** (when agent is in a specific state):
+```
+Use when the user requests a code review of a pull request.
+```
+
+**Workflow triggers** (when agent is mid-workflow):
+```
+Use after running tests and before committing changes.
+```
+
+## Vocabulary Selection
+
+The description's words must overlap with words users + agents naturally use for the task.
+
+| Bad keyword | Better keyword | Why |
+|---|---|---|
+| "documents" | "PDF files" / "Word docs" | More specific = less collision |
+| "improve" | "refactor" / "fix" / "optimize" | Specific verb = clearer routing |
+| "various" | (delete; just list them) | Hedge language = no info |
+| "modern" | (cite the actual tool/version) | Trend words age badly |
+| "comprehensive" | (delete; just list capabilities) | Adjective inflation |
+
+## Length Optimization
+
+Below 1024 chars, shorter is usually better. Target: 100-300 chars for most skills.
+
+Where complexity demands more chars, prioritize:
+1. The verb-object pair (what it does) — never compress
+2. The trigger phrase — never compress
+3. Keyword variety (different ways users describe it) — expand here if space allows
+4. Anti-keyword (what it does NOT do) — only if there's a frequently-confused sibling skill
+
+## Anti-Patterns to Avoid
+
+1. **First-person voice** — "I extract PDFs" — confuses agent self-reference
+2. **Marketing language** — "fast, powerful, intuitive" — agent doesn't care, ignores adjectives
+3. **Trigger-less descriptions** — every skill needs "Use when X"
+4. **Multi-purpose dumping** — if your skill does 10 unrelated things, it's probably 10 skills
+5. **Pronouns and hedges** — "you can also use this if you want to" — drop entirely
+6. **Recursive descriptions** — "Use this skill when you need this skill" — adds nothing
+7. **Implementation details** — "Built on Python + stdlib" — agent doesn't care; matters for README, not description
+
+## Pre-Commit Discipline
+
+Run before every skill PR:
+
+```bash
+python scripts/skill_description_validator.py path/to/SKILL.md
+```
+
+If validator returns FAIL, fix before merging. If WARN, justify and document the trade-off.
+
+## When This Reference Doesn't Help
+
+- **Naming the skill itself** — different concern; see naming-conventions guidance per-repo
+- **Skill discovery in marketplaces** — different audience (humans browsing), different rules
+- **System-prompt design for the agent that loads skills** — upstream concern
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — write-a-skill** (https://github.com/mattpocock/skills/, MIT) — the 4 format rules + good/bad example pattern
+- **Anthropic — Building agents with skills** (https://docs.claude.com/en/docs/agents/skills) — official format guidance
+- **Anthropic Engineering — Effective system prompts** (continuously updated blog) — same principles applied to system-prompt design
+- **Claude Code documentation — Skill registry** — how Claude's skill-loader uses descriptions
+- **Karpathy, A. — public commentary on LLM prompt design** — emphasis on specificity + lack of ambiguity
+- **Garrett, J.J. — "The Elements of User Experience"** (2002) + information architecture principles — labels must match user mental models
+- **Nielsen Norman Group — Microcontent guidelines** — applies to skill descriptions: front-load value, hard-cap length, scannable structure
+- **Search-engine + SEO patterns adapted for agent routing** — keyword density, intent matching, semantic field coverage

package/engineering/write-a-skill/skills/write-a-skill/references/progressive_disclosure_principles.md

@@ -0,0 +1,89 @@
+# Progressive Disclosure for Skill Files
+
+This reference answers exactly one decision: **when should a SKILL.md be split into reference files, and how do we keep the disclosure ladder shallow + scannable?**
+
+Pair with `scripts/skill_structure_validator.py` for automated enforcement of the 100-line ceiling + one-level-deep rule.
+
+## What "Progressive Disclosure" Means in Skill Files
+
+Progressive disclosure = present the minimum needed to act, with paths to deeper detail when needed. For agent skills:
+
+- **SKILL.md** = the description + minimum workflow the agent needs to invoke the skill
+- **REFERENCE.md / EXAMPLES.md / references/*.md** = deep detail invoked only when the SKILL.md workflow points there
+- **scripts/** = deterministic operations (no LLM token cost; no inconsistency risk)
+
+The goal: agent reads SKILL.md and either has enough to act, or has a clear link to the specific reference file that resolves its question. No deeper than that.
+
+## Matt Pocock's Original Rule (the 100-Line Ceiling)
+
+> "Split into separate files when:
+> - SKILL.md exceeds 100 lines
+> - Content has distinct domains (finance vs sales schemas)
+> - Advanced features are rarely needed"
+>
+> — Matt Pocock, write-a-skill
+
+The 100-line ceiling is empirical: agents reading >100 lines of SKILL.md tend to over-condition on tangential detail; below 100 lines, the agent reads the entire skill and routes correctly to references or scripts when needed.
+
+## When the Ceiling Is Right vs Wrong
+
+| Situation | 100-line ceiling appropriate? |
+|---|---|
+| Single-action skill (e.g., format-json) | Yes — fits comfortably under 50 lines |
+| Mid-complexity skill with 2-3 workflows | Yes — 70-100 lines |
+| Skill with 4+ workflows + extensive examples | No — split workflows into separate reference files |
+| Domain-spanning skill (multi-framework like compliance-os) | No — split per-framework into separate references |
+| Skill that wraps another (derived/extension) | Special case — wrapper additions push past 100; treat as warning, not failure |
+
+## The One-Level-Deep Rule
+
+> "References one level deep" — Matt Pocock review checklist
+
+Why: agent loading a reference file should resolve its question without further indirection. If `REFERENCE.md` says "see `references/foo.md` for more on bar," then bar's content is the leaf — it shouldn't say "see references/foo/bar/baz.md."
+
+Operational consequence: keep `references/` flat. No nested subfolders.
+
+## Anti-Patterns to Avoid
+
+1. **SKILL.md as a complete manual** — 300-line SKILL.md with every workflow inline. Agent over-conditions; token cost on every invocation.
+2. **Reference soup** — 20 reference files at one level. Hard to scan; agent can't tell which to load.
+3. **Circular references** — `A.md` → `B.md` → `A.md`. Agent loops or fails.
+4. **No examples in SKILL.md** — "see EXAMPLES.md for usage." Forces agent to load another file to do anything. Provide a *minimum* example in SKILL.md.
+5. **Versioned references** — `references/v1/` and `references/v2/`. Maintenance burden; pick one.
+6. **Auto-generated table-of-contents** — agents don't need this; humans rarely browse `references/`.
+
+## How to Apply Progressive Disclosure Concretely
+
+1. Draft SKILL.md with the workflow you want the agent to use 80% of the time
+2. Count lines. If > 100, identify the next-largest section. Move it to `references/<topic>.md`.
+3. Replace the moved section with a 1-2-line pointer: "See [references/topic.md](references/topic.md) for X."
+4. Repeat until SKILL.md ≤ 100 lines.
+5. Validate: `python scripts/skill_structure_validator.py path/to/skill-folder/`
+
+## When 100 Is Too Restrictive
+
+For skills that wrap or extend other skills (like this `write-a-skill` itself, which preserves Matt's full original content + adds wrapper sections), the 100-line ceiling becomes an artifact of attribution rather than over-conditioning. Two options:
+
+- Accept the line-count WARN as documentation of intentional preservation
+- Move attribution/wrapper notes to `README.md` (which lives outside the SKILL.md ceiling)
+
+This `write-a-skill` skill demonstrates option 1.
+
+## When This Reference Doesn't Help
+
+- **Choosing what to put in scripts/ vs references/** — see Matt's "When to Add Scripts" guidance in main SKILL.md.
+- **Information architecture for documentation sites** — see DocOps + DITA references.
+- **Token-budget optimization beyond skill files** — different scope (system-prompt design, context engineering).
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — write-a-skill** (https://github.com/mattpocock/skills/, MIT) — the 100-line ceiling + one-level-deep rule originator
+- **Anthropic — Building agents with skills** (https://docs.claude.com/en/docs/agents/skills) — official skill structure documentation
+- **Anthropic Engineering Blog — Prompt design + context engineering** — concise context = lower hallucination + better routing
+- **Don Norman — "The Design of Everyday Things"** (1988) + progressive disclosure HCI principle — origin of the term
+- **Information Foraging Theory** — Pirolli & Card (1995) — humans + agents search info using cost/benefit tradeoffs analogous to foraging
+- **John Maeda — "The Laws of Simplicity"** (2006) — reduction principle applied to UX, directly applicable to skill files
+- **Lean Documentation movement** — DocOps + DITA practitioners on minimum-viable-documentation patterns
+- **Pareto principle (80/20 rule)** applied to skill workflows — most agent invocations use the same 20% of skill content

package/engineering/write-a-skill/skills/write-a-skill/references/quality_gates_for_skills.md

@@ -0,0 +1,158 @@
+# Quality Gates for Skill Libraries
+
+This reference answers exactly one decision: **what checks must pass before a new skill enters the library, and why?**
+
+Pair with `scripts/skill_review_checklist_runner.py` for the automated gate.
+
+## The Six Mandatory Gates (per Matt Pocock's checklist)
+
+| # | Check | Why it matters |
+|---|---|---|
+| 1 | Description includes triggers ("Use when ...") | Without trigger, agent guesses when to activate — high false-positive rate |
+| 2 | SKILL.md under 100 lines | Over-conditioning; agent reads tangential detail and misroutes |
+| 3 | No time-sensitive info | Dates/versions/year refs rot; agent receives stale guidance |
+| 4 | Consistent terminology | Synonym drift confuses the agent + downstream users |
+| 5 | Concrete examples included | Without an example, agent constructs from scratch and hallucinates |
+| 6 | References one level deep | Deep nesting = agent gives up resolving the reference chain |
+
+## Why Programmatic, Not Manual
+
+Manual review of these 6 items:
+- Drifts across reviewers (different humans interpret "concrete example" differently)
+- Slows PR cadence (every reviewer re-reads every skill against every check)
+- Misses regressions (a skill once compliant can drift across updates)
+
+Programmatic gate (the `skill_review_checklist_runner.py` tool):
+- Same verdict regardless of reviewer
+- Runs in CI in seconds
+- Catches regressions automatically
+- Documents the explicit criteria — no implicit reviewer judgment
+
+## Beyond Matt's Six: Additional Quality Dimensions
+
+Matt's 6 are the floor. For a mature skill library, add:
+
+### Citation density (this repo's standard)
+
+Every reference file in `references/` should cite ≥ 5 authoritative sources. Why: skills inspired by public material need traceable provenance. Tool: grep-based count of bibliography entries.
+
+### Tool determinism (karpathy-coder discipline)
+
+Every script in `scripts/` should:
+- Be stdlib-only (no external dependencies)
+- Have embedded sample input
+- Support `--output {text,json}`
+- Be deterministic (no randomness, no LLM calls)
+
+Tool: `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py`
+
+### Cross-skill compatibility
+
+For skills that reference other skills (via `Adjacent Skills` sections), every cross-reference must resolve to an existing skill. Tool: link-integrity grep across skill folders.
+
+### Attribution discipline (this repo's standard)
+
+Skills derived from external sources (MIT-licensed or public-domain) must:
+- Name the original author
+- Link to the original source
+- State the license
+- Note what's preserved vs added
+
+Tool: presence-of-attribution grep in plugin.json + README.md.
+
+## Quality Gate Sequencing
+
+Apply gates in this order during PR:
+
+```
+1. Description validator      (fast; catches most issues early)
+2. Structure validator        (fast; folder layout + line counts)
+3. Review checklist runner    (combined; all 6 of Matt's items)
+4. Karpathy complexity check  (code quality; only if scripts/ exists)
+5. Karpathy assumption linter (code quality; only if scripts/ exists)
+6. Link integrity scan        (cross-skill references)
+7. Citation density check     (references/ bibliography)
+```
+
+If any gate fails, PR is blocked. WARN status (1 check fails out of 6) requires reviewer justification in PR description.
+
+## CI Integration Pattern
+
+```yaml
+# .github/workflows/skill-quality-gate.yml (illustrative)
+on: [pull_request]
+jobs:
+  skill-quality:
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run review checklist
+        run: |
+          for skill in $(find . -name "SKILL.md" -type f); do
+            python engineering/write-a-skill/skills/write-a-skill/scripts/skill_review_checklist_runner.py "$(dirname $skill)"
+          done
+      - name: Run karpathy gate
+        run: python engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py .
+```
+
+## Common Failure Modes (and Fixes)
+
+| Failure | Common cause | Fix |
+|---|---|---|
+| Description >1024 chars | Trying to describe every feature | Cut to verbs + objects + triggers; move details to SKILL.md |
+| SKILL.md >100 lines | Inline workflows that belong in references | Move workflows to `references/<workflow>.md`; replace with 1-line pointers |
+| Missing "Use when" | Description written as marketing copy | Rewrite second sentence to start with "Use when ..." |
+| Time-sensitive info | "As of October 2024 ..." | Remove date; describe pattern that doesn't depend on date |
+| No examples | Abstract guidance only | Add at least 1 code block showing minimum invocation |
+| Deep references | Subfolder structure under references/ | Flatten to one level |
+
+## Quality Gate Anti-Patterns
+
+1. **Disabling gates "just for this skill"** — once disabled, never re-enabled. If a gate genuinely doesn't apply, document the exception in skill metadata.
+2. **Reviewer override without rationale** — if a reviewer bypasses a check, they own future regressions. Require justification.
+3. **Manual review for what tools can check** — wastes reviewer attention on mechanical items. Reserve manual review for judgment calls (is the workflow correct? Does the skill cover the stated use case?).
+4. **Gate proliferation** — adding new gates faster than they're enforced creates fatigue. Cap at ~10 gates total; merge similar ones.
+
+## Binding vs Advisory for Legacy Skills
+
+Matt's 6-item checklist is **binding for new skills** (any skill authored after v2.6.0 must PASS all 6 before merge). For **legacy skills** authored before this discipline was established, the same rules apply as **advisory** signals to triage, not blockers.
+
+The reason: this repo has 298 SKILL.md files written under different conventions over time. Auditing them against the v2.6.0 checklist surfaces real tech debt, but retro-fitting all 298 in one sweep would require ~50-100 hours of careful editing. Forcing the gate as blocking would either delay all PRs or require disabling the gate.
+
+The pragmatic split:
+
+| Skill cohort | Gate status | Action on failure |
+|---|---|---|
+| **New skills (post-v2.6.0)** | **Blocking** — must PASS all 6 | Fix before PR merge |
+| **Legacy skills (pre-v2.6.0)** | **Advisory** — WARN/FAIL surfaced but non-blocking | Track in audit report; fix opportunistically |
+
+How to tell which cohort a skill belongs to:
+- New: matches the `engineering/<skill>/skills/<skill>/` wrapper pattern with `attribution` in plugin.json, OR was added in a PR tagged for v2.6.0+
+- Legacy: pre-existing structure without the wrapper pattern, or pre-v2.6.0 git history
+
+Re-running `scripts/audit_skills.py` periodically captures the legacy backlog drift. The numerator (PASS count) is the metric to grow over time, not "force every skill to PASS by Friday."
+
+## Common Cohort-Specific Issues
+
+**Legacy SKILL.md > 100 lines (88% of repo):** the dominant violation. Most legacy skills predate the 100-line ceiling. Splitting them into `references/` is invasive. The advisory frame: a 200-line legacy SKILL.md isn't urgent unless the skill is actively being edited.
+
+**Legacy missing "Use when" trigger (26% of repo after v2.6.1 validator fix):** highest-leverage fix because it's a 1-line edit per skill. Even legacy skills should adopt this in the next time they're touched.
+
+**Legacy placeholder descriptions (e.g., "Migration Architect" as the only description text):** these are real bugs, not just lint failures. Fix on sight. v2.6.1 fixed 10 of these in the engineering POWERFUL tier.
+
+## When This Reference Doesn't Help
+
+- **Performance optimization of skills** — different concern; benchmark agent token usage, not skill files
+- **Skill discovery + organization in marketplaces** — different audience (humans), different rules
+- **A/B testing skills** — different mode; quality gates are preconditions, not A/B subjects
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — write-a-skill** (https://github.com/mattpocock/skills/, MIT) — the 6-item review checklist
+- **Karpathy, A. — public commentary on LLM coding pitfalls** (X.com, 2024-2025) — discipline framework adopted as `engineering/karpathy-coder/`
+- **Anthropic — Building agents with skills** (https://docs.claude.com/en/docs/agents/skills) — official skill quality guidance
+- **Continuous Integration / Continuous Deployment patterns** — Humble & Farley (Continuous Delivery, 2010) — gate sequencing principles
+- **The Phoenix Project** (Kim et al., 2013) + Three Ways of DevOps — quality gates as constraint management
+- **Hyrum's Law** as applied to skill libraries — once a skill's behavior is observed, downstream depends on it; quality gates prevent drift
+- **Software craftsmanship + the Boy Scout Rule** — leave each skill cleaner than you found it; gates enforce the floor