Claude Code Insights

English | 繁體中文

A best practices guide for Claude Code CLAUDE.md, Skills, and Subagents.

This repository compiles and organizes content primarily from Anthropic's official documentation, community articles, and popular GitHub repositories — credit goes to the original authors. This is a curated collection of what I've learned along the way, not original research.

Who Is This For

Developers ranging from Claude Code beginners to those looking to master Skills and Subagent design patterns.

• Beginners: Start with the CLAUDE.md guide to build a solid foundation
• Advanced: The Skills and Subagent guides cover design patterns and architectural strategies

Contents

The three guides cross-reference each other. Recommended reading order: CLAUDE.md → Skills → Subagent.

Practical Examples

Subagent Examples

Hook Examples

Skills Examples

The following Skills are adapted from mattpocock/skills (implementing concepts like design trees and TDD vertical slices), reworked according to this repository's best practices guide: templates extracted to templates/, reference materials moved to reference/, and Gotchas sections added.

Solo Development Workflow: /grill-me (interrogate the design) → /write-prd (write the PRD) → /prd-to-plan (break into phases, optionally review with Codex) → /tdd (implement one by one)

Skill Development Workflow: /write-a-skill (author the skill) → /skill-eval-toolkit (evaluate and optimize)

write-prd — PRD Authoring Skill

Fills the gap between /grill-me and /prd-to-plan — turns design decisions or rough ideas into a structured PRD:

• One-question-per-turn structured interview (target user → success state → non-goals)
• Enforces P0/P1/P2 priority tiers, References citing decision records, docs/prds/ output convention
• Stays at product / system-contract level — no implementation details leak (httpOnly cookies, SDK pinning, etc.)
• Delegated/Eval Mode — distinguishes draft artifacts from canonical PRD files
• Includes 4 functional eval cases + 12 trigger tests (validated through 2 iterations with skill-eval-toolkit, 90% pass rate)

You: "Write a PRD based on docs/decisions/login-redesign.md"
Claude: (loads write-prd, reads decision record, identifies gaps,
         produces PRD draft with user stories + traceability, asks to confirm)

write-a-skill — Skill Authoring Guide

Use when you want to create a new skill from scratch. Covers the full authoring lifecycle:

• Content type decision (Reference vs Task) and invocation control (disable-model-invocation, context: fork, etc.)
• Frontmatter schema, progressive disclosure (metadata → body → bundled resources)
• Description writing — trigger-oriented keywords, not feature summaries
• Security checklist and review process
• Gotchas iteration loop — the feedback mechanism that makes skills more accurate over time

You: "I want to create a skill that generates API documentation from OpenAPI specs"
Claude: (loads write-a-skill, interviews you, drafts SKILL.md, runs smoke tests)

skill-eval-toolkit — Eval-Driven Testing and Optimization

Use when you have an existing skill and want to measure or improve it. Provides a structured eval loop with 4 specialized subagents:

The workflow: create test prompts → run with-skill and baseline in parallel → grade → aggregate benchmarks → interactive viewer for human review → improve → repeat. Also includes automated description trigger optimization (train/test split, iterative improvement) and an eval-driven body autopilot loop for small SKILL.md mutations.

You: "Evaluate my json-diff skill and tell me if it actually adds value"
Claude: (loads skill-eval-toolkit, creates test cases, spawns parallel runs,
         grades outputs, launches viewer, shows you the results)

When to use which: If the question is "how should I structure this skill?" → write-a-skill. If the question is "is this skill actually working well?" → skill-eval-toolkit. Most skills start with the former and graduate to the latter when you need quantitative rigor.

Gotchas Are the Soul of a Skill: The strongest signal in any Skill isn't the tutorial — it's the pitfalls the team has hit. Every time a Skill execution encounters an unexpected failure, write the failure pattern back into Gotchas — this feedback loop makes the Skill more accurate over time. See skills-best-practices.md § 4.3 for details.

Note: These examples can be copied directly into .claude/skills/ for use. We recommend reading both guides first to understand the design rationale and adapt them to your needs.

Quick Overview

CLAUDE.md Guide Highlights

• Why you shouldn't use /init for auto-generation (with supporting research data)
• The right approach from scratch: start with nothing, add rules only when problems arise
• Three-layer architecture model: Enforcement Layer / High-Frequency Recall Layer / On-Demand Reference Layer
• Using Hooks instead of CLAUDE.md directives (determinism > suggestions)
• Five major anti-patterns and maintenance practices

Skills Guide Highlights

• What a Skill is and how it differs from CLAUDE.md
• Complete Frontmatter field reference
• Auto-trigger vs manual invocation control methods
• Skill vs Subagent vs CLAUDE.md decision matrix
• Security guidelines and iteration methodology

Subagent Guide Highlights

• When to use a Subagent (Anthropic's official stance: most scenarios don't need one)
• Four solutions for black-box and one-shot problems
• Research-type and review-type Agent design templates
• Hub-and-Spoke architectural pattern
• The Early Victory Problem and mitigation strategies

License

MIT