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

Type	Invocation	Purpose	Location
Skills	Auto (model-invoked)	Persistent context/knowledge	~/.claude/skills/, .claude/skills/, <plugin>/skills/
Agents	Explicit (@agent-name)	Multi-step workflows	.claude/agents/, <plugin>/agents/
Commands	User (/command)	Saved prompts/shortcuts	~/.claude/commands/, .claude/commands/, <plugin>/commands/
Plugins	Package	Bundled distribution	.claude-plugin/plugin.json

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)

Hook	Timing	Frontmatter	settings.json
PreToolUse	Before tool runs	✅	✅
PostToolUse	After tool completes	✅	✅
Stop	When component/agent finishes	✅	✅
UserPromptSubmit	When user sends message	❌	✅
PermissionRequest	When permission requested	❌	✅
SessionStart	Session starts/resumes	❌	✅
SessionEnd	Session ends	❌	✅
SubagentStart/Stop	Subagent lifecycle	❌	✅
Notification	Notification sent	❌	✅
PreCompact	Before context compact	❌	✅

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

Setting	Description
agent	Use agent's system prompt, tools, model for main thread
language	Response language (e.g., "japanese")
disallowed-tools	Disable tools: Task(AgentName), mcp__server_*

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.

✅ Correct	❌ Incorrect
"Identify candidate files..."	"You should identify..."
"Extract data from..."	"You can extract..."

Common Issues

Issue	Cause	Fix
Skill not triggering	Vague description, >1024 chars	Add specific trigger keywords
Hook not executing	Not executable, wrong path	chmod +x, use relative path from root
Agent not found	Name mismatch, wrong location	Match name to filename, check .claude/agents/
Inline bash not working	Missing allowed-tools	Add allowed-tools: Bash(...) to frontmatter

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