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

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

code

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

•Agent Creation Guide - Comprehensive subagent development
•Skills Creation Guide - Detailed skill creation with progressive disclosure
•Commands Creation Guide - Slash command development patterns
•Hooks Reference Guide - Complete hooks documentation
•Common Patterns & Examples - 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.