| name | claude-code-development |
| description | Expert knowledge in creating and configuring Claude Code components (subagents, skills, slash commands, hooks, MCP integrations). Use when the user asks to create, modify, or extend .claude/ directory components. Follows official best practices and documentation standards. |
Claude Code Development
Overview
This skill provides comprehensive guidance for creating and configuring Claude Code components following official best practices. Use this when working with .claude/ directory structure including agents, skills, commands, hooks, and MCP integrations.
Official Documentation
All official documentation references are maintained in docs/claude/README.md. Always consult these references for the latest standards and best practices:
When creating new components, fetch and review the relevant documentation using the WebFetch tool.
Quick Start
When to Use Which Component?
Use a Subagent when you need:
- Task isolation in a separate context
- Specialized model or tool restrictions
- Repeated complex workflows
Use a Skill when you need:
- Reusable knowledge that Claude lacks
- Domain-specific terminology or patterns
- Expert knowledge loaded into context
Use a Command when you need:
- User-invocable workflows
- Shortcuts for common tasks
- Structured argument handling
Use a Hook when you need:
- Automated actions on tool events
- Validation before operations
- Cleanup after operations
Quick Examples
Agent (specialized AI for focused tasks):
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
Skill (reusable knowledge package):
name: api-design-patterns
description: REST API design. Use when designing or reviewing APIs.
Command (user-invocable workflow):
description: Review code changes
allowed-tools: Task(code-reviewer)
See detailed guides: Agents | Skills | Commands
Component Types Overview
Subagents (.claude/agents/)
Specialized AI assistants that handle specific types of tasks in isolated contexts.
- File Format: Markdown with YAML frontmatter
- Location:
.claude/agents/[agent-name].md
- Key Fields: name, description, tools, model, skills, permissionMode
See Agent Creation Guide for complete details.
Skills (.claude/skills/)
Reusable knowledge packages that can be loaded into conversations or subagents.
- File Format: Markdown with YAML frontmatter
- Location:
.claude/skills/[skill-name]/SKILL.md
- Key Fields: name, description, allowed-tools, context
See Skills Creation Guide for complete details.
Slash Commands (.claude/commands/)
User-invocable prompts that provide reusable workflows.
- File Format: Markdown with YAML frontmatter
- Location:
.claude/commands/[command-name].md
- Key Fields: description, argument-hint, allowed-tools
See Commands Creation Guide for complete details.
Hooks (.claude/hooks/)
Scripts that run automatically on tool events.
- Configuration: In
.claude/settings.json or component frontmatter
- Hook Events: PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop
- Hook Types: command (shell), prompt (text injection)
See Hooks Reference Guide for complete details.
Directory Structure
Standard layout for a well-organized .claude/ directory:
.claude/
├── settings.json # Project-level configuration
├── agents/
│ ├── agent-name-1.md
│ └── agent-name-2.md
├── skills/
│ ├── skill-name-1/
│ │ ├── SKILL.md
│ │ ├── reference.md # Progressive disclosure
│ │ └── scripts/
│ │ └── helper.py
│ └── skill-name-2/
│ └── SKILL.md
├── commands/
│ ├── command-1.md
│ └── command-2.md
└── hooks/
├── README.md # Hook documentation
└── scripts/
├── validate.sh
└── lint.sh
Naming Conventions
Agents: lowercase-with-hyphens
- Good:
code-reviewer, test-runner, db-analyzer
- Avoid:
CodeReviewer, test_runner, DBAnalyzer
Skills: lowercase-with-hyphens (gerund form preferred)
- Good:
processing-pdfs, analyzing-data, reviewing-code
- Acceptable:
pdf-processing, data-analysis, code-review
- Avoid:
helper, utils, tools (too vague)
Commands: lowercase-with-hyphens
- Good:
translate, deploy-staging, run-tests
- Avoid:
doTranslate, Deploy_Staging
Files: Always use .md extension for agents, skills, and commands
Quality Checklist
All Components: Valid YAML, clear description with trigger terms, follows naming conventions
Agents: Focused purpose, minimal tools, clear workflow, tested
Skills: Concise (<500 lines), concrete examples, one-level references
Commands: User-facing, clear arguments, examples included
Hooks: Fast execution, proper error handling, appropriate scope
For detailed checklists, see component-specific guides.
Best Practices Summary
- Follow official documentation: Always consult official guides
- Be concise: Assume Claude is smart, avoid over-explaining
- Use progressive disclosure: Split large content into multiple files
- Test thoroughly: Verify components work as expected
- Iterate based on behavior: Watch how Claude uses components and refine
- Keep components focused: Each component should do one thing well
- Document clearly: Good descriptions and examples are essential
- Use appropriate tools: Restrict tool access to minimum needed
- Maintain consistency: Follow naming conventions and patterns
- Version control: Check components into git for team collaboration
References
For detailed guidance, see these companion guides:
Always refer to the official documentation (see top of this file) when:
- Creating new component types
- Using advanced features
- Troubleshooting issues
- Following best practices
- Understanding permission models
The official documentation is the source of truth. This skill provides a practical guide, but defer to official docs for authoritative information.
