What's Changed
All 13 skills have been comprehensively rewritten based on learnings from Anthropic's "Lessons from Building Claude Code: How We Use Skills" article. This is the largest single update to the skills collection.
The Core Transformation
Skills have been rewritten from textbook voice (explains concepts) to hybrid instructional voice (leads with actions, weaves in reasoning):
Before:
"System prompts establish the agent's core identity, constraints, and behavioral guidelines. They are loaded once at session start and typically persist throughout the conversation."
After:
"Organize system prompts into distinct sections using XML tags or Markdown headers. System prompts persist throughout the conversation, so place the most critical constraints at the beginning and end where attention is strongest — the middle receives 10-40% less recall accuracy."
Changes Across All 13 Skills
- Hybrid voice rewrite — every prose section rewritten from "X is Y" to "Do X because Y" while preserving all substantive knowledge (metrics, research findings, thresholds)
- Gotchas sections — standardized
## Gotchasadded to all 13 skills (was 4, inconsistently formatted). 5-9 experience-derived, specific, actionable gotchas per skill. Per Anthropic: "The highest-signal content in any skill is the Gotchas section." - Composable scripts — all 12 Python scripts updated with
__all__exports, type hints,"Use when:"docstrings, and__main__demo blocks - Progressive disclosure triggers — all 13 References sections now include
"Read when: [condition]"to tell Claude when to load supporting files - Template updated —
template/SKILL.mdnow includes canonical## Gotchassection
Key Metrics
| Metric | Before | After |
|---|---|---|
| Total SKILL.md lines | 3,559 | 3,421 (compressed despite adding content) |
| Skills with Gotchas | 4 (inconsistent) | 13 (standardized) |
Scripts with __all__
| 0 | 12 |
| References with triggers | 0 | 13 |
| All under 500-line limit | ✓ | ✓ (range: 195–402) |
New Files
docs/skills-improvement-analysis.md— full gap analysis of the repo against Anthropic's 9 skill categories and best practicesskills/advanced-evaluation/references/evaluation-pipeline.md— ASCII pipeline diagram offloaded from SKILL.md to free line budget
Skills Updated
| Bundle | Skills |
|---|---|
| context-engineering-fundamentals | context-fundamentals, context-degradation, context-compression, context-optimization |
| agent-architecture | multi-agent-patterns, memory-systems, tool-design, filesystem-context, hosted-agents |
| agent-evaluation | evaluation, advanced-evaluation |
| agent-development | project-development |
| cognitive-architecture | bdi-mental-states |
28 files changed, 4,938 insertions, 3,100 deletions
🤖 Generated with Claude Code