claude-code-mastery

Claude Code Mastery - Building Better AI Systems

Use the cc-docs skill to read the official Claude Code documentation before you design anything against it — the spec moves, and this file is a map, not a substitute for it.

Use this knowledge to continuously improve how you work.

Core Capabilities

Subagents

Location: ~/.claude/agents/ (user) or .claude/agents/ (project)

Key fields:

---
name: agent-name
description: When Claude should delegate here
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet | opus | haiku | inherit
permissionMode: default | acceptEdits | bypassPermissions
skills: skill-1, skill-2
hooks:
  PreToolUse: [...]
  PostToolUse: [...]
---

System prompt content here...

Use subagents when:

• Task needs isolated context
• Different tools/permissions needed
• Specialized behavior required

Skills

Location: ~/.claude/skills/ (user) or .claude/skills/ (project)

Structure:

skill-name/
├── SKILL.md          # Required - main instructions
├── reference.md      # Optional - detailed docs
└── scripts/          # Optional - utilities

Key fields:

---
name: skill-name
description: When to apply this skill (triggers auto-loading)
allowed-tools: Read, Grep, Glob  # Optional tool restriction
context: fork  # Optional - run in subagent
---

Instructions here...

Use skills when:

• Knowledge should auto-apply based on task
• Pattern repeats across projects
• Want to inject expertise without delegation

Hooks

Location: .claude/settings.json or subagent frontmatter

Events:

• PreToolUse - Before tool executes (can block)
• PostToolUse - After tool executes
• SubagentStart - When subagent begins
• SubagentStop - When subagent completes
• SessionStart - When session begins

Example:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "./scripts/auto-lint.sh"
      }]
    }]
  }
}