Claude Ecosystem
Comprehensive guide for Claude Code CLI tool, extensibility (agents/skills/output styles), and CLAUDE.md architecture.
Module Selection
| Need |
Module |
Reference |
| Setup/Configuration |
CLI |
references/getting-started.md, references/configuration.md |
| Slash Commands |
CLI |
references/slash-commands.md |
| MCP Servers |
CLI |
references/mcp-integration.md |
| Hooks & Plugins |
CLI |
references/hooks-and-plugins.md |
| Create Agents |
Extensibility |
references/agent-development.md |
| Create Skills |
Extensibility |
references/skill-development.md |
| Output Styles |
Extensibility |
references/skill-development.md |
| Init CLAUDE.md |
Architecture |
references/initialization-workflow.md |
| Optimize CLAUDE.md |
Architecture |
references/optimization-patterns.md |
| Enterprise/CI-CD |
CLI |
references/enterprise-features.md, references/cicd-integration.md |
| Troubleshooting |
CLI |
references/troubleshooting.md |
Quick Reference
Extension Types
| Type |
Invocation |
Purpose |
Location |
| Agents |
Task tool |
Specialized sub-processes |
.claude/agents/ |
| Skills |
Model-invoked |
Domain knowledge |
.claude/skills/{name}/ |
| Output Styles |
/output-style |
Modify main agent |
.claude/output-styles/ |
Model Selection (Agents)
| Model |
Use When |
Target Time |
haiku |
Fast tasks, exploration |
< 3s |
sonnet |
Balanced, most use cases |
< 10s |
opus |
Complex reasoning |
< 30s |
CLAUDE.md Token Budget
| Complexity |
Target Tokens |
| Simple |
100-200 |
| Medium |
200-400 |
| Complex |
400-800 |
| Maximum |
1000 |
Extensibility Principles
Core Truths
| Truth |
Meaning |
| Expertise Transfer |
Make Claude think like expert, not follow steps |
| Flow, Not Friction |
Produce output, not intermediate work |
| Voice Matches Domain |
Sound like practitioner, not documentation |
| Focused Beats Comprehensive |
Constrain ruthlessly |
Decision Heuristics
| Rule |
Guidance |
| 3-File Rule |
3+ files → agent. Enhances YOUR work → skill. |
| Delegation Test |
Runs independently? Agent. Guides you? Skill. |
| Activation Breadth |
Trigger on 80% of relevant requests |
| Tool Constraint |
Start with 2-3 essential tools |
Activation Keywords
The description field is your activation gate. Include:
- Task verbs: create, build, debug, fix, deploy
- Problem descriptions: slow, broken, failing
- Artifact types: component, API, database
- Casual synonyms: "make it faster" → optimize
Common Workflows
Create Agent
---
name: agent-name
description: "Use when [use case]. PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n</example>"
tools: Grep, Glob, Read, Bash
model: haiku
---
# Agent Name
Mission statement.
## Strategy
[Approach]
## Does NOT Do
- [boundary] (use X instead)
Create Skill
---
name: skill-name
description: "[Core purpose]. [Technologies]. Capabilities: [list].
Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."
allowed-tools: Read, Grep, Glob
---
# Skill Name
## Patterns
### [Pattern Name]
**When you see:** [Observable trigger]
**This indicates:** [Expert insight]
**Therefore:** [Action]
**Watch out:** [Pitfall]
Initialize CLAUDE.md
- Analyze codebase (language, framework, structure)
- Extract code style, commands, patterns
- Generate with template, customize
- Validate commands, check token count
- Target <400 lines, prefer <250
Detailed: references/initialization-workflow.md
Optimize CLAUDE.md
- Evaluate token efficiency
- Find redundancy, outdated info
- Apply token reduction techniques
- Target 40%+ reduction
- Verify critical info retained
Detailed: references/optimization-patterns.md
Anti-Patterns
| Pattern |
Problem |
Fix |
| Kitchen Sink Agent |
10+ tools, handles "everything" |
Constrain to 3-5 tools |
| Echo Skill |
Restates docs without insight |
Add expert layer |
| Invisible Trigger |
Description uses only formal terms |
Include user language |
| Procedure Manual |
Step 1, 2, 3... |
Teach patterns, not steps |
| Over-Documentation |
CLAUDE.md > 400 lines |
Document project-specific only |
Quality Signals
Good Signs
- Frontmatter reads like "when to use" guide
- First 10 lines provide actionable guidance
- Expert would nod "yes, that's how I think"
- Explicit constraints on what it does NOT handle
Warning Signs
50% reference tables or field definitions
- No mention of "when NOT to use"
- Generic language for any domain
- Body exceeds 600 lines
References
CLI Tool
references/getting-started.md - Installation, setup, authreferences/slash-commands.md - Complete command catalogreferences/mcp-integration.md - MCP server configurationreferences/hooks-and-plugins.md - Hook types, plugin structurereferences/configuration.md - Settings hierarchyreferences/enterprise-features.md - IAM, SSO, sandboxingreferences/cicd-integration.md - GitHub Actions, GitLab CIreferences/ide-integration.md - VS Code, JetBrainsreferences/advanced-features.md - Extended thinking, cachingreferences/troubleshooting.md - Common issuesreferences/api-reference.md - Admin, Messages, Skills APIsreferences/best-practices.md - Project organization, securityreferences/agent-skills.md - Creating skills via CLI
Extensibility
references/agent-development.md - Full YAML structure, system promptsreferences/skill-development.md - Structure, triggers, hooks
CLAUDE.md
references/initialization-workflow.md - Creating new CLAUDE.mdreferences/optimization-patterns.md - Token reduction techniquesreferences/integration-strategies.md - Global config, MCP toolsreferences/output-templates.md - Standard output formats
Related Skills
IMPORTANT: When creating/editing prompts, use prompt-architect skill.
Skill("prompt-architect") → Create/enhance skill/agent prompt content
Documentation:
1---2name: claude-ecosystem3description: Claude Code ecosystem expertise. Modules: CLI tool (setup, slash commands, MCP servers, hooks, plugins, CI/CD), extensibility (agents, skills, output styles creation), CLAUDE.md (project instructions, optimization). Actions: configure, troubleshoot, create, deploy, integrate, optimize Claude Code. Keywords: Claude Code, Anthropic, CLI tool, slash command, MCP server, Agent Skill, hook, plugin, CI/CD, enterprise, CLAUDE.md, agentic coding, agent, skill, output-style, SKILL.md, subagent, Task tool, project instructions, token optimization. Use when: learning Claude Code features, configuring settings, creating skills/agents/hooks, setting up MCP servers, troubleshooting issues, CI/CD integration, initializing or optimizing CLAUDE.md files.4---56# Claude Ecosystem78Comprehensive guide for Claude Code CLI tool, extensibility (agents/skills/output styles), and CLAUDE.md architecture.910## Module Selection1112| Need | Module | Reference |13|------|--------|-----------|14| **Setup/Configuration** | CLI | `references/getting-started.md`, `references/configuration.md` |15| **Slash Commands** | CLI | `references/slash-commands.md` |16| **MCP Servers** | CLI | `references/mcp-integration.md` |17| **Hooks & Plugins** | CLI | `references/hooks-and-plugins.md` |18| **Create Agents** | Extensibility | `references/agent-development.md` |19| **Create Skills** | Extensibility | `references/skill-development.md` |20| **Output Styles** | Extensibility | `references/skill-development.md` |21| **Init CLAUDE.md** | Architecture | `references/initialization-workflow.md` |22| **Optimize CLAUDE.md** | Architecture | `references/optimization-patterns.md` |23| **Enterprise/CI-CD** | CLI | `references/enterprise-features.md`, `references/cicd-integration.md` |24| **Troubleshooting** | CLI | `references/troubleshooting.md` |2526---2728## Quick Reference2930### Extension Types3132| Type | Invocation | Purpose | Location |33|------|------------|---------|----------|34| **Agents** | Task tool | Specialized sub-processes | `.claude/agents/` |35| **Skills** | Model-invoked | Domain knowledge | `.claude/skills/{name}/` |36| **Output Styles** | `/output-style` | Modify main agent | `.claude/output-styles/` |3738### Model Selection (Agents)3940| Model | Use When | Target Time |41|-------|----------|-------------|42| `haiku` | Fast tasks, exploration | < 3s |43| `sonnet` | Balanced, most use cases | < 10s |44| `opus` | Complex reasoning | < 30s |4546### CLAUDE.md Token Budget4748| Complexity | Target Tokens |49|-----------|---------------|50| Simple | 100-200 |51| Medium | 200-400 |52| Complex | 400-800 |53| Maximum | 1000 |5455---5657## Extensibility Principles5859### Core Truths6061| Truth | Meaning |62|-------|---------|63| **Expertise Transfer** | Make Claude *think* like expert, not follow steps |64| **Flow, Not Friction** | Produce output, not intermediate work |65| **Voice Matches Domain** | Sound like practitioner, not documentation |66| **Focused Beats Comprehensive** | Constrain ruthlessly |6768### Decision Heuristics6970| Rule | Guidance |71|------|----------|72| **3-File Rule** | 3+ files → agent. Enhances YOUR work → skill. |73| **Delegation Test** | Runs independently? Agent. Guides you? Skill. |74| **Activation Breadth** | Trigger on 80% of relevant requests |75| **Tool Constraint** | Start with 2-3 essential tools |7677### Activation Keywords7879**The description field is your activation gate.** Include:801. Task verbs: create, build, debug, fix, deploy812. Problem descriptions: slow, broken, failing823. Artifact types: component, API, database834. Casual synonyms: "make it faster" → optimize8485---8687## Common Workflows8889### Create Agent9091```yaml92---93name: agent-name94description: "Use when [use case]. PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n</example>"95tools: Grep, Glob, Read, Bash96model: haiku97---9899# Agent Name100101Mission statement.102103## Strategy104[Approach]105106## Does NOT Do107- [boundary] (use X instead)108```109110### Create Skill111112```yaml113---114name: skill-name115description: "[Core purpose]. [Technologies]. Capabilities: [list].116 Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."117allowed-tools: Read, Grep, Glob118---119120# Skill Name121122## Patterns123124### [Pattern Name]125**When you see:** [Observable trigger]126**This indicates:** [Expert insight]127**Therefore:** [Action]128**Watch out:** [Pitfall]129```130131### Initialize CLAUDE.md1321331. Analyze codebase (language, framework, structure)1342. Extract code style, commands, patterns1353. Generate with template, customize1364. Validate commands, check token count1375. Target <400 lines, prefer <250138139**Detailed:** `references/initialization-workflow.md`140141### Optimize CLAUDE.md1421431. Evaluate token efficiency1442. Find redundancy, outdated info1453. Apply token reduction techniques1464. Target 40%+ reduction1475. Verify critical info retained148149**Detailed:** `references/optimization-patterns.md`150151---152153## Anti-Patterns154155| Pattern | Problem | Fix |156|---------|---------|-----|157| **Kitchen Sink Agent** | 10+ tools, handles "everything" | Constrain to 3-5 tools |158| **Echo Skill** | Restates docs without insight | Add expert layer |159| **Invisible Trigger** | Description uses only formal terms | Include user language |160| **Procedure Manual** | Step 1, 2, 3... | Teach patterns, not steps |161| **Over-Documentation** | CLAUDE.md > 400 lines | Document project-specific only |162163---164165## Quality Signals166167### Good Signs168- Frontmatter reads like "when to use" guide169- First 10 lines provide actionable guidance170- Expert would nod "yes, that's how I think"171- Explicit constraints on what it does NOT handle172173### Warning Signs174- >50% reference tables or field definitions175- No mention of "when NOT to use"176- Generic language for any domain177- Body exceeds 600 lines178179---180181## References182183### CLI Tool184- `references/getting-started.md` - Installation, setup, auth185- `references/slash-commands.md` - Complete command catalog186- `references/mcp-integration.md` - MCP server configuration187- `references/hooks-and-plugins.md` - Hook types, plugin structure188- `references/configuration.md` - Settings hierarchy189- `references/enterprise-features.md` - IAM, SSO, sandboxing190- `references/cicd-integration.md` - GitHub Actions, GitLab CI191- `references/ide-integration.md` - VS Code, JetBrains192- `references/advanced-features.md` - Extended thinking, caching193- `references/troubleshooting.md` - Common issues194- `references/api-reference.md` - Admin, Messages, Skills APIs195- `references/best-practices.md` - Project organization, security196- `references/agent-skills.md` - Creating skills via CLI197198### Extensibility199- `references/agent-development.md` - Full YAML structure, system prompts200- `references/skill-development.md` - Structure, triggers, hooks201202### CLAUDE.md203- `references/initialization-workflow.md` - Creating new CLAUDE.md204- `references/optimization-patterns.md` - Token reduction techniques205- `references/integration-strategies.md` - Global config, MCP tools206- `references/output-templates.md` - Standard output formats207208---209210## Related Skills211212**IMPORTANT:** When creating/editing prompts, use `prompt-architect` skill.213214```215Skill("prompt-architect") → Create/enhance skill/agent prompt content216```217218---219220**Documentation:**221- llms.txt: https://context7.com/websites/claude_en_claude-code/llms.txt?tokens=10000222- Main docs: https://docs.claude.com/en/docs/claude-code/223- GitHub: https://github.com/anthropics/claude-code
diegosouzapw