claude-code-expert

Claude Code Expert

Comprehensive quick-reference for Claude Code extensibility. For detailed examples, see the reference files linked at the end.

When to Use

• Updating existing skills, agents, slash commands, or plugins
• Creating new agents, slash commands, or plugins (NOT new skills)
• Debugging hook configurations or integration issues
• Reviewing Claude Code file formats for correctness

Do NOT use for: Creating NEW skills from scratch (use claude-creator instead), general coding tasks, or CI/CD unrelated to Claude Code.

Core Concepts

The Four Extension Types

Decision Framework

1. Should Claude remember X automatically? → Skill
2. Should Claude follow workflow Y step-by-step? → Agent
3. Do users need shortcut to Z? → Command
4. Should setup be shared/distributed? → Plugin

File Formats Quick Reference

Skill Frontmatter

---
name: skill-name                          # Required: lowercase, hyphens, max 64 chars
description: This skill should be used when [triggers]. It provides [capabilities].  # Required: max 1024 chars
allowed-tools: Read, Grep, Glob           # Optional: tool restrictions
context: fork                             # Optional: run in forked sub-agent
agent: my-agent                           # Optional: use agent's config
hooks:                                    # Optional: component-scoped hooks
  PreToolUse: [...]
  PostToolUse: [...]
  Stop: [...]
---

Skills hot-reload when modified. See references/skill-triggers.md for trigger optimization.

Agent Frontmatter

---
name: agent-name                          # Required: kebab-case, match filename
description: What agent does and when to use it.  # Required
model: opus                               # Optional: sonnet, opus, haiku
color: blue                               # Optional: visual identifier
tools: Read, Grep, Glob, Bash             # Optional: tool restrictions
hooks:                                    # Optional: component-scoped hooks
  PreToolUse: [...]
  PostToolUse: [...]
  Stop: [...]
---

Disable agents: "disallowed-tools": ["Task(agent-name)"] in settings.json.

Command Frontmatter

---
description: Brief description for autocomplete  # Optional
argument-hint: [file] [options]           # Optional: shown in picker
model: opus                               # Optional: override model
allowed-tools: Bash(git *), Read, Grep    # Optional: tool restrictions
disable-model-invocation: false           # Optional: prevent Skill tool calling
hooks:                                    # Optional: component-scoped hooks
  PreToolUse: [...]
  Stop: [...]
---

Special syntax: $ARGUMENTS, $1/$2, inline bash with exclamation prefix (requires allowed-tools), @path/file

See references/command-patterns.md for patterns and examples.

Plugin Manifest

{
  "name": "plugin-name",
  "description": "What this plugin provides",
  "version": "1.0.0",
  "author": "Author Name"
}

Hooks Quick Reference

Locations: settings.json (global) or frontmatter (component-scoped)

Matcher patterns: Bash(git commit:*), Write(*.py), Edit(src/**/*.ts), mcp__server_*, *

Hook options: matcher, command, once (run only once per session)

See references/hook-recipes.md for complete schemas and recipes.

Settings & CLI

Location: .claude/settings.json or ~/.claude/settings.json

CLI flags: --agent, --tools, --disable-slash-commands, --session-id, --system-prompt

CLAUDE.md & Rules

CLAUDE.md: Project root or ~/.claude/CLAUDE.md. Keep concise (always loaded).

Rules directory: .claude/rules/*.md - modular alternative to single CLAUDE.md.

Writing Style

CRITICAL: Use imperative/infinitive form, not second person.

Common Issues

Validation Checklist

• YAML frontmatter has required fields (name, description)
• Names: kebab-case for agents, lowercase-hyphens for skills
• Descriptions include trigger conditions (for skills)
• Imperative writing style throughout
• File locations correct for component type
• Hook scripts executable (chmod +x)

References

• references/skill-triggers.md - Skill triggers, body structure, frontmatter
• references/agent-patterns.md - Agent body structure, frontmatter, patterns
• references/command-patterns.md - Command patterns, TodoWrite usage
• references/hook-recipes.md - Hook schemas, recipes, debugging
• references/configuration.md - CLAUDE.md, rules, settings, CLI, background agents