[epic] v2.7: refactor top-20 skills to fit Matt Pocock's 100-line SKILL.md ceiling

[alirezarezvani]

Summary

The v2.6.1 audit (scripts/audit_skills.py) reveals 263 of 298 legacy SKILL.md files (88%) exceed Matt Pocock's 100-line ceiling — the dominant pattern violation across the repo.

Per v2.6.1's engineering/write-a-skill/skills/write-a-skill/references/quality_gates_for_skills.md, this rule is now formally advisory for legacy skills (binding only for new skills post-v2.6.0). But the long-term goal is to grow the PASS rate (currently 9/298 = 3%) by refactoring the highest-impact skills.

This issue tracks the planning + execution sweep for v2.7.

Background

Audit metric	v2.6.0 baseline	v2.6.1
PASS (6/6)	4 (1%)	9 (3%)
WARN (5/6)	111 (37%)	137 (46%)
FAIL (≤4/6)	183 (61%)	152 (51%)
"SKILL.md ≤ 100 lines" failures	263	263 (unchanged)

The other 5 of Matt's 6 rules have improved (description triggers, terminology, examples, time-sensitivity, references depth). Only the 100-line ceiling has resisted because it requires structural refactoring — splitting SKILL.md content into references/<topic>.md files per Matt's progressive disclosure pattern.

Scope (proposed)

Phase 1 — Prioritize (1 PR, low effort):

• Identify top-20 high-traffic skills (most-installed via marketplace metrics OR most-mentioned in domain CLAUDE.md files)
• Refactor only these 20 to ≤100 lines via references/ splits
• Expected impact: PASS rate jumps from 9/298 (3%) to ~25-30/298 (8-10%)

Phase 2 — Domain sweep (3-4 PRs, medium effort):

• Address engineering-advanced tier first (40 skills, most cs-* commands depend on these)
• Then engineering-team tier (32 skills)
• Then C-level + product + marketing in parallel
• Expected impact: PASS rate reaches ~50%

Phase 3 — Long tail (ongoing):

• Remaining skills addressed when touched for other reasons (Boy Scout rule)

Per-skill refactoring pattern

For each over-100-line SKILL.md:

1. Identify the largest section (often "Workflows" or "Use Cases")
2. Move to references/<topic>.md
3. Replace inline content in SKILL.md with: See [references/topic.md](references/topic.md) for X.
4. Validate: python3 engineering/write-a-skill/skills/write-a-skill/scripts/skill_structure_validator.py <skill-folder>

Acceptance criteria for v2.7 release

• At minimum: top-20 high-traffic skills refactored to ≤100 lines
• PASS rate ≥ 25/298 (8.4%, up from 3%)
• "SKILL.md ≤ 100 lines" failure rate ≤ 75% (down from 88%)
• No regression on the 9 currently-PASS skills
• Documentation: per-domain refactoring playbook in engineering/write-a-skill/

Open questions

1. Should we batch all 20 in one PR or one-per-skill PRs?
2. How do we determine "high-traffic"? Marketplace install metrics aren't exposed. Could use ClawHub downloads if available, or domain-CLAUDE-md prominence as a proxy.
3. Does the 100-line ceiling apply to the whole SKILL.md including frontmatter, or just the body?

Surfaced by

v2.6.1 ecosystem verification — Agent 5 (regression + quality evaluator), SC9.

Related

• v2.6.1 release: PR release(v2.6.1): dev → main — meta-skill maturity cleanup #650
• Quality gates reference: quality_gates_for_skills.md
• Audit harness: scripts/audit_skills.py

🤖 Filed via Claude Code session

[alirezarezvani]

Phase 1 kicked off — pilot tranche in PR #843 (ci-cd-pipeline-builder 147→89, mcp-server-builder 164→97, both validator-PASS), which also establishes the per-skill playbook for the rest.

Open questions — answered

1. Batch or per-skill PRs? Batch tranches of 5-8. The refactor is mechanical (move the advisory layer verbatim to one new references/ doc, link with a one-line summary); per-skill PRs would be overhead without review benefit.
2. How to determine "high-traffic"? Domain-CLAUDE.md prominence, as proposed in this issue — skills called out in the root CLAUDE.md highlights and the engineering tier docs.
3. Does the ceiling include frontmatter? Yes. skill_structure_validator.py's count_lines() counts every line of SKILL.md, frontmatter included.

Top-20 priority list (current line counts, refs = existing reference docs)

Lines	Refs	Skill
572	5	engineering-team/skills/senior-frontend
467	5	engineering-team/skills/senior-backend
432	2	engineering/skills/api-design-reviewer
428	3	engineering/skills/migration-architect
412	5	engineering-team/skills/senior-fullstack
403	3	engineering-team/skills/tdd-guide
397	0	engineering/skills/pr-review-expert
343	3	engineering-team/skills/senior-architect
323	3	engineering-team/skills/senior-devops
322	1	engineering-team/skills/incident-response
272	3	engineering/skills/observability-designer
242	4	engineering/skills/kubernetes-operator
234	4	engineering/skills/slo-architect
231	4	engineering/skills/chaos-engineering
226	5	marketing-skill/skills/aeo
219	4	engineering/skills/feature-flags-architect
207	3	engineering/skills/tc-tracker
190	2	engineering/skills/ship-gate
183	0	engineering-team/skills/code-reviewer
170	1	engineering/skills/performance-profiler

(✅ already done in #843: ci-cd-pipeline-builder 147, mcp-server-builder 164.)

Caveats for later tranches: slo-architect, chaos-engineering, kubernetes-operator are dual-published — refactors must sync the standalone twin or the G4 drift guard fails. Each new reference doc bumps the headline counter, so every tranche ends with a derive_counters.py --check true-up (G3 is blocking).

---

Generated by Claude Code

[alirezarezvani]

Playbook amendment from PR #843 review (applies to all remaining tranches): security-critical guidance is the one exception to the strict move-to-references rule. Keep a 2-3 bullet inline summary in the relevant workflow step (e.g. "secrets in env, not schemas") with a link to the full reference doc — safety nudges must stay scannable in SKILL.md, not two hops away. Everything else (pitfalls, best practices, strategy notes, checklists, scaling) moves verbatim to references. Applied in mcp-server-builder's "Harden for Production" step; the skill sits at exactly 100 lines (ceiling is inclusive: lines <= 100).

---

Generated by Claude Code

[alirezarezvani]

Playbook note (from PR #843 supplementary review): target ≤95 lines, not the ceiling itself. mcp-server-builder landed at exactly 100/100, which means any future addition — even one bullet — forces a corresponding removal. ci-cd-pipeline-builder's 89 with ~11 lines of headroom is the better shape; treat 96-100 as "passes but tight" when reviewing the remaining 18 tranches.

---

Generated by Claude Code

[alirezarezvani]

Tranche 2 in PR #844: performance-profiler 170 → 74 lines (PASS, comfortable headroom), advisory layer moved to references/optimization-playbook.md. Counters trued up 704 → 705.

Blocked pending a playbook decision — the next three priority skills are not mechanical moves:

• code-reviewer (183): bulk is operational dispatch tables/tool thresholds, no advisory layer to move — going under 100 means splitting tool documentation into references, a different tradeoff.
• tc-tracker (207): movable advisory content (~45 lines) isn't enough on its own; rest is operational workflow text.
• ship-gate (190): external MIT contribution with preserved upstream voice — restructuring should respect the hybrid-voice import convention.

Suggest deciding whether the playbook extends to "operational reference splits" (move tool detail tables/workflow elaborations to references, keeping command one-liners) before anyone runs these three or the 400-line senior-* role skills.

---

Generated by Claude Code