claude-code-development

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.

All official documentation references are maintained in docs/claude/README.md. Always consult these references for the latest standards and best practices:

• [Claude Code Settings](https://code.claude.com/docs/en/settings.md)
• [Claude Code Memory Management](https://code.claude.com/docs/en/memory.md)
• [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents.md)
• [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills.md)
• [Claude Code Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands.md)
• [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks.md)
• [Claude Code MCP Support](https://code.claude.com/docs/en/mcp.md)
• [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md)

When creating new components, fetch and review the relevant documentation using the WebFetch tool.

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):

```yaml

name: code-reviewer

description: Reviews code for quality and best practices

tools: Read, Grep, Glob

```

Skill (reusable knowledge package):

```yaml

name: api-design-patterns

description: REST API design. Use when designing or reviewing APIs.

```

Command (user-invocable workflow):

```yaml

description: Review code changes

allowed-tools: Task(code-reviewer)

```

See detailed guides: [Agents](agents-guide.md) | [Skills](skills-guide.md) | [Commands](commands-guide.md)

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](agents-guide.md) 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](skills-guide.md) 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](commands-guide.md) 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](hooks-guide.md) for complete details.

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

```

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

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.

1. Follow official documentation: Always consult official guides
2. Be concise: Assume Claude is smart, avoid over-explaining
3. Use progressive disclosure: Split large content into multiple files
4. Test thoroughly: Verify components work as expected
5. Iterate based on behavior: Watch how Claude uses components and refine
6. Keep components focused: Each component should do one thing well
7. Document clearly: Good descriptions and examples are essential
8. Use appropriate tools: Restrict tool access to minimum needed
9. Maintain consistency: Follow naming conventions and patterns
10. Version control: Check components into git for team collaboration

For detailed guidance, see these companion guides:

• [Agent Creation Guide](agents-guide.md) - Comprehensive subagent development
• [Skills Creation Guide](skills-guide.md) - Detailed skill creation with progressive disclosure
• [Commands Creation Guide](commands-guide.md) - Slash command development patterns
• [Hooks Reference Guide](hooks-guide.md) - Complete hooks documentation
• [Common Patterns & Examples](patterns-examples.md) - Practical patterns and examples

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.