Claude Ecosystem

Claude Ecosystem

Comprehensive guide for Claude Code CLI tool, extensibility (agents/skills/output styles), and CLAUDE.md architecture.

Module Selection

Quick Reference

Extension Types

Model Selection (Agents)

CLAUDE.md Token Budget

Extensibility Principles

Core Truths

Decision Heuristics

Activation Keywords

The description field is your activation gate. Include:

1. Task verbs: create, build, debug, fix, deploy
2. Problem descriptions: slow, broken, failing
3. Artifact types: component, API, database
4. Casual synonyms: "make it faster" → optimize

Common Workflows

Create Agent

For the agent's prompt content (soul, tensions, mental models, thinking approaches), invoke Skill("prompt-architect") — it handles expertise transfer and dialectic design. This skill handles structure and frontmatter.

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

Each skill is a context engineering problem: what information does Claude need, when should it load, and how much freedom should the instructions leave?

For body content (soul, tensions, mental models, anti-patterns), invoke Skill("prompt-architect") — it handles expertise transfer and dialectic design.

Key Principles

1. Claude is smart — only add what Claude doesn't already know
2. Explain WHY — reasoning beats commands; reframe ALWAYS/NEVER as consequences
3. Be pushy in descriptions — Claude undertriggers by default; use directive language ("ALWAYS invoke")
4. Match freedom to fragility — exact scripts for dangerous ops, principles for judgment tasks
5. Generalize from examples — skills run millions of times; don't overfit

Architecture

skill-name/
├── SKILL.md          # Required: YAML frontmatter + instructions (<500 lines)
├── scripts/          # Optional: deterministic operations (execute without loading)
├── references/       # Optional: domain docs loaded as needed
└── assets/           # Optional: templates, fonts, icons for output

Creation Workflow

1. Capture Intent — mine conversation for workflow, tools, corrections before asking questions
2. Research Domain — best practices, failure modes, decision heuristics, similar skills
3. Draft SKILL.md — quick orientation → core workflow → patterns → edge cases → reference routing → frontmatter (LAST)
4. Review — token audit, freedom calibration, generalization, trigger check, "Rationalizations to Reject", "When NOT to Use"
5. Test Cases — 2-3 realistic messy prompts as users actually type
6. Iterate — generalize from feedback, keep lean, reframe don't restrict

Detailed workflow: references/skill-creation-workflow.md Writing principles: references/skill-writing-guide.md Description optimization: references/skill-description-guide.md

Deliverables

1. Complete SKILL.md with frontmatter and body
2. Directory structure with any bundled scripts/references/assets
3. 2-3 test prompts — realistic, messy, user-style
4. Description rationale — brief triggering strategy explanation

Initialize CLAUDE.md

1. Analyze codebase (language, framework, structure)
2. Extract code style, commands, patterns
3. Generate with template, customize
4. Validate commands, check token count
5. Target <400 lines, prefer <250

Detailed: references/initialization-workflow.md

Optimize CLAUDE.md

1. Evaluate token efficiency
2. Find redundancy, outdated info
3. Apply token reduction techniques
4. Target 40%+ reduction
5. Verify critical info retained

Detailed: references/optimization-patterns.md

Anti-Patterns

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, auth
• references/slash-commands.md - Complete command catalog
• references/mcp-integration.md - MCP server configuration
• references/hooks-and-plugins.md - Hook types, plugin structure
• references/configuration.md - Settings hierarchy
• references/enterprise-features.md - IAM, SSO, sandboxing
• references/cicd-integration.md - GitHub Actions, GitLab CI
• references/ide-integration.md - VS Code, JetBrains
• references/advanced-features.md - Extended thinking, caching
• references/troubleshooting.md - Common issues
• references/api-reference.md - Admin, Messages, Skills APIs
• references/best-practices.md - Project organization, security
• references/agent-skills.md - Creating skills via CLI

Extensibility

• references/agent-development.md - Full YAML structure, system prompts
• references/skill-development.md - Structure, triggers, hooks
• references/skill-creation-workflow.md - End-to-end skill creation process
• references/skill-writing-guide.md - Writing principles and mental models
• references/skill-description-guide.md - Description optimization and triggers

CLAUDE.md

• references/initialization-workflow.md - Creating new CLAUDE.md
• references/optimization-patterns.md - Token reduction techniques
• references/integration-strategies.md - Global config, MCP tools
• references/output-templates.md - Standard output formats

Skill Routing

When creating or editing skills/agents: this skill for structure → prompt-architect for body content.

Documentation:

• llms.txt: https://context7.com/websites/claude_en_claude-code/llms.txt?tokens=10000
• Main docs: https://docs.claude.com/en/docs/claude-code/
• GitHub: https://github.com/anthropics/claude-code