diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index c8f32e0..0000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "name": "stepwise-dev", - "owner": { - "name": "Jorge Castro", - "email": "nikey_es@yahoo.es" - }, - "metadata": { - "description": "Step-by-step development: Research → Plan → Implement → Validate with context control", - "version": "0.0.4" - }, - "plugins": [ - { - "name": "stepwise-dev", - "source": "./", - "description": "Research → Plan → Implement → Validate workflow with local thoughts/ management", - "version": "0.0.4", - "category": "productivity", - "keywords": ["workflow", "planning", "tdd", "documentation", "development"], - "strict": true - } - ] -} diff --git a/.claude/settings.json b/.claude/settings.json index c11d684..cae04e6 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -4,6 +4,7 @@ "Bash(make test:*)", "Bash(make check:*)", "Bash(make ci:*)", - "Skill(stepwise-dev:thoughts-management)" + "Skill(stepwise-dev:thoughts-management)", + "Bash(ls:*)" ]} } \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 622326e..35fd392 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,52 +8,79 @@ This is a **workflow tooling project for Claude Code itself**, not a traditional The workflow operates entirely locally without cloud dependencies and uses a `thoughts/` directory system with hardlinks for efficient searching. -## Plugin Structure +## Multi-Plugin Architecture -This project is distributed as a Claude Code plugin: +This project is distributed as **3 independent Claude Code plugins** in a single marketplace: -**Plugin Name**: `stepwise-dev` +### Plugin 1: stepwise-core +**Location**: `core/` +**Components**: +- 5 slash commands (research_codebase, create_plan, iterate_plan, implement_plan, validate_plan) +- 5 specialized agents (codebase-locator, codebase-analyzer, codebase-pattern-finder, thoughts-locator, thoughts-analyzer) +- 1 Agent Skill (thoughts-management with 3 bash scripts) + +### Plugin 2: stepwise-git +**Location**: `git/` +**Components**: +- 1 slash command (commit) +### Plugin 3: stepwise-web +**Location**: `web/` **Components**: -- 6 slash commands in `commands/` (at plugin root) -- 5 specialized agents in `agents/` (at plugin root) -- 1 Agent Skill in `skills/` (for thoughts/ management) +- 1 specialized agent (web-search-researcher) **Installation**: -- Plugin: Via `/plugin install stepwise-dev@stepwise-dev` -- No additional steps required - the Skill is included in the plugin +```bash +# Add marketplace +/plugin marketplace add nikeyes/stepwise-dev -**Note**: Commands and agents are at the plugin root, NOT in a `.claude/` subdirectory. -This follows Claude Code plugin conventions and prevents confusion with the actual -`~/.claude/` installation directory. +# Install all three (or pick individual ones) +/plugin install stepwise-core@stepwise-dev +/plugin install stepwise-git@stepwise-dev +/plugin install stepwise-web@stepwise-dev +``` See README.md for detailed installation instructions. ## Project Structure ``` -commands/ # 6 slash commands (markdown files) -├── research_codebase.md -├── create_plan.md -├── iterate_plan.md -├── implement_plan.md -├── validate_plan.md -└── commit.md - -agents/ # 5 specialized agents (markdown files) -├── codebase-locator.md -├── codebase-analyzer.md -├── codebase-pattern-finder.md -├── thoughts-locator.md -└── thoughts-analyzer.md - -skills/ # 1 Agent Skill -└── thoughts-management/ - ├── SKILL.md # Skill instructions - └── scripts/ # Bash scripts for thoughts/ operations - ├── thoughts-init - ├── thoughts-sync - └── thoughts-metadata +marketplace.json # Marketplace listing all 3 plugins + +core/ # stepwise-core plugin +├── .claude-plugin/ +│ └── plugin.json +├── commands/ # 5 slash commands (markdown files) +│ ├── research_codebase.md +│ ├── create_plan.md +│ ├── iterate_plan.md +│ ├── implement_plan.md +│ └── validate_plan.md +├── agents/ # 5 specialized agents (markdown files) +│ ├── codebase-locator.md +│ ├── codebase-analyzer.md +│ ├── codebase-pattern-finder.md +│ ├── thoughts-locator.md +│ └── thoughts-analyzer.md +└── skills/ # 1 Agent Skill + └── thoughts-management/ + ├── SKILL.md + └── scripts/ + ├── thoughts-init + ├── thoughts-sync + └── thoughts-metadata + +git/ # stepwise-git plugin +├── .claude-plugin/ +│ └── plugin.json +└── commands/ # 1 slash command + └── commit.md + +web/ # stepwise-web plugin +├── .claude-plugin/ +│ └── plugin.json +└── agents/ # 1 specialized agent + └── web-search-researcher.md test/ # Automated bash tests (for development) ``` @@ -62,12 +89,14 @@ test/ # Automated bash tests (for development) ### Installation ```bash -# Install plugin in Claude Code +# Install plugins in Claude Code /plugin marketplace add nikeyes/stepwise-dev -/plugin install stepwise-dev@stepwise-dev +/plugin install stepwise-core@stepwise-dev +/plugin install stepwise-git@stepwise-dev +/plugin install stepwise-web@stepwise-dev # Restart Claude Code -# That's it! The thoughts-management Skill is included in the plugin +# That's it! All components are included in the respective plugins # No additional installation steps required ``` @@ -91,9 +120,9 @@ make check ``` **What's covered:** -- ✅ `skills/thoughts-management/scripts/thoughts-init` - Directory creation, gitignore, README generation -- ✅ `skills/thoughts-management/scripts/thoughts-sync` - Hardlink creation, orphan cleanup -- ✅ `skills/thoughts-management/scripts/thoughts-metadata` - Metadata generation +- ✅ `core/skills/thoughts-management/scripts/thoughts-init` - Directory creation, gitignore, README generation +- ✅ `core/skills/thoughts-management/scripts/thoughts-sync` - Hardlink creation, orphan cleanup +- ✅ `core/skills/thoughts-management/scripts/thoughts-metadata` - Metadata generation **Test files:** - `test/smoke-test.sh` - Main integration tests (7 test groups) @@ -105,31 +134,31 @@ make check Commands, agents, and skills require manual validation in Claude Code: 1. **Test slash commands in Claude Code:** - - Commands are loaded via the plugin + - Commands are loaded via the plugins - After modifying a command file, restart Claude Code or use `/plugin reload` - - Test by invoking: `/stepwise-dev:research_codebase`, `/stepwise-dev:create_plan`, etc. + - Test by invoking: `/stepwise-core:research_codebase`, `/stepwise-git:commit`, etc. 2. **Validate agents:** - Agents spawn as sub-tasks when commands execute - - Test by running commands that use them (e.g., `/stepwise-dev:research_codebase` spawns `codebase-locator`) + - Test by running commands that use them (e.g., `/stepwise-core:research_codebase` spawns `codebase-locator`) - Check agent behavior in Claude Code's task output 3. **Test the thoughts-management Skill:** - The Skill activates automatically when Claude needs to manage thoughts/ - - Test by creating research documents or plans + - Test by creating research documents or plans with stepwise-core - Verify Claude calls the Skill to sync and gather metadata ### Iterative Development Cycle When modifying **commands/agents/skills**: -1. **Edit** the file in `commands/`, `agents/`, or `skills/` -2. **Test locally** via plugin development mode or by reinstalling the plugin +1. **Edit** the file in `core/commands/`, `core/agents/`, `git/commands/`, `web/agents/`, etc. +2. **Test locally** via plugin development mode or by reinstalling the specific plugin 3. **Validate** in a sample project 4. **Iterate** based on results When modifying **scripts in the Skill**: -1. **Edit** the file in `skills/thoughts-management/scripts/` -2. **Reinstall** the plugin or test in development mode +1. **Edit** the file in `core/skills/thoughts-management/scripts/` +2. **Reinstall** stepwise-core plugin or test in development mode 3. **Test** by triggering the Skill (create research docs, plans, etc.) 4. **Iterate** based on results @@ -177,25 +206,28 @@ thoughts/ ### Version Management -**Plugin version:** +**Plugin versions:** - Managed by Claude Code plugin system -- Check with `/plugin list` or `/plugin show stepwise-dev@stepwise-dev` -- Update with `/plugin update stepwise-dev@stepwise-dev` +- Check with `/plugin list` +- Update individual plugins: + - `/plugin update stepwise-core@stepwise-dev` + - `/plugin update stepwise-git@stepwise-dev` + - `/plugin update stepwise-web@stepwise-dev` **Scripts:** -- Updated automatically when plugin updates -- Part of the plugin package, no separate installation +- Updated automatically when stepwise-core plugin updates +- Part of the stepwise-core plugin package, no separate installation ## Development Workflow For **scripts**: -1. Edit file in `skills/thoughts-management/scripts/` +1. Edit file in `core/skills/thoughts-management/scripts/` 2. Test using `make test` (runs automated tests) 3. Test manually by triggering the Skill in Claude Code 4. Iterate based on results For **commands/agents**: -1. Edit file in `commands/` or `agents/` +1. Edit file in the specific plugin directory (`core/commands/`, `git/commands/`, `web/agents/`, etc.) 2. Test via plugin reload or development mode 3. Validate in Claude Code 4. Iterate diff --git a/README.md b/README.md index 4d2ce56..c597a73 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Claude Code Stepwise Dev Plugin +# Stepwise Dev - Multi-Plugin Suite [![Plugin Available](https://img.shields.io/badge/Claude_Code-Plugin_Available-blue)](https://github.com/nikeyes/stepwise-dev) [![License](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE) [![Tests](https://img.shields.io/badge/Tests-Passing-brightgreen)](test/) -A development workflow for Claude Code inspired by [Ashley Ha's workflow](https://medium.com/@ashleyha/i-mastered-the-claude-code-workflow-145d25e502cf), adapted to work 100% locally with thoughts. +A modular development workflow suite for Claude Code inspired by [Ashley Ha's workflow](https://medium.com/@ashleyha/i-mastered-the-claude-code-workflow-145d25e502cf), adapted to work 100% locally with thoughts. **📖 Read more**: [Tu CLAUDE.md no funciona sin Context Engineering](https://nikeyes.github.io/tu-claude-md-no-funciona-sin-context-engineering-es/) (Spanish article about Stepwise-dev) @@ -12,79 +12,86 @@ A development workflow for Claude Code inspired by [Ashley Ha's workflow](https: Solves the context management problem: LLMs lose attention after 60% context usage. -Implements **Research -> Plan -> Implement -> Validate** with frequent `/clear` and persistent `thoughts/` storage. - -- **6 Slash Commands** for structured development -- **5 Specialized Agents** for parallel research -- **3 Bash Scripts** for local thoughts/ management -- **Built-in version tracking** for team synchronization +Implements **Research → Plan → Implement → Validate** with frequent `/clear` and persistent `thoughts/` storage. ### Philosophy - Keep context < 60% (attention threshold) -- Split work into phases. +- Split work into phases - Clear between phases, save to `thoughts/` - Never lose research or decisions -## 📦 What's Included +## 📦 Available Plugins + +This repository contains **3 independent plugins** that can be installed separately based on your needs: + +### 1. **stepwise-core** (Core Workflow) +The foundation plugin with the complete Research → Plan → Implement → Validate cycle. -### Slash Commands +**Includes:** +- 5 slash commands (`research_codebase`, `create_plan`, `iterate_plan`, `implement_plan`, `validate_plan`) +- 5 specialized agents (codebase exploration and thoughts management) +- 1 thoughts-management skill (with 3 bash scripts) -| Command | Description | -|---------|-------------| -| `/stepwise-dev:research_codebase` | Research and document codebase comprehensively | -| `/stepwise-dev:create_plan` | Create detailed implementation plans iteratively | -| `/stepwise-dev:iterate_plan` | Update existing implementation plans | -| `/stepwise-dev:implement_plan` | Execute plans phase by phase with validation | -| `/stepwise-dev:validate_plan` | Validate implementation against plan | -| `/stepwise-dev:commit` | Create git commits (no Claude attribution) | +[→ Read more](./core/README.md) -### Specialized Agents +### 2. **stepwise-git** (Git Operations) +Clean git commit workflow without Claude attribution. -| Agent | Purpose | -|-------|---------| -| `codebase-locator` | Find WHERE code lives in the codebase | -| `codebase-analyzer` | Understand HOW code works | -| `codebase-pattern-finder` | Find similar patterns to model after | -| `thoughts-locator` | Discover documents in thoughts/ | -| `thoughts-analyzer` | Extract insights from thoughts docs | +**Includes:** +- 1 slash command (`commit`) +- Smart staging and commit message generation -### Thoughts Scripts (Included in Plugin) +[→ Read more](./git/README.md) -| Script | Purpose | -|--------|---------| -| `thoughts-init` | Initialize thoughts/ structure in a project | -| `thoughts-sync` | Sync hardlinks in searchable/ directory | -| `thoughts-metadata` | Generate git metadata for documents | +### 3. **stepwise-web** (Web Research) +Web search and research capabilities for external context. -**Note**: These scripts are executed automatically by the `thoughts-management` Skill. You don't need to install them separately or configure PATH. +**Includes:** +- 1 specialized agent (`web-search-researcher`) +- Deep web research with source citations + +[→ Read more](./web/README.md) ## 🚀 Installation +### Option 1: Install All Plugins (Recommended for first-time users) + ```bash # Add marketplace from GitHub /plugin marketplace add nikeyes/stepwise-dev -# Install plugin -/plugin install stepwise-dev@stepwise-dev +# Install all three plugins +/plugin install stepwise-core@stepwise-dev +/plugin install stepwise-git@stepwise-dev +/plugin install stepwise-web@stepwise-dev ``` -**Restart Claude Code after installation.** +### Option 2: Install Only What You Need + +```bash +# Add marketplace +/plugin marketplace add nikeyes/stepwise-dev -That's it! The plugin includes: -- 6 slash commands -- 5 specialized agents -- 1 thoughts-management Skill (with 3 bash scripts) +# Install only the core workflow +/plugin install stepwise-core@stepwise-dev -All components are ready to use immediately after installation. +# Optionally add git operations +/plugin install stepwise-git@stepwise-dev + +# Optionally add web research +/plugin install stepwise-web@stepwise-dev +``` + +**Restart Claude Code after installation.** ## 🧪 Try It Out -Don't have a project to test with? Use [stepwise-todo-api-test](https://github.com/nikeyes/stepwise-todo-api-test) — a sample repository with small and large tasks designed for testing this plugin in an isolated environment. +Don't have a project to test with? Use [stepwise-todo-api-test](https://github.com/nikeyes/stepwise-todo-api-test) — a sample repository designed for testing these plugins. ## 📁 Directory Structure -After running `thoughts-init` in a project: +After running `thoughts-init` (from stepwise-core) in a project: ``` / @@ -97,8 +104,8 @@ After running `thoughts-init` in a project: │ │ ├── plans/ # Implementation plans │ │ └── prs/ # PR descriptions │ └── searchable/ # Hardlinks for grep (auto-generated) -│ ├── nikey_es/ # -> hardlinks to nikey_es/ -│ └── shared/ # -> hardlinks to shared/ +│ ├── nikey_es/ # → hardlinks to nikey_es/ +│ └── shared/ # → hardlinks to shared/ ├── .gitignore # (add thoughts/searchable/ to this) └── ... ``` @@ -106,7 +113,6 @@ After running `thoughts-init` in a project: **Key distinction:** - **`nikey_es/`**: Personal tickets/notes you create manually - **`shared/`**: Formal docs Claude generates from commands -- **Example**: `/create_plan thoughts/nikey_es/tickets/eng_1234.md` reads your ticket → writes `shared/plans/2025-11-09-ENG-1234-*.md` ### Why Hardlinks? @@ -115,314 +121,146 @@ After running `thoughts-init` in a project: - **Auto-sync**: Changes in source are immediately visible - **Efficient**: Better than symlinks for grep operations -## Thoughts Directory - -This directory contains research documents, implementation plans, and notes for this project. - -### Structure - -- `nikey_es/` - Personal notes and tickets - - `tickets/` - Ticket documentation and tracking - - `notes/` - Personal notes and observations -- `shared/` - Team-shared documents - - `research/` - Research documents from /stepwise-dev:research_codebase - - `plans/` - Implementation plans from /stepwise-dev:create_plan - - `prs/` - PR descriptions and documentation -- `searchable/` - Hardlinks for efficient grep searching (auto-generated) - -### Usage - -Use Claude Code slash commands: -- `/stepwise-dev:research_codebase [topic]` - Research and document codebase -- `/stepwise-dev:create_plan [description]` - Create implementation plan -- `/stepwise-dev:implement_plan [plan-file]` - Execute a plan -- `/stepwise-dev:validate_plan [plan-file]` - Validate implementation - -Run `thoughts-sync` after adding/modifying files to update searchable/ hardlinks. - - ## 🔄 The Four-Phase Workflow -### Phase 1: Research - -**Goal**: Understand what exists before changing anything. +### Phase 1: Research (stepwise-core) ```bash -# In Claude Code -/stepwise-dev:research_codebase How does authentication work in this app? +/stepwise-core:research_codebase How does authentication work? ``` -This will: -1. Spawn parallel agents to search the codebase -2. Search thoughts/ for historical context -3. Generate a comprehensive research document -4. Save to `thoughts/shared/research/YYYY-MM-DD-topic.md` -5. Run `thoughts-sync` to update searchable/ - -**Output**: Research document with code references, architecture insights, and file:line numbers. +Spawns parallel agents, searches codebase and thoughts/, generates comprehensive research document. -### Phase 2: Plan - -**Goal**: Create a detailed, iterative implementation plan. +### Phase 2: Plan (stepwise-core) ```bash -# In Claude Code -/stepwise-dev:create_plan Add rate limiting to the API -# Or reference a research doc: -/stepwise-dev:create_plan @thoughts/shared/research/2025-11-09-auth-system.md +/stepwise-core:create_plan Add rate limiting to the API ``` -This will: -1. Ask clarifying questions -2. Research existing patterns in the codebase -3. Iterate with you 5+ times on the plan -4. Create phases with specific changes -5. Define automated AND manual success criteria -6. Save to `thoughts/shared/plans/YYYY-MM-DD-topic.md` - -**Output**: Detailed plan with phases, file paths, code snippets, and verification steps. +Iterates with you 5+ times, creates detailed phases with verification steps. -### Phase 3: Implement - -**Goal**: Execute one phase at a time with confidence. +### Phase 3: Implement (stepwise-core) ```bash -# In Claude Code -/stepwise-dev:implement_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md +/stepwise-core:implement_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md ``` -This will: -1. Read the complete plan -2. Implement Phase 1 -3. Run automated verification (tests, linting) -4. **Pause for manual verification** -5. Wait for your confirmation -6. Proceed to Phase 2 (or stop) - -**Key Rule**: One phase at a time. Validate before proceeding. +Executes one phase at a time, validates before proceeding. -### Phase 4: Validate - -**Goal**: Systematically verify the entire implementation. +### Phase 4: Validate (stepwise-core) ```bash -# In Claude Code -/stepwise-dev:validate_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md +/stepwise-core:validate_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md ``` -This will: -1. Check all phases are complete -2. Run all automated verification -3. Review code against plan -4. Identify deviations or issues -5. Generate validation report - -**Output**: Report showing what passed, what needs fixing, and manual test checklist. +Systematically verifies the entire implementation. -## 💡 Usage Examples - -### Example 1: Feature Development +### Commit (stepwise-git) ```bash -# 1. Research -/stepwise-dev:research_codebase Where is user registration handled? -# → Saves to thoughts/shared/research/2025-11-09-user-registration.md -# → /context shows 45% -# → /clear - -# 2. Plan -/stepwise-dev:create_plan Add OAuth login support -# → Iterates 5 times -# → Saves to thoughts/shared/plans/2025-11-09-oauth-login.md -# → /context shows 58% -# → /clear - -# 3. Implement (Phase 1 only) -/stepwise-dev:implement_plan @thoughts/shared/plans/2025-11-09-oauth-login.md -# → Completes Phase 1 -# → Runs tests -# → Pauses for manual testing -# → You verify it works -# → "Continue to Phase 2" -# → /context shows 62% -# → /clear - -# 4. Validate -/stepwise-dev:validate_plan @thoughts/shared/plans/2025-11-09-oauth-login.md -# → Comprehensive verification -# → /context shows 41% - -# 5. Commit -/stepwise-dev:commit -# → Creates atomic commits +/stepwise-git:commit ``` -### Example 2: Bug Investigation - -```bash -# Research the bug -/stepwise-dev:research_codebase Why are webhooks timing out after 30 seconds? +Creates clean commits without Claude attribution. -# Create a fix plan -/stepwise-dev:create_plan Fix webhook timeout issue based on @thoughts/shared/research/...md - -# Implement the fix -/stepwise-dev:implement_plan @thoughts/shared/plans/...md - -# Commit -/stepwise-dev:commit -``` +## 💡 Usage Examples -### Example 3: Iterating on a Plan +### Example 1: Complete Feature Development ```bash -# You've created a plan but need to adjust it -/stepwise-dev:iterate_plan @thoughts/shared/plans/2025-11-09-feature.md +# Research (core) +/stepwise-core:research_codebase Where is user registration handled? +# /clear -# Claude asks: What changes would you like to make? -# You: "Add error handling phase before deployment" +# Plan (core) +/stepwise-core:create_plan Add OAuth login support +# /clear -# Claude updates the plan in place -``` - -## 🛠️ Thoughts Scripts +# Implement (core) +/stepwise-core:implement_plan @thoughts/shared/plans/...md +# /clear -### thoughts-init +# Validate (core) +/stepwise-core:validate_plan @thoughts/shared/plans/...md -Initialize thoughts/ in current project: - -```bash -cd ~/projects/my-app -thoughts-init +# Commit (git) +/stepwise-git:commit ``` -Creates structure, README, .gitignore, and runs initial sync. - -### thoughts-sync - -Sync hardlinks in searchable/: +### Example 2: Using Web Research ```bash -thoughts-sync -``` - -Run this: -- After adding new .md files -- After modifying file structure -- If searchable/ seems out of sync +# Research external best practices (web) +"What are the best practices for implementing rate limiting in REST APIs?" +# The web-search-researcher agent will be invoked automatically -The scripts automatically run this after `/research_codebase` and `/create_plan`. - -### thoughts-metadata - -Generate metadata for the current repo: - -```bash -thoughts-metadata -``` +# Research your codebase (core) +/stepwise-core:research_codebase Where do we handle API rate limiting? -Returns: -``` -Current Date/Time (TZ): 2025-11-09 15:30:00 PST -ISO DateTime: 2025-11-09T23:30:00+0000 -Date Short: 2025-11-09 -Current Git Commit Hash: abc123... -Current Branch Name: main -Repository Name: my-app -Git User: nikey_es +# Continue with plan and implementation... ``` -Used internally by commands to populate frontmatter. - ## 🏷️ Version Management -### Checking Plugin Version - ```bash -/plugin -# Check on Installed tab -``` - -### Updating +# Check versions +/plugin list -```bash -/plugin -> Marketplaces tab -> stepwise-dev -> Update marketplace -/plugin -> Installed -> stepwise-dev -> Update now +# Update all plugins +/plugin update stepwise-core@stepwise-dev +/plugin update stepwise-git@stepwise-dev +/plugin update stepwise-web@stepwise-dev ``` -**Note**: Plugin updates include commands, agents, and scripts automatically. No separate script installation needed. - ## 📝 Context Management **Golden Rule**: Never exceed 60% context capacity. -Check context frequently: ```bash -/context -``` - -Clear between phases: -```bash -/clear +/context # Check current usage +/clear # Clear between phases ``` ## 🔧 Customization -**Change Username**: Set `export THOUGHTS_USER=your_name` or edit `skills/thoughts-management/scripts/thoughts-init:8` - -**Add Commands**: Create `.md` files in `~/.claude/commands/` with frontmatter. Claude auto-detects on restart. +**Change Username**: Set `export THOUGHTS_USER=your_name` or edit the thoughts-init script. ## 🧪 Testing ```bash -make test # Run all automated tests (functional + structure) +make test # Run all automated tests make test-verbose # Run tests with debug output -make check # Run shellcheck on all bash scripts -make ci # Run full CI validation (test + check + plugin) +make check # Run shellcheck on bash scripts +make ci # Run full CI validation ``` -Tests validate bash scripts (thoughts-init, thoughts-sync, thoughts-metadata) and plugin structure. No dependencies needed, runs in isolated temp directories. - -**Test structure:** -- `test/thoughts-structure-test.sh` - Functional tests for thoughts/ operations -- `test/plugin-structure-test.sh` - Plugin structure validation -- `test/test-helpers.sh` - Test utilities and assertions -- `test/commands/` - Test command definitions - ## 🐛 Troubleshooting ### Plugin Issues -**Commands not showing after installation**: -- Restart Claude Code completely -- Check plugin is enabled: `/plugin list` -- Try reinstalling: `/plugin uninstall stepwise-dev@stepwise-dev` then `/plugin install stepwise-dev@stepwise-dev` +**Commands not showing**: +- Restart Claude Code +- Check plugins enabled: `/plugin list` +- Reinstall if needed **Plugin installation fails**: -- Verify marketplace added: `/plugin marketplace list` -- Check network connection (for GitHub marketplaces) -- Try local marketplace for testing: `/plugin marketplace add ./test-marketplace` +- Verify marketplace: `/plugin marketplace list` +- Check network connection ### Workflow Issues -**Hardlinks failing**: Script auto-falls back to symlinks (slower but works) +**Hardlinks failing**: Auto-falls back to symlinks -**No files synced**: Run `THOUGHTS_DEBUG=1 thoughts-sync` to debug - -**Plugin version mismatch**: Update plugin with `/plugin update stepwise-dev@stepwise-dev`. All components (commands, agents, scripts) update together. +**No files synced**: Run `THOUGHTS_DEBUG=1 thoughts-sync` ## 📚 Learn More -- **Original Article**: [I mastered the Claude Code workflow](https://medium.com/@ashleybcha/i-mastered-the-claude-code-workflow-d7ea726b38fd) by Ashley Ha +- **Original Article**: [I mastered the Claude Code workflow](https://medium.com/@ashleyha/i-mastered-the-claude-code-workflow-145d25e502cf) by Ashley Ha - **HumanLayer**: Original inspiration from [HumanLayer's .claude directory](https://github.com/humanlayer/humanlayer) ## 🤝 Contributing -This is extracted from HumanLayer and adapted for local use. If you have improvements: - -1. Test them in your workflow -2. Document what changed and why -3. Share with the community +Test improvements in your workflow, document changes, and share with the community. ## 📄 License @@ -430,25 +268,25 @@ Apache License 2.0 - See LICENSE file for details. ## 🔖 Attribution -This project is derived from [HumanLayer's Claude Code workflow](https://github.com/humanlayer/humanlayer/tree/main/.claude) under Apache License 2.0. +Derived from [HumanLayer's Claude Code workflow](https://github.com/humanlayer/humanlayer/tree/main/.claude) under Apache License 2.0. See [NOTICE](NOTICE) for detailed attribution. -**Major enhancements and modifications**: -- Specialized agent system for efficient codebase exploration (5 custom agents) -- Local-only thoughts/ management with Agent Skill (no cloud dependencies) -- Automated testing infrastructure for bash scripts -- Standalone plugin distribution system -- Enhanced TDD-focused success criteria guidelines +**Major enhancements**: +- Multi-plugin architecture for modular installation +- Specialized agent system (6 custom agents) +- Local-only thoughts/ management with Agent Skill +- Automated testing infrastructure +- Enhanced TDD-focused success criteria ## 🙏 Credits -- **[Ashley Ha](https://medium.com/@ashleyha)** - For documenting and popularizing this workflow -- **HumanLayer Team** ([Dex Horthy](https://x.com/dexhorthy) et al.) - For creating the original commands and agents -- **Anthropic** - For [Claude Code](https://claude.com/product/claude-code) +- **[Ashley Ha](https://medium.com/@ashleyha)** - Workflow documentation +- **HumanLayer Team** ([Dex Horthy](https://x.com/dexhorthy) et al.) - Original commands and agents +- **Anthropic** - [Claude Code](https://claude.com/product/claude-code) --- **Happy Coding! 🚀** -Questions? Issues? [Open an issue](https://github.com/nikeyes/stepwise-dev/issues) on GitHub. +Questions? [Open an issue](https://github.com/nikeyes/stepwise-dev/issues) on GitHub. diff --git a/.claude-plugin/plugin.json b/core/.claude-plugin/plugin.json similarity index 53% rename from .claude-plugin/plugin.json rename to core/.claude-plugin/plugin.json index 7d5d6ff..dfdb6a8 100644 --- a/.claude-plugin/plugin.json +++ b/core/.claude-plugin/plugin.json @@ -1,19 +1,21 @@ { - "name": "stepwise-dev", + "name": "stepwise-core", "version": "0.0.7", - "description": "Research → Plan → Implement → Validate workflow for Claude Code with local thoughts/ management", + "description": "Core workflow for structured development: Research → Plan → Implement → Validate with thoughts/ management", "author": { "name": "Jorge Castro", - "email": "nikey_es@yahoo.es" + "url": "https://github.com/nikeyes" }, "homepage": "https://github.com/nikeyes/stepwise-dev", "repository": "https://github.com/nikeyes/stepwise-dev", "license": "Apache-2.0", "keywords": [ "workflow", - "development", - "planning", "research", + "planning", + "implementation", + "validation", + "thoughts", "tdd" ] } diff --git a/core/README.md b/core/README.md new file mode 100644 index 0000000..6f46327 --- /dev/null +++ b/core/README.md @@ -0,0 +1,67 @@ +# Stepwise Core Plugin + +Core workflow plugin for structured development following the Research → Plan → Implement → Validate cycle. + +## What's Included + +### Commands (5) +- `/stepwise-core:research_codebase` - Document codebase as-is with comprehensive research +- `/stepwise-core:create_plan` - Create detailed implementation plans iteratively +- `/stepwise-core:iterate_plan` - Update existing implementation plans +- `/stepwise-core:implement_plan` - Execute plans phase by phase with validation +- `/stepwise-core:validate_plan` - Validate implementation against plan + +### Agents (5) +- `codebase-locator` - Find WHERE code lives in the codebase +- `codebase-analyzer` - Understand HOW code works +- `codebase-pattern-finder` - Find similar patterns to model after +- `thoughts-locator` - Discover documents in thoughts/ +- `thoughts-analyzer` - Extract insights from thoughts docs + +### Skills (1) +- `thoughts-management` - Manage thoughts/ directory with 3 bash scripts: + - `thoughts-init` - Initialize thoughts/ structure + - `thoughts-sync` - Sync hardlinks in searchable/ + - `thoughts-metadata` - Generate git metadata + +## Installation + +```bash +# Add marketplace +/plugin marketplace add nikeyes/stepwise-dev + +# Install this plugin +/plugin install stepwise-core@stepwise-dev +``` + +## Quick Start + +```bash +# 1. Research +/stepwise-core:research_codebase How does authentication work? + +# 2. Plan +/stepwise-core:create_plan Add OAuth support + +# 3. Implement +/stepwise-core:implement_plan @thoughts/shared/plans/YYYY-MM-DD-oauth.md + +# 4. Validate +/stepwise-core:validate_plan @thoughts/shared/plans/YYYY-MM-DD-oauth.md +``` + +## Philosophy + +- Keep context < 60% (attention threshold) +- Split work into phases +- Clear between phases, save to thoughts/ +- Never lose research or decisions + +## Related Plugins + +- **stepwise-git**: Git commit workflow without Claude attribution +- **stepwise-web**: Web search and research capabilities + +## License + +Apache License 2.0 - See LICENSE file for details. diff --git a/agents/codebase-analyzer.md b/core/agents/codebase-analyzer.md similarity index 100% rename from agents/codebase-analyzer.md rename to core/agents/codebase-analyzer.md diff --git a/agents/codebase-locator.md b/core/agents/codebase-locator.md similarity index 100% rename from agents/codebase-locator.md rename to core/agents/codebase-locator.md diff --git a/agents/codebase-pattern-finder.md b/core/agents/codebase-pattern-finder.md similarity index 100% rename from agents/codebase-pattern-finder.md rename to core/agents/codebase-pattern-finder.md diff --git a/agents/thoughts-analyzer.md b/core/agents/thoughts-analyzer.md similarity index 100% rename from agents/thoughts-analyzer.md rename to core/agents/thoughts-analyzer.md diff --git a/agents/thoughts-locator.md b/core/agents/thoughts-locator.md similarity index 100% rename from agents/thoughts-locator.md rename to core/agents/thoughts-locator.md diff --git a/commands/create_plan.md b/core/commands/create_plan.md similarity index 100% rename from commands/create_plan.md rename to core/commands/create_plan.md diff --git a/commands/implement_plan.md b/core/commands/implement_plan.md similarity index 100% rename from commands/implement_plan.md rename to core/commands/implement_plan.md diff --git a/commands/iterate_plan.md b/core/commands/iterate_plan.md similarity index 100% rename from commands/iterate_plan.md rename to core/commands/iterate_plan.md diff --git a/commands/research_codebase.md b/core/commands/research_codebase.md similarity index 100% rename from commands/research_codebase.md rename to core/commands/research_codebase.md diff --git a/commands/validate_plan.md b/core/commands/validate_plan.md similarity index 100% rename from commands/validate_plan.md rename to core/commands/validate_plan.md diff --git a/skills/thoughts-management/SKILL.md b/core/skills/thoughts-management/SKILL.md similarity index 100% rename from skills/thoughts-management/SKILL.md rename to core/skills/thoughts-management/SKILL.md diff --git a/skills/thoughts-management/scripts/thoughts-init b/core/skills/thoughts-management/scripts/thoughts-init similarity index 100% rename from skills/thoughts-management/scripts/thoughts-init rename to core/skills/thoughts-management/scripts/thoughts-init diff --git a/skills/thoughts-management/scripts/thoughts-metadata b/core/skills/thoughts-management/scripts/thoughts-metadata similarity index 100% rename from skills/thoughts-management/scripts/thoughts-metadata rename to core/skills/thoughts-management/scripts/thoughts-metadata diff --git a/skills/thoughts-management/scripts/thoughts-sync b/core/skills/thoughts-management/scripts/thoughts-sync similarity index 100% rename from skills/thoughts-management/scripts/thoughts-sync rename to core/skills/thoughts-management/scripts/thoughts-sync diff --git a/git/.claude-plugin/plugin.json b/git/.claude-plugin/plugin.json new file mode 100644 index 0000000..d5b980a --- /dev/null +++ b/git/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "stepwise-git", + "version": "0.0.7", + "description": "Git commit workflow without Claude attribution", + "author": { + "name": "Jorge Castro", + "url": "https://github.com/nikeyes" + }, + "homepage": "https://github.com/nikeyes/stepwise-dev", + "repository": "https://github.com/nikeyes/stepwise-dev", + "license": "Apache-2.0", + "keywords": [ + "git", + "commit", + "version-control" + ] +} diff --git a/git/README.md b/git/README.md new file mode 100644 index 0000000..e9f7512 --- /dev/null +++ b/git/README.md @@ -0,0 +1,50 @@ +# Stepwise Git Plugin + +Git commit workflow for creating clean commits without Claude attribution. + +## What's Included + +### Commands (1) +- `/stepwise-git:commit` - Create git commits with user approval and no Claude attribution + +## Installation + +```bash +# Add marketplace +/plugin marketplace add nikeyes/stepwise-dev + +# Install this plugin +/plugin install stepwise-git@stepwise-dev +``` + +## Usage + +```bash +# Create a commit +/stepwise-git:commit +``` + +This will: +1. Run `git status` to see untracked files +2. Run `git diff` to see changes +3. Run `git log` to match commit message style +4. Draft a commit message focusing on "why" not "what" +5. Stage relevant files +6. Create the commit +7. Verify with `git status` + +## Features + +- **No Claude attribution**: Commits are attributed to you, not Claude +- **Smart staging**: Only stages relevant files, warns about secrets +- **Style matching**: Follows your existing commit message patterns +- **Pre-commit hook support**: Handles hook failures gracefully + +## Related Plugins + +- **stepwise-core**: Core workflow for Research → Plan → Implement → Validate +- **stepwise-web**: Web search and research capabilities + +## License + +Apache License 2.0 - See LICENSE file for details. diff --git a/commands/commit.md b/git/commands/commit.md similarity index 100% rename from commands/commit.md rename to git/commands/commit.md diff --git a/marketplace.json b/marketplace.json new file mode 100644 index 0000000..6a6144a --- /dev/null +++ b/marketplace.json @@ -0,0 +1,25 @@ +{ + "plugins": [ + { + "name": "stepwise-core", + "source": "./core", + "version": "0.0.7", + "description": "Core workflow for structured development: Research → Plan → Implement → Validate with thoughts/ management", + "keywords": ["workflow", "research", "planning", "implementation", "validation", "thoughts"] + }, + { + "name": "stepwise-git", + "source": "./git", + "version": "0.0.7", + "description": "Git commit workflow without Claude attribution", + "keywords": ["git", "commit", "version-control"] + }, + { + "name": "stepwise-web", + "source": "./web", + "version": "0.0.7", + "description": "Web search and research capabilities for external context", + "keywords": ["web", "search", "research", "external"] + } + ] +} diff --git a/thoughts/nikey_es/notes/claude-code-skills.md b/thoughts/nikey_es/notes/claude-code-skills.md index e2116cf..7eda418 100644 --- a/thoughts/nikey_es/notes/claude-code-skills.md +++ b/thoughts/nikey_es/notes/claude-code-skills.md @@ -1,2118 +1,678 @@ -# Agent Skills +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. -> Create, manage, and share Skills to extend Claude's capabilities in Claude Code. +# Extend Claude with skills -This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources. +> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands. -## Prerequisites - -* Claude Code version 1.0 or later -* Basic familiarity with [Claude Code](/en/quickstart) - -## What are Agent Skills? - -Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates. - -**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them). - -**Benefits**: - -* Extend Claude's capabilities for your specific workflows -* Share expertise across your team via git -* Reduce repetitive prompting -* Compose multiple Skills for complex tasks - -Learn more in the [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview). +Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`. - For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). - + For built-in commands like `/help` and `/compact`, see [interactive mode](/en/interactive-mode#built-in-commands). -## Create a Skill - -Skills are stored as directories containing a `SKILL.md` file. + **Custom slash commands have been merged into skills.** A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant. + -### Personal Skills +Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context). -Personal Skills are available across all your projects. Store them in `~/.claude/skills/`: +## Getting started -```bash theme={null} -mkdir -p ~/.claude/skills/my-skill-name -``` +### Create your first skill -**Use personal Skills for**: +This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with `/explain-code`. -* Your individual workflows and preferences -* Experimental Skills you're developing -* Personal productivity tools + + + Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects. -### Project Skills + ```bash theme={null} + mkdir -p ~/.claude/skills/explain-code + ``` + -Project Skills are shared with your team. Store them in `.claude/skills/` within your project: + + Every skill needs a `SKILL.md` file with two parts: YAML frontmatter (between `---` markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The `name` field becomes the `/slash-command`, and the `description` helps Claude decide when to load it automatically. -```bash theme={null} -mkdir -p .claude/skills/my-skill-name -``` + Create `~/.claude/skills/explain-code/SKILL.md`: -**Use project Skills for**: + ```yaml theme={null} + --- + name: explain-code + description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" + --- -* Team workflows and conventions -* Project-specific expertise -* Shared utilities and scripts + When explaining code, always include: -Project Skills are checked into git and automatically available to team members. + 1. **Start with an analogy**: Compare the code to something from everyday life + 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships + 3. **Walk through the code**: Explain step-by-step what happens + 4. **Highlight a gotcha**: What's a common mistake or misconception? -### Plugin Skills + Keep explanations conversational. For complex concepts, use multiple analogies. + ``` + -Skills can also come from [Claude Code plugins](/en/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills. + + You can test it two ways: -## Write SKILL.md + **Let Claude invoke it automatically** by asking something that matches the description: -Create a `SKILL.md` file with YAML frontmatter and Markdown content: + ``` + How does this code work? + ``` -```yaml theme={null} ---- -name: your-skill-name -description: Brief description of what this Skill does and when to use it ---- + **Or invoke it directly** with the skill name: -# Your Skill Name + ``` + /explain-code src/auth/login.ts + ``` -## Instructions -Provide clear, step-by-step guidance for Claude. + Either way, Claude should include an analogy and ASCII diagram in its explanation. + + -## Examples -Show concrete examples of using this Skill. -``` +### Where skills live -**Field requirements**: +Where you store a skill determines who can use it: -* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters) -* `description`: Brief description of what the Skill does and when to use it (max 1024 characters) +| Location | Path | Applies to | +| :--------- | :------------------------------------------------------- | :----------------------------- | +| Enterprise | See [managed settings](/en/permissions#managed-settings) | All users in your organization | +| Personal | `~/.claude/skills//SKILL.md` | All your projects | +| Project | `.claude/skills//SKILL.md` | This project only | +| Plugin | `/skills//SKILL.md` | Where plugin is enabled | -The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it. +When skills share the same name across levels, higher-priority locations win: enterprise > personal > project. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels. If you have files in `.claude/commands/`, those work the same way, but if a skill and a command share the same name, the skill takes precedence. -See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules. +#### Automatic discovery from nested directories -## Add supporting files +When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills. -Create additional files alongside SKILL.md: +Each skill is a directory with `SKILL.md` as the entrypoint: ``` my-skill/ -├── SKILL.md (required) -├── reference.md (optional documentation) -├── examples.md (optional examples) -├── scripts/ -│ └── helper.py (optional utility) -└── templates/ - └── template.txt (optional template) -``` - -Reference these files from SKILL.md: - -````markdown theme={null} -For advanced usage, see [reference.md](reference.md). - -Run the helper script: -```bash -python scripts/helper.py input.txt -``` -```` - -Claude reads these files only when needed, using progressive disclosure to manage context efficiently. - -## Restrict tool access with allowed-tools - -Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active: - -```yaml theme={null} ---- -name: safe-file-reader -description: Read files without making changes. Use when you need read-only file access. -allowed-tools: Read, Grep, Glob ---- - -# Safe File Reader - -This Skill provides read-only file access. - -## Instructions -1. Use Read to view file contents -2. Use Grep to search within files -3. Use Glob to find files by pattern +├── SKILL.md # Main instructions (required) +├── template.md # Template for Claude to fill in +├── examples/ +│ └── sample.md # Example output showing expected format +└── scripts/ + └── validate.sh # Script Claude can execute ``` -When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for: - -* Read-only Skills that shouldn't modify files -* Skills with limited scope (e.g., only data analysis, no file writing) -* Security-sensitive workflows where you want to restrict capabilities - -If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model. +The `SKILL.md` contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your `SKILL.md` so Claude knows what they contain and when to load them. See [Add supporting files](#add-supporting-files) for more details. - `allowed-tools` is only supported for Skills in Claude Code. + Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files. -## View available Skills - -Skills are automatically discovered by Claude from three sources: - -* Personal Skills: `~/.claude/skills/` -* Project Skills: `.claude/skills/` -* Plugin Skills: bundled with installed plugins - -**To view all available Skills**, ask Claude directly: - -``` -What Skills are available? -``` - -or - -``` -List all available Skills -``` - -This will show all Skills from all sources, including plugin Skills. - -**To inspect a specific Skill**, you can also check the filesystem: - -```bash theme={null} -# List personal Skills -ls ~/.claude/skills/ - -# List project Skills (if in a project directory) -ls .claude/skills/ - -# View a specific Skill's content -cat ~/.claude/skills/my-skill/SKILL.md -``` - -## Test a Skill - -After creating a Skill, test it by asking questions that match your description. - -**Example**: If your description mentions "PDF files": - -``` -Can you help me extract text from this PDF? -``` +#### Skills from additional directories -Claude autonomously decides to use your Skill if it matches the request—you don't need to explicitly invoke it. The Skill activates automatically based on the context of your question. +Skills defined in `.claude/skills/` within directories added via `--add-dir` are loaded automatically and picked up by live change detection, so you can edit them during a session without restarting. -## Debug a Skill + + CLAUDE.md files from `--add-dir` directories are not loaded by default. To load them, set `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`. See [Load memory from additional directories](/en/memory#load-memory-from-additional-directories). + -If Claude doesn't use your Skill, check these common issues: +## Configure skills -### Make description specific +Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows. -**Too vague**: +### Types of skill content -```yaml theme={null} -description: Helps with documents -``` +Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include: -**Specific**: +**Reference content** adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context. ```yaml theme={null} -description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. -``` - -Include both what the Skill does and when to use it in the description. - -### Verify file path - -**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md` -**Project Skills**: `.claude/skills/skill-name/SKILL.md` - -Check the file exists: - -```bash theme={null} -# Personal -ls ~/.claude/skills/my-skill/SKILL.md - -# Project -ls .claude/skills/my-skill/SKILL.md -``` - -### Check YAML syntax - -Invalid YAML prevents the Skill from loading. Verify the frontmatter: - -```bash theme={null} -cat SKILL.md | head -n 10 -``` - -Ensure: - -* Opening `---` on line 1 -* Closing `---` before Markdown content -* Valid YAML syntax (no tabs, correct indentation) - -### View errors - -Run Claude Code with debug mode to see Skill loading errors: +--- +name: api-conventions +description: API design patterns for this codebase +--- -```bash theme={null} -claude --debug +When writing API endpoints: +- Use RESTful naming conventions +- Return consistent error formats +- Include request validation ``` -## Share Skills with your team - -**Recommended approach**: Distribute Skills through [plugins](/en/plugins). +**Task content** gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation. These are often actions you want to invoke directly with `/skill-name` rather than letting Claude decide when to run them. Add `disable-model-invocation: true` to prevent Claude from triggering it automatically. -To share Skills via plugin: - -1. Create a plugin with Skills in the `skills/` directory -2. Add the plugin to a marketplace -3. Team members install the plugin - -For complete instructions, see [Add Skills to your plugin](/en/plugins#add-skills-to-your-plugin). - -You can also share Skills directly through project repositories: - -### Step 1: Add Skill to your project - -Create a project Skill: +```yaml theme={null} +--- +name: deploy +description: Deploy the application to production +context: fork +disable-model-invocation: true +--- -```bash theme={null} -mkdir -p .claude/skills/team-skill -# Create SKILL.md +Deploy the application: +1. Run the test suite +2. Build the application +3. Push to the deployment target ``` -### Step 2: Commit to git +Your `SKILL.md` can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also [add supporting files](#add-supporting-files) to keep the main skill focused. -```bash theme={null} -git add .claude/skills/ -git commit -m "Add team Skill for PDF processing" -git push -``` +### Frontmatter reference -### Step 3: Team members get Skills automatically +Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between `---` markers at the top of your `SKILL.md` file: -When team members pull the latest changes, Skills are immediately available: +```yaml theme={null} +--- +name: my-skill +description: What this skill does +disable-model-invocation: true +allowed-tools: Read, Grep +--- -```bash theme={null} -git pull -claude # Skills are now available +Your skill instructions here... ``` -## Update a Skill +All fields are optional. Only `description` is recommended so Claude knows when to use the skill. -Edit SKILL.md directly: +| Field | Required | Description | +| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). | +| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. | +| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. | +| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. | +| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. | +| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. | +| `model` | No | Model to use when this skill is active. | +| `context` | No | Set to `fork` to run in a forked subagent context. | +| `agent` | No | Which subagent type to use when `context: fork` is set. | +| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. | -```bash theme={null} -# Personal Skill -code ~/.claude/skills/my-skill/SKILL.md +#### Available string substitutions -# Project Skill -code .claude/skills/my-skill/SKILL.md -``` +Skills support string substitution for dynamic values in the skill content: -Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates. +| Variable | Description | +| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | +| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: `. | +| `$ARGUMENTS[N]` | Access a specific argument by 0-based index, such as `$ARGUMENTS[0]` for the first argument. | +| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. | +| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. | -## Remove a Skill +**Example using substitutions:** -Delete the Skill directory: +```yaml theme={null} +--- +name: session-logger +description: Log activity for this session +--- -```bash theme={null} -# Personal -rm -rf ~/.claude/skills/my-skill +Log the following to logs/${CLAUDE_SESSION_ID}.log: -# Project -rm -rf .claude/skills/my-skill -git commit -m "Remove unused Skill" +$ARGUMENTS ``` -## Best practices - -### Keep Skills focused - -One Skill should address one capability: - -**Focused**: +### Add supporting files -* "PDF form filling" -* "Excel data analysis" -* "Git commit messages" +Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs. -**Too broad**: - -* "Document processing" (split into separate Skills) -* "Data tools" (split by data type or operation) - -### Write clear descriptions - -Help Claude discover when to use Skills by including specific triggers in your description: - -**Clear**: - -```yaml theme={null} -description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format. ``` - -**Vague**: - -```yaml theme={null} -description: For files +my-skill/ +├── SKILL.md (required - overview and navigation) +├── reference.md (detailed API docs - loaded when needed) +├── examples.md (usage examples - loaded when needed) +└── scripts/ + └── helper.py (utility script - executed, not loaded) ``` -### Test with your team - -Have teammates use Skills and provide feedback: - -* Does the Skill activate when expected? -* Are the instructions clear? -* Are there missing examples or edge cases? - -### Document Skill versions - -You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section: +Reference supporting files from `SKILL.md` so Claude knows what each file contains and when to load it: ```markdown theme={null} -# My Skill +## Additional resources -## Version History -- v2.0.0 (2025-10-01): Breaking changes to API -- v1.1.0 (2025-09-15): Added new features -- v1.0.0 (2025-09-01): Initial release +- For complete API details, see [reference.md](reference.md) +- For usage examples, see [examples.md](examples.md) ``` -This helps team members understand what changed between versions. - -## Troubleshooting - -### Claude doesn't use my Skill +Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files. -**Symptom**: You ask a relevant question but Claude doesn't use your Skill. +### Control who invokes a skill -**Check**: Is the description specific enough? +By default, both you and Claude can invoke any skill. You can type `/skill-name` to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this: -Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention. +* **`disable-model-invocation: true`**: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like `/commit`, `/deploy`, or `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready. -**Too generic**: - -```yaml theme={null} -description: Helps with data -``` +* **`user-invocable: false`**: Only Claude can invoke the skill. Use this for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works. Claude should know this when relevant, but `/legacy-system-context` isn't a meaningful action for users to take. -**Specific**: +This example creates a deploy skill that only you can trigger. The `disable-model-invocation: true` field prevents Claude from running it automatically: ```yaml theme={null} -description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files. -``` - -**Check**: Is the YAML valid? - -Run validation to check for syntax errors: - -```bash theme={null} -# View frontmatter -cat .claude/skills/my-skill/SKILL.md | head -n 15 - -# Check for common issues -# - Missing opening or closing --- -# - Tabs instead of spaces -# - Unquoted strings with special characters -``` - -**Check**: Is the Skill in the correct location? +--- +name: deploy +description: Deploy the application to production +disable-model-invocation: true +--- -```bash theme={null} -# Personal Skills -ls ~/.claude/skills/*/SKILL.md +Deploy $ARGUMENTS to production: -# Project Skills -ls .claude/skills/*/SKILL.md +1. Run the test suite +2. Build the application +3. Push to the deployment target +4. Verify the deployment succeeded ``` -### Skill has errors +Here's how the two fields affect invocation and context loading: -**Symptom**: The Skill loads but doesn't work correctly. +| Frontmatter | You can invoke | Claude can invoke | When loaded into context | +| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- | +| (default) | Yes | Yes | Description always in context, full skill loads when invoked | +| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke | +| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked | -**Check**: Are dependencies available? + + In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/en/sub-agents#preload-skills-into-subagents) work differently: the full skill content is injected at startup. + -Claude will automatically install required dependencies (or ask for permission to install them) when it needs them. +### Restrict tool access -**Check**: Do scripts have execute permissions? +Use the `allowed-tools` field to limit which tools Claude can use when a skill is active. This skill creates a read-only mode where Claude can explore files but not modify them: -```bash theme={null} -chmod +x .claude/skills/my-skill/scripts/*.py +```yaml theme={null} +--- +name: safe-reader +description: Read files without making changes +allowed-tools: Read, Grep, Glob +--- ``` -**Check**: Are file paths correct? - -Use forward slashes (Unix style) in all paths: +### Pass arguments to skills -**Correct**: `scripts/helper.py` -**Wrong**: `scripts\helper.py` (Windows style) +Both you and Claude can pass arguments when invoking a skill. Arguments are available via the `$ARGUMENTS` placeholder. -### Multiple Skills conflict - -**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills. - -**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions. - -Instead of: +This skill fixes a GitHub issue by number. The `$ARGUMENTS` placeholder gets replaced with whatever follows the skill name: ```yaml theme={null} -# Skill 1 -description: For data analysis - -# Skill 2 -description: For analyzing data -``` - -Use: +--- +name: fix-issue +description: Fix a GitHub issue +disable-model-invocation: true +--- -```yaml theme={null} -# Skill 1 -description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking. +Fix GitHub issue $ARGUMENTS following our coding standards. -# Skill 2 -description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics. +1. Read the issue description +2. Understand the requirements +3. Implement the fix +4. Write tests +5. Create a commit ``` -## Examples +When you run `/fix-issue 123`, Claude receives "Fix GitHub issue 123 following our coding standards..." -### Simple Skill (single file) +If you invoke a skill with arguments but the skill doesn't include `$ARGUMENTS`, Claude Code appends `ARGUMENTS: ` to the end of the skill content so Claude still sees what you typed. -``` -commit-helper/ -└── SKILL.md -``` +To access individual arguments by position, use `$ARGUMENTS[N]` or the shorter `$N`: ```yaml theme={null} --- -name: generating-commit-messages -description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes. +name: migrate-component +description: Migrate a component from one framework to another --- -# Generating Commit Messages - -## Instructions - -1. Run `git diff --staged` to see changes -2. I'll suggest a commit message with: - - Summary under 50 characters - - Detailed description - - Affected components - -## Best practices - -- Use present tense -- Explain what and why, not how +Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2]. +Preserve all existing behavior and tests. ``` -### Skill with tool permissions - -``` -code-reviewer/ -└── SKILL.md -``` +Running `/migrate-component SearchBar React Vue` replaces `$ARGUMENTS[0]` with `SearchBar`, `$ARGUMENTS[1]` with `React`, and `$ARGUMENTS[2]` with `Vue`. The same skill using the `$N` shorthand: ```yaml theme={null} --- -name: code-reviewer -description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality. -allowed-tools: Read, Grep, Glob +name: migrate-component +description: Migrate a component from one framework to another --- -# Code Reviewer - -## Review checklist - -1. Code organization and structure -2. Error handling -3. Performance considerations -4. Security concerns -5. Test coverage - -## Instructions - -1. Read the target files using Read tool -2. Search for patterns using Grep -3. Find related files using Glob -4. Provide detailed feedback on code quality +Migrate the $0 component from $1 to $2. +Preserve all existing behavior and tests. ``` -### Multi-file Skill +## Advanced patterns -``` -pdf-processing/ -├── SKILL.md -├── FORMS.md -├── REFERENCE.md -└── scripts/ - ├── fill_form.py - └── validate.py -``` +### Inject dynamic context -**SKILL.md**: +The `!`command\`\` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself. -````yaml theme={null} +This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `!`gh pr diff\`\` and other commands run first, and their output gets inserted into the prompt: + +```yaml theme={null} --- -name: pdf-processing -description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages. +name: pr-summary +description: Summarize changes in a pull request +context: fork +agent: Explore +allowed-tools: Bash(gh *) --- -# PDF Processing - -## Quick start - -Extract text: -```python -import pdfplumber -with pdfplumber.open("doc.pdf") as pdf: - text = pdf.pages[0].extract_text() -``` - -For form filling, see [FORMS.md](FORMS.md). -For detailed API reference, see [REFERENCE.md](REFERENCE.md). - -## Requirements +## Pull request context +- PR diff: !`gh pr diff` +- PR comments: !`gh pr view --comments` +- Changed files: !`gh pr diff --name-only` -Packages must be installed in your environment: -```bash -pip install pypdf pdfplumber +## Your task +Summarize this pull request... ``` -```` - - - List required packages in the description. Packages must be installed in your environment before Claude can use them. - - -Claude loads additional files only when needed. -## Next steps +When this skill runs: - - - Write Skills that Claude can use effectively - +1. Each `!`command\`\` executes immediately (before Claude sees anything) +2. The output replaces the placeholder in the skill content +3. Claude receives the fully-rendered prompt with actual PR data - - Learn how Skills work across Claude products - +This is preprocessing, not something Claude executes. Claude only sees the final result. - - Use Skills programmatically with TypeScript and Python - - - - Create your first Skill - - - -# Skill authoring best practices - -> Learn how to write effective Skills that Claude can discover and use successfully. - -Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively. - -For conceptual background on how Skills work, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview). - -## Core principles - -### Concise is key - -The [context window](/en/docs/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including: - -* The system prompt -* Conversation history -* Other Skills' metadata -* Your actual request - -Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context. + + To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) in a skill, include the word "ultrathink" anywhere in your skill content. + -**Default assumption**: Claude is already very smart +### Run skills in a subagent -Only add context Claude doesn't already have. Challenge each piece of information: +Add `context: fork` to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history. -* "Does Claude really need this explanation?" -* "Can I assume Claude knows this?" -* "Does this paragraph justify its token cost?" + + `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output. + -**Good example: Concise** (approximately 50 tokens): +Skills and [subagents](/en/sub-agents) work together in two directions: -````markdown theme={null} -## Extract PDF text +| Approach | System prompt | Task | Also loads | +| :--------------------------- | :---------------------------------------- | :-------------------------- | :--------------------------- | +| Skill with `context: fork` | From agent type (`Explore`, `Plan`, etc.) | SKILL.md content | CLAUDE.md | +| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md | -Use pdfplumber for text extraction: +With `context: fork`, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see [Subagents](/en/sub-agents#preload-skills-into-subagents). -```python -import pdfplumber +#### Example: Research skill using Explore agent -with pdfplumber.open("file.pdf") as pdf: - text = pdf.pages[0].extract_text() -``` -```` +This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration: -**Bad example: Too verbose** (approximately 150 tokens): +```yaml theme={null} +--- +name: deep-research +description: Research a topic thoroughly +context: fork +agent: Explore +--- -```markdown theme={null} -## Extract PDF text +Research $ARGUMENTS thoroughly: -PDF (Portable Document Format) files are a common file format that contains -text, images, and other content. To extract text from a PDF, you'll need to -use a library. There are many libraries available for PDF processing, but we -recommend pdfplumber because it's easy to use and handles most cases well. -First, you'll need to install it using pip. Then you can use the code below... +1. Find relevant files using Glob and Grep +2. Read and analyze the code +3. Summarize findings with specific file references ``` -The concise version assumes Claude knows what PDFs are and how libraries work. +When this skill runs: -### Set appropriate degrees of freedom +1. A new isolated context is created +2. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...") +3. The `agent` field determines the execution environment (model, tools, and permissions) +4. Results are summarized and returned to your main conversation -Match the level of specificity to the task's fragility and variability. +The `agent` field specifies which subagent configuration to use. Options include built-in agents (`Explore`, `Plan`, `general-purpose`) or any custom subagent from `.claude/agents/`. If omitted, uses `general-purpose`. -**High freedom** (text-based instructions): +### Restrict Claude's skill access -Use when: +By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/permissions) still govern baseline approval behavior for all other tools. Built-in commands like `/compact` and `/init` are not available through the Skill tool. -* Multiple approaches are valid -* Decisions depend on context -* Heuristics guide the approach +Three ways to control which skills Claude can invoke: -Example: +**Disable all skills** by denying the Skill tool in `/permissions`: -```markdown theme={null} -## Code review process - -1. Analyze the code structure and organization -2. Check for potential bugs or edge cases -3. Suggest improvements for readability and maintainability -4. Verify adherence to project conventions ``` - -**Medium freedom** (pseudocode or scripts with parameters): - -Use when: - -* A preferred pattern exists -* Some variation is acceptable -* Configuration affects behavior - -Example: - -````markdown theme={null} -## Generate report - -Use this template and customize as needed: - -```python -def generate_report(data, format="markdown", include_charts=True): - # Process data - # Generate output in specified format - # Optionally include visualizations +# Add to deny rules: +Skill ``` -```` - -**Low freedom** (specific scripts, few or no parameters): - -Use when: -* Operations are fragile and error-prone -* Consistency is critical -* A specific sequence must be followed +**Allow or deny specific skills** using [permission rules](/en/permissions): -Example: - -````markdown theme={null} -## Database migration - -Run exactly this script: - -```bash -python scripts/migrate.py --verify --backup ``` +# Allow only specific skills +Skill(commit) +Skill(review-pr *) -Do not modify the command or add additional flags. -```` - -**Analogy**: Think of Claude as a robot exploring a path: - -* **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence. -* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach. - -### Test with all models you plan to use - -Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with. - -**Testing considerations by model**: - -* **Claude Haiku** (fast, economical): Does the Skill provide enough guidance? -* **Claude Sonnet** (balanced): Is the Skill clear and efficient? -* **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining? +# Deny specific skills +Skill(deploy *) +``` -What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them. +Permission syntax: `Skill(name)` for exact match, `Skill(name *)` for prefix match with any arguments. -## Skill structure +**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter. This removes the skill from Claude's context entirely. - **YAML Frontmatter**: The SKILL.md frontmatter requires two fields: - - `name`: - - * Maximum 64 characters - * Must contain only lowercase letters, numbers, and hyphens - * Cannot contain XML tags - * Cannot contain reserved words: "anthropic", "claude" + The `user-invocable` field only controls menu visibility, not Skill tool access. Use `disable-model-invocation: true` to block programmatic invocation. + - `description`: +## Share skills - * Must be non-empty - * Maximum 1024 characters - * Cannot contain XML tags - * Should describe what the Skill does and when to use it +Skills can be distributed at different scopes depending on your audience: - For complete Skill structure details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure). - +* **Project skills**: Commit `.claude/skills/` to version control +* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins) +* **Managed**: Deploy organization-wide through [managed settings](/en/permissions#managed-settings) -### Naming conventions +### Generate visual output -Use consistent naming patterns to make Skills easier to reference and discuss. We recommend using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides. +Skills can bundle and run scripts in any language, giving Claude capabilities beyond what's possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports. -Remember that the `name` field must use lowercase letters, numbers, and hyphens only. +This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color. -**Good naming examples (gerund form)**: +Create the Skill directory: -* `processing-pdfs` -* `analyzing-spreadsheets` -* `managing-databases` -* `testing-code` -* `writing-documentation` +```bash theme={null} +mkdir -p ~/.claude/skills/codebase-visualizer/scripts +``` -**Acceptable alternatives**: +Create `~/.claude/skills/codebase-visualizer/SKILL.md`. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script: -* Noun phrases: `pdf-processing`, `spreadsheet-analysis` -* Action-oriented: `process-pdfs`, `analyze-spreadsheets` +````yaml theme={null} +--- +name: codebase-visualizer +description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files. +allowed-tools: Bash(python *) +--- -**Avoid**: +# Codebase Visualizer -* Vague names: `helper`, `utils`, `tools` -* Overly generic: `documents`, `data`, `files` -* Reserved words: `anthropic-helper`, `claude-tools` -* Inconsistent patterns within your skill collection +Generate an interactive HTML tree view that shows your project's file structure with collapsible directories. -Consistent naming makes it easier to: +## Usage -* Reference Skills in documentation and conversations -* Understand what a Skill does at a glance -* Organize and search through multiple Skills -* Maintain a professional, cohesive skill library +Run the visualization script from your project root: -### Writing effective descriptions +```bash +python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . +``` -The `description` field enables Skill discovery and should include both what the Skill does and when to use it. +This creates `codebase-map.html` in the current directory and opens it in your default browser. - - **Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems. +## What the visualization shows - * **Good:** "Processes Excel files and generates reports" - * **Avoid:** "I can help you process Excel files" - * **Avoid:** "You can use this to process Excel files" - +- **Collapsible directories**: Click folders to expand/collapse +- **File sizes**: Displayed next to each file +- **Colors**: Different colors for different file types +- **Directory totals**: Shows aggregate size of each folder +```` -**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it. +Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with: -Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details. +* A **summary sidebar** showing file count, directory count, total size, and number of file types +* A **bar chart** breaking down the codebase by file type (top 8 by size) +* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators -Effective examples: +The script requires Python but uses only built-in libraries, so there are no packages to install: -**PDF Processing skill:** +```python expandable theme={null} +#!/usr/bin/env python3 +"""Generate an interactive collapsible tree visualization of a codebase.""" -```yaml theme={null} -description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. -``` +import json +import sys +import webbrowser +from pathlib import Path +from collections import Counter -**Excel Analysis skill:** +IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'} -```yaml theme={null} -description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. -``` +def scan(path: Path, stats: dict) -> dict: + result = {"name": path.name, "children": [], "size": 0} + try: + for item in sorted(path.iterdir()): + if item.name in IGNORE or item.name.startswith('.'): + continue + if item.is_file(): + size = item.stat().st_size + ext = item.suffix.lower() or '(no ext)' + result["children"].append({"name": item.name, "size": size, "ext": ext}) + result["size"] += size + stats["files"] += 1 + stats["extensions"][ext] += 1 + stats["ext_sizes"][ext] += size + elif item.is_dir(): + stats["dirs"] += 1 + child = scan(item, stats) + if child["children"]: + result["children"].append(child) + result["size"] += child["size"] + except PermissionError: + pass + return result + +def generate_html(data: dict, stats: dict, output: Path) -> None: + ext_sizes = stats["ext_sizes"] + total_size = sum(ext_sizes.values()) or 1 + sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8] + colors = { + '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8', + '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26', + '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e', + '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25', + } + lang_bars = "".join( + f'
{ext}' + f'
' + f'{(size/total_size)*100:.1f}%
' + for ext, size in sorted_exts + ) + def fmt(b): + if b < 1024: return f"{b} B" + if b < 1048576: return f"{b/1024:.1f} KB" + return f"{b/1048576:.1f} MB" + + html = f''' + + Codebase Explorer + + +
+
+

📊 Summary

+
Files{stats["files"]:,}
+
Directories{stats["dirs"]:,}
+
Total size{fmt(data["size"])}
+
File types{len(stats["extensions"])}
+

By file type

+ {lang_bars} +
+
+

📁 {data["name"]}

+
    +
    +
    + +''' + output.write_text(html) + +if __name__ == '__main__': + target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve() + stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()} + data = scan(target, stats) + out = Path('codebase-map.html') + generate_html(data, stats, out) + print(f'Generated {out.absolute()}') + webbrowser.open(f'file://{out.absolute()}') +``` + +To test, open Claude Code in any project and ask "Visualize this codebase." Claude runs the script, generates `codebase-map.html`, and opens it in your browser. + +This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration. -**Git Commit Helper skill:** - -```yaml theme={null} -description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. -``` - -Avoid vague descriptions like these: - -```yaml theme={null} -description: Helps with documents -``` - -```yaml theme={null} -description: Processes data -``` - -```yaml theme={null} -description: Does stuff with files -``` - -### Progressive disclosure patterns - -SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview. - -**Practical guidance:** - -* Keep SKILL.md body under 500 lines for optimal performance -* Split content into separate files when approaching this limit -* Use the patterns below to organize instructions, code, and resources effectively - -#### Visual overview: From simple to complex - -A basic Skill starts with just a SKILL.md file containing metadata and instructions: - -Simple SKILL.md file showing YAML frontmatter and markdown body - -As your Skill grows, you can bundle additional content that Claude loads only when needed: - -Bundling additional reference files like reference.md and forms.md. - -The complete Skill directory structure might look like this: - -``` -pdf/ -├── SKILL.md # Main instructions (loaded when triggered) -├── FORMS.md # Form-filling guide (loaded as needed) -├── reference.md # API reference (loaded as needed) -├── examples.md # Usage examples (loaded as needed) -└── scripts/ - ├── analyze_form.py # Utility script (executed, not loaded) - ├── fill_form.py # Form filling script - └── validate.py # Validation script -``` - -#### Pattern 1: High-level guide with references - -````markdown theme={null} ---- -name: pdf-processing -description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ---- - -# PDF Processing - -## Quick start - -Extract text with pdfplumber: -```python -import pdfplumber -with pdfplumber.open("file.pdf") as pdf: - text = pdf.pages[0].extract_text() -``` - -## Advanced features - -**Form filling**: See [FORMS.md](FORMS.md) for complete guide -**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods -**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns -```` - -Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. - -#### Pattern 2: Domain-specific organization - -For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused. - -``` -bigquery-skill/ -├── SKILL.md (overview and navigation) -└── reference/ - ├── finance.md (revenue, billing metrics) - ├── sales.md (opportunities, pipeline) - ├── product.md (API usage, features) - └── marketing.md (campaigns, attribution) -``` - -````markdown SKILL.md theme={null} -# BigQuery Data Analysis - -## Available datasets - -**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md) -**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md) -**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md) -**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md) - -## Quick search - -Find specific metrics using grep: - -```bash -grep -i "revenue" reference/finance.md -grep -i "pipeline" reference/sales.md -grep -i "api usage" reference/product.md -``` -```` - -#### Pattern 3: Conditional details - -Show basic content, link to advanced content: - -```markdown theme={null} -# DOCX Processing - -## Creating documents - -Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md). - -## Editing documents - -For simple edits, modify the XML directly. - -**For tracked changes**: See [REDLINING.md](REDLINING.md) -**For OOXML details**: See [OOXML.md](OOXML.md) -``` - -Claude reads REDLINING.md or OOXML.md only when the user needs those features. - -### Avoid deeply nested references - -Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information. - -**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed. - -**Bad example: Too deep**: - -```markdown theme={null} -# SKILL.md -See [advanced.md](advanced.md)... - -# advanced.md -See [details.md](details.md)... - -# details.md -Here's the actual information... -``` - -**Good example: One level deep**: - -```markdown theme={null} -# SKILL.md - -**Basic usage**: [instructions in SKILL.md] -**Advanced features**: See [advanced.md](advanced.md) -**API reference**: See [reference.md](reference.md) -**Examples**: See [examples.md](examples.md) -``` - -### Structure longer reference files with table of contents - -For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads. - -**Example**: - -```markdown theme={null} -# API Reference - -## Contents -- Authentication and setup -- Core methods (create, read, update, delete) -- Advanced features (batch operations, webhooks) -- Error handling patterns -- Code examples - -## Authentication and setup -... - -## Core methods -... -``` - -Claude can then read the complete file or jump to specific sections as needed. - -For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below. - -## Workflows and feedback loops - -### Use workflows for complex tasks - -Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses. - -**Example 1: Research synthesis workflow** (for Skills without code): - -````markdown theme={null} -## Research synthesis workflow - -Copy this checklist and track your progress: - -``` -Research Progress: -- [ ] Step 1: Read all source documents -- [ ] Step 2: Identify key themes -- [ ] Step 3: Cross-reference claims -- [ ] Step 4: Create structured summary -- [ ] Step 5: Verify citations -``` - -**Step 1: Read all source documents** - -Review each document in the `sources/` directory. Note the main arguments and supporting evidence. - -**Step 2: Identify key themes** - -Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree? - -**Step 3: Cross-reference claims** - -For each major claim, verify it appears in the source material. Note which source supports each point. - -**Step 4: Create structured summary** - -Organize findings by theme. Include: -- Main claim -- Supporting evidence from sources -- Conflicting viewpoints (if any) - -**Step 5: Verify citations** - -Check that every claim references the correct source document. If citations are incomplete, return to Step 3. -```` - -This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi-step process. - -**Example 2: PDF form filling workflow** (for Skills with code): - -````markdown theme={null} -## PDF form filling workflow - -Copy this checklist and check off items as you complete them: - -``` -Task Progress: -- [ ] Step 1: Analyze the form (run analyze_form.py) -- [ ] Step 2: Create field mapping (edit fields.json) -- [ ] Step 3: Validate mapping (run validate_fields.py) -- [ ] Step 4: Fill the form (run fill_form.py) -- [ ] Step 5: Verify output (run verify_output.py) -``` - -**Step 1: Analyze the form** - -Run: `python scripts/analyze_form.py input.pdf` - -This extracts form fields and their locations, saving to `fields.json`. - -**Step 2: Create field mapping** - -Edit `fields.json` to add values for each field. - -**Step 3: Validate mapping** - -Run: `python scripts/validate_fields.py fields.json` - -Fix any validation errors before continuing. - -**Step 4: Fill the form** - -Run: `python scripts/fill_form.py input.pdf fields.json output.pdf` - -**Step 5: Verify output** - -Run: `python scripts/verify_output.py output.pdf` - -If verification fails, return to Step 2. -```` - -Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows. - -### Implement feedback loops - -**Common pattern**: Run validator → fix errors → repeat - -This pattern greatly improves output quality. - -**Example 1: Style guide compliance** (for Skills without code): - -```markdown theme={null} -## Content review process - -1. Draft your content following the guidelines in STYLE_GUIDE.md -2. Review against the checklist: - - Check terminology consistency - - Verify examples follow the standard format - - Confirm all required sections are present -3. If issues found: - - Note each issue with specific section reference - - Revise the content - - Review the checklist again -4. Only proceed when all requirements are met -5. Finalize and save the document -``` - -This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Claude performs the check by reading and comparing. - -**Example 2: Document editing process** (for Skills with code): - -```markdown theme={null} -## Document editing process - -1. Make your edits to `word/document.xml` -2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/` -3. If validation fails: - - Review the error message carefully - - Fix the issues in the XML - - Run validation again -4. **Only proceed when validation passes** -5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx` -6. Test the output document -``` - -The validation loop catches errors early. - -## Content guidelines - -### Avoid time-sensitive information - -Don't include information that will become outdated: - -**Bad example: Time-sensitive** (will become wrong): - -```markdown theme={null} -If you're doing this before August 2025, use the old API. -After August 2025, use the new API. -``` - -**Good example** (use "old patterns" section): - -```markdown theme={null} -## Current method - -Use the v2 API endpoint: `api.example.com/v2/messages` - -## Old patterns - -
    -Legacy v1 API (deprecated 2025-08) - -The v1 API used: `api.example.com/v1/messages` - -This endpoint is no longer supported. -
    -``` - -The old patterns section provides historical context without cluttering the main content. - -### Use consistent terminology - -Choose one term and use it throughout the Skill: - -**Good - Consistent**: - -* Always "API endpoint" -* Always "field" -* Always "extract" - -**Bad - Inconsistent**: - -* Mix "API endpoint", "URL", "API route", "path" -* Mix "field", "box", "element", "control" -* Mix "extract", "pull", "get", "retrieve" - -Consistency helps Claude understand and follow instructions. - -## Common patterns - -### Template pattern - -Provide templates for output format. Match the level of strictness to your needs. - -**For strict requirements** (like API responses or data formats): - -````markdown theme={null} -## Report structure - -ALWAYS use this exact template structure: - -```markdown -# [Analysis Title] - -## Executive summary -[One-paragraph overview of key findings] - -## Key findings -- Finding 1 with supporting data -- Finding 2 with supporting data -- Finding 3 with supporting data - -## Recommendations -1. Specific actionable recommendation -2. Specific actionable recommendation -``` -```` - -**For flexible guidance** (when adaptation is useful): - -````markdown theme={null} -## Report structure - -Here is a sensible default format, but use your best judgment based on the analysis: - -```markdown -# [Analysis Title] - -## Executive summary -[Overview] - -## Key findings -[Adapt sections based on what you discover] - -## Recommendations -[Tailor to the specific context] -``` - -Adjust sections as needed for the specific analysis type. -```` - -### Examples pattern - -For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting: - -````markdown theme={null} -## Commit message format - -Generate commit messages following these examples: - -**Example 1:** -Input: Added user authentication with JWT tokens -Output: -``` -feat(auth): implement JWT-based authentication - -Add login endpoint and token validation middleware -``` - -**Example 2:** -Input: Fixed bug where dates displayed incorrectly in reports -Output: -``` -fix(reports): correct date formatting in timezone conversion - -Use UTC timestamps consistently across report generation -``` - -**Example 3:** -Input: Updated dependencies and refactored error handling -Output: -``` -chore: update dependencies and refactor error handling - -- Upgrade lodash to 4.17.21 -- Standardize error response format across endpoints -``` - -Follow this style: type(scope): brief description, then detailed explanation. -```` - -Examples help Claude understand the desired style and level of detail more clearly than descriptions alone. - -### Conditional workflow pattern - -Guide Claude through decision points: - -```markdown theme={null} -## Document modification workflow - -1. Determine the modification type: - - **Creating new content?** → Follow "Creation workflow" below - **Editing existing content?** → Follow "Editing workflow" below - -2. Creation workflow: - - Use docx-js library - - Build document from scratch - - Export to .docx format - -3. Editing workflow: - - Unpack existing document - - Modify XML directly - - Validate after each change - - Repack when complete -``` - - - If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand. - - -## Evaluation and iteration - -### Build evaluations first - -**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones. - -**Evaluation-driven development:** - -1. **Identify gaps**: Run Claude on representative tasks without a Skill. Document specific failures or missing context -2. **Create evaluations**: Build three scenarios that test these gaps -3. **Establish baseline**: Measure Claude's performance without the Skill -4. **Write minimal instructions**: Create just enough content to address the gaps and pass evaluations -5. **Iterate**: Execute evaluations, compare against baseline, and refine - -This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize. - -**Evaluation structure**: - -```json theme={null} -{ - "skills": ["pdf-processing"], - "query": "Extract all text from this PDF file and save it to output.txt", - "files": ["test-files/document.pdf"], - "expected_behavior": [ - "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool", - "Extracts text content from all pages in the document without missing any pages", - "Saves the extracted text to a file named output.txt in a clear, readable format" - ] -} -``` - - - This example demonstrates a data-driven evaluation with a simple testing rubric. We do not currently provide a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness. - - -### Develop Skills iteratively with Claude - -The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that will be used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need. - -**Creating a new Skill:** - -1. **Complete a task without a Skill**: Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide. - -2. **Identify the reusable pattern**: After completing the task, identify what context you provided that would be useful for similar future tasks. - - **Example**: If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns. - -3. **Ask Claude A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts." - - - Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content. - - -4. **Review for conciseness**: Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that." - -5. **Improve information architecture**: Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later." - -6. **Test on similar tasks**: Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully. - -7. **Iterate based on observation**: If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?" - -**Iterating on existing Skills:** - -The same hierarchical pattern continues when improving Skills. You alternate between: - -* **Working with Claude A** (the expert who helps refine the Skill) -* **Testing with Claude B** (the agent using the Skill to perform real work) -* **Observing Claude B's behavior** and bringing insights back to Claude A - -1. **Use the Skill in real workflows**: Give Claude B (with the Skill loaded) actual tasks, not test scenarios - -2. **Observe Claude B's behavior**: Note where it struggles, succeeds, or makes unexpected choices - - **Example observation**: "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule." - -3. **Return to Claude A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?" - -4. **Review Claude A's suggestions**: Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section. - -5. **Apply and test changes**: Update the Skill with Claude A's refinements, then test again with Claude B on similar requests - -6. **Repeat based on usage**: Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions. - -**Gathering team feedback:** - -1. Share Skills with teammates and observe their usage -2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing? -3. Incorporate feedback to address blind spots in your own usage patterns - -**Why this approach works**: Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions. - -### Observe how Claude navigates Skills - -As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for: - -* **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought -* **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent -* **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead -* **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions - -Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used. - -## Anti-patterns to avoid - -### Avoid Windows-style paths - -Always use forward slashes in file paths, even on Windows: - -* ✓ **Good**: `scripts/helper.py`, `reference/guide.md` -* ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md` - -Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems. - -### Avoid offering too many options - -Don't present multiple approaches unless necessary: - -````markdown theme={null} -**Bad example: Too many choices** (confusing): -"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..." - -**Good example: Provide a default** (with escape hatch): -"Use pdfplumber for text extraction: -```python -import pdfplumber -``` - -For scanned PDFs requiring OCR, use pdf2image with pytesseract instead." -```` - -## Advanced: Skills with executable code - -The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills). - -### Solve, don't punt - -When writing scripts for Skills, handle error conditions rather than punting to Claude. - -**Good example: Handle errors explicitly**: - -```python theme={null} -def process_file(path): - """Process a file, creating it if it doesn't exist.""" - try: - with open(path) as f: - return f.read() - except FileNotFoundError: - # Create file with default content instead of failing - print(f"File {path} not found, creating default") - with open(path, 'w') as f: - f.write('') - return '' - except PermissionError: - # Provide alternative instead of failing - print(f"Cannot access {path}, using default") - return '' -``` - -**Bad example: Punt to Claude**: - -```python theme={null} -def process_file(path): - # Just fail and let Claude figure it out - return open(path).read() -``` - -Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it? - -**Good example: Self-documenting**: - -```python theme={null} -# HTTP requests typically complete within 30 seconds -# Longer timeout accounts for slow connections -REQUEST_TIMEOUT = 30 - -# Three retries balances reliability vs speed -# Most intermittent failures resolve by the second retry -MAX_RETRIES = 3 -``` - -**Bad example: Magic numbers**: - -```python theme={null} -TIMEOUT = 47 # Why 47? -RETRIES = 5 # Why 5? -``` - -### Provide utility scripts - -Even if Claude could write a script, pre-made scripts offer advantages: - -**Benefits of utility scripts**: - -* More reliable than generated code -* Save tokens (no need to include code in context) -* Save time (no code generation required) -* Ensure consistency across uses - -Bundling executable scripts alongside instruction files - -The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context. - -**Important distinction**: Make clear in your instructions whether Claude should: - -* **Execute the script** (most common): "Run `analyze_form.py` to extract fields" -* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm" - -For most utility scripts, execution is preferred because it's more reliable and efficient. See the [Runtime environment](#runtime-environment) section below for details on how script execution works. - -**Example**: - -````markdown theme={null} -## Utility scripts - -**analyze_form.py**: Extract all form fields from PDF - -```bash -python scripts/analyze_form.py input.pdf > fields.json -``` - -Output format: -```json -{ - "field_name": {"type": "text", "x": 100, "y": 200}, - "signature": {"type": "sig", "x": 150, "y": 500} -} -``` - -**validate_boxes.py**: Check for overlapping bounding boxes - -```bash -python scripts/validate_boxes.py fields.json -# Returns: "OK" or lists conflicts -``` - -**fill_form.py**: Apply field values to PDF - -```bash -python scripts/fill_form.py input.pdf fields.json output.pdf -``` -```` - -### Use visual analysis - -When inputs can be rendered as images, have Claude analyze them: - -````markdown theme={null} -## Form layout analysis - -1. Convert PDF to images: - ```bash - python scripts/pdf_to_images.py form.pdf - ``` - -2. Analyze each page image to identify form fields -3. Claude can see field locations and types visually -```` - - - In this example, you'd need to write the `pdf_to_images.py` script. - - -Claude's vision capabilities help understand layouts and structures. - -### Create verifiable intermediate outputs - -When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it. - -**Example**: Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly. - -**Solution**: Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify. - -**Why this pattern works:** - -* **Catches errors early**: Validation finds problems before changes are applied -* **Machine-verifiable**: Scripts provide objective verification -* **Reversible planning**: Claude can iterate on the plan without touching originals -* **Clear debugging**: Error messages point to specific problems - -**When to use**: Batch operations, destructive changes, complex validation rules, high-stakes operations. - -**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues. - -### Package dependencies - -Skills run in the code execution environment with platform-specific limitations: - -* **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories -* **Anthropic API**: Has no network access and no runtime package installation - -List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool). - -### Runtime environment - -Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/en/docs/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview. - -**How this affects your authoring:** - -**How Claude accesses Skills:** - -1. **Metadata pre-loaded**: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt -2. **Files read on-demand**: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed -3. **Scripts executed efficiently**: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens -4. **No context penalty for large files**: Reference files, data, or documentation don't consume context tokens until actually read - -* **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes -* **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md` -* **Organize for discovery**: Structure directories by domain or feature - * Good: `reference/finance.md`, `reference/sales.md` - * Bad: `docs/file1.md`, `docs/file2.md` -* **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed -* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code -* **Make execution intent clear**: - * "Run `analyze_form.py` to extract fields" (execute) - * "See `analyze_form.py` for the extraction algorithm" (read as reference) -* **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests - -**Example:** - -``` -bigquery-skill/ -├── SKILL.md (overview, points to reference files) -└── reference/ - ├── finance.md (revenue metrics) - ├── sales.md (pipeline data) - └── product.md (usage analytics) -``` - -When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires. - -For complete details on the technical architecture, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview. - -### MCP tool references - -If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors. - -**Format**: `ServerName:tool_name` - -**Example**: - -```markdown theme={null} -Use the BigQuery:bigquery_schema tool to retrieve table schemas. -Use the GitHub:create_issue tool to create issues. -``` - -Where: - -* `BigQuery` and `GitHub` are MCP server names -* `bigquery_schema` and `create_issue` are the tool names within those servers - -Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available. - -### Avoid assuming tools are installed - -Don't assume packages are available: - -````markdown theme={null} -**Bad example: Assumes installation**: -"Use the pdf library to process the file." - -**Good example: Explicit about dependencies**: -"Install required package: `pip install pypdf` - -Then use it: -```python -from pypdf import PdfReader -reader = PdfReader("file.pdf") -```" -```` - -## Technical notes - -### YAML frontmatter requirements - -The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules: - -* `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words -* `description`: Maximum 1024 characters, non-empty, no XML tags - -See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details. - -### Token budgets - -Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work). - -## Checklist for effective Skills - -Before sharing a Skill, verify: - -### Core quality - -* [ ] Description is specific and includes key terms -* [ ] Description includes both what the Skill does and when to use it -* [ ] SKILL.md body is under 500 lines -* [ ] Additional details are in separate files (if needed) -* [ ] No time-sensitive information (or in "old patterns" section) -* [ ] Consistent terminology throughout -* [ ] Examples are concrete, not abstract -* [ ] File references are one level deep -* [ ] Progressive disclosure used appropriately -* [ ] Workflows have clear steps - -### Code and scripts - -* [ ] Scripts solve problems rather than punt to Claude -* [ ] Error handling is explicit and helpful -* [ ] No "voodoo constants" (all values justified) -* [ ] Required packages listed in instructions and verified as available -* [ ] Scripts have clear documentation -* [ ] No Windows-style paths (all forward slashes) -* [ ] Validation/verification steps for critical operations -* [ ] Feedback loops included for quality-critical tasks - -### Testing - -* [ ] At least three evaluations created -* [ ] Tested with Haiku, Sonnet, and Opus -* [ ] Tested with real usage scenarios -* [ ] Team feedback incorporated (if applicable) - -## Next steps - - - - Create your first Skill - - - - Create and manage Skills in Claude Code - - - - Use Skills programmatically in TypeScript and Python - - - - Upload and use Skills programmatically - - - -# Agent Skills - -> Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. - -## Why use Skills - -Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. - -**Key benefits**: - -* **Specialize Claude**: Tailor capabilities for domain-specific tasks -* **Reduce repetition**: Create once, use automatically -* **Compose capabilities**: Combine Skills to build complex workflows - - - For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills). - - -## Using Skills - -Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way. Claude automatically uses them when relevant to your request. - -**Pre-built Agent Skills** are available to all users on claude.ai and via the Claude API. See the [Available Skills](#available-skills) section below for the complete list. - -**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them via the API, or add them in claude.ai settings. - - - **Get started:** - - * For pre-built Agent Skills: See the [quickstart tutorial](/en/docs/agents-and-tools/agent-skills/quickstart) to start using PowerPoint, Excel, Word, and PDF skills in the API - * For custom Skills: See the [Agent Skills Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills) to learn how to create your own Skills - - -## How Skills work - -Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member. - -This filesystem-based architecture enables **progressive disclosure**: Claude loads information in stages as needed, rather than consuming context upfront. - -### Three types of Skill content, three levels of loading - -Skills can contain three types of content, each loaded at different times: - -### Level 1: Metadata (always loaded) - -**Content type: Instructions**. The Skill's YAML frontmatter provides discovery information: - -```yaml theme={null} ---- -name: pdf-processing -description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ---- -``` - -Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it. - -### Level 2: Instructions (loaded when triggered) - -**Content type: Instructions**. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance: - -````markdown theme={null} -# PDF Processing - -## Quick start - -Use pdfplumber to extract text from PDFs: - -```python -import pdfplumber - -with pdfplumber.open("document.pdf") as pdf: - text = pdf.pages[0].extract_text() -``` - -For advanced form filling, see [FORMS.md](FORMS.md). -```` - -When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window. - -### Level 3: Resources and code (loaded as needed) - -**Content types: Instructions, code, and resources**. Skills can bundle additional materials: - -``` -pdf-skill/ -├── SKILL.md (main instructions) -├── FORMS.md (form-filling guide) -├── REFERENCE.md (detailed API reference) -└── scripts/ - └── fill_form.py (utility script) -``` - -**Instructions**: Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows - -**Code**: Executable scripts (fill\_form.py, validate.py) that Claude runs via bash; scripts provide deterministic operations without consuming context - -**Resources**: Reference materials like database schemas, API documentation, templates, or examples - -Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup. - -| Level | When Loaded | Token Cost | Content | -| ------------------------- | ----------------------- | ---------------------- | --------------------------------------------------------------------- | -| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter | -| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance | -| **Level 3+: Resources** | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context | - -Progressive disclosure ensures only relevant content occupies the context window at any given time. - -### The Skills architecture - -Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Think of it like this: Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer. - -Agent Skills Architecture - showing how Skills integrate with the agent's configuration and virtual machine - -**How Claude accesses Skill content:** - -When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (like FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them via bash and receives only the output (the script code itself never enters context). - -**What this architecture enables:** - -**On-demand file access**: Claude reads only the files needed for each specific task. A Skill can include dozens of reference files, but if your task only needs the sales schema, Claude loads just that one file. The rest remain on the filesystem consuming zero tokens. - -**Efficient script execution**: When Claude runs `validate_form.py`, the script's code never loads into the context window. Only the script's output (like "Validation passed" or specific error messages) consumes tokens. This makes scripts far more efficient than having Claude generate equivalent code on the fly. - -**No practical limit on bundled content**: Because files don't consume context until accessed, Skills can include comprehensive API documentation, large datasets, extensive examples, or any reference materials you need. There's no context penalty for bundled content that isn't used. - -This filesystem-based model is what makes progressive disclosure work. Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires. - -### Example: Loading a PDF processing skill - -Here's how Claude loads and uses a PDF processing skill: - -1. **Startup**: System prompt includes: `PDF Processing - Extract text and tables from PDF files, fill forms, merge documents` -2. **User request**: "Extract the text from this PDF and summarize it" -3. **Claude invokes**: `bash: read pdf-skill/SKILL.md` → Instructions loaded into context -4. **Claude determines**: Form filling is not needed, so FORMS.md is not read -5. **Claude executes**: Uses instructions from SKILL.md to complete the task - -Skills loading into context window - showing the progressive loading of skill metadata and content - -The diagram shows: - -1. Default state with system prompt and skill metadata pre-loaded -2. Claude triggers the skill by reading SKILL.md via bash -3. Claude optionally reads additional bundled files like FORMS.md as needed -4. Claude proceeds with the task - -This dynamic loading ensures only relevant skill content occupies the context window. - -## Where Skills work - -Skills are available across Claude's agent products: - -### Claude API - -The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant `skill_id` in the `container` parameter along with the code execution tool. - -**Prerequisites**: Using Skills via the API requires three beta headers: - -* `code-execution-2025-08-25` - Skills run in the code execution container -* `skills-2025-10-02` - Enables Skills functionality -* `files-api-2025-04-14` - Required for uploading/downloading files to/from the container - -Use pre-built Agent Skills by referencing their `skill_id` (e.g., `pptx`, `xlsx`), or create and upload your own via the Skills API (`/v1/skills` endpoints). Custom Skills are shared organization-wide. - -To learn more, see [Use Skills with the Claude API](/en/docs/build-with-claude/skills-guide). - -### Claude Code - -[Claude Code](https://code.claude.com/docs/en/overview) supports only Custom Skills. - -**Custom Skills**: Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically. - -Custom Skills in Claude Code are filesystem-based and don't require API uploads. - -To learn more, see [Use Skills in Claude Code](https://code.claude.com/docs/en/skills). - -### Claude Agent SDK - -The [Claude Agent SDK](/en/docs/agent-sdk/overview) supports custom Skills through filesystem-based configuration. - -**Custom Skills**: Create Skills as directories with SKILL.md files in `.claude/skills/`. Enable Skills by including `"Skill"` in your `allowed_tools` configuration. - -Skills in the Agent SDK are then automatically discovered when the SDK runs. - -To learn more, see [Agent Skills in the SDK](/en/docs/agent-sdk/skills). - -### Claude.ai - -[Claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills. - -**Pre-built Agent Skills**: These Skills are already working behind the scenes when you create documents. Claude uses them without requiring any setup. - -**Custom Skills**: Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled. Custom Skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins. - -To learn more about using Skills in Claude.ai, see the following resources in the Claude Help Center: - -* [What are Skills?](https://support.claude.com/en/articles/12512176-what-are-skills) -* [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude) -* [How to create custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills) -* [Teach Claude your way of working using Skills](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills) - -## Skill structure - -Every Skill requires a `SKILL.md` file with YAML frontmatter: - -```yaml theme={null} ---- -name: your-skill-name -description: Brief description of what this Skill does and when to use it ---- - -# Your Skill Name - -## Instructions -[Clear, step-by-step guidance for Claude to follow] - -## Examples -[Concrete examples of using this Skill] -``` - -**Required fields**: `name` and `description` - -**Field requirements**: - -`name`: - -* Maximum 64 characters -* Must contain only lowercase letters, numbers, and hyphens -* Cannot contain XML tags -* Cannot contain reserved words: "anthropic", "claude" - -`description`: - -* Must be non-empty -* Maximum 1024 characters -* Cannot contain XML tags - -The `description` should include both what the Skill does and when Claude should use it. For complete authoring guidance, see the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices). - -## Security considerations - -We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills provide Claude with new capabilities through instructions and code, and while this makes them powerful, it also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose. - - - If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks. - - -**Key security considerations**: - -* **Audit thoroughly**: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns like unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose -* **External sources are risky**: Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time -* **Tool misuse**: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways -* **Data exposure**: Skills with access to sensitive data could be designed to leak information to external systems -* **Treat like installing software**: Only use Skills from trusted sources. Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations - -## Available Skills - -### Pre-built Agent Skills - -The following pre-built Agent Skills are available for immediate use: - -* **PowerPoint (pptx)**: Create presentations, edit slides, analyze presentation content -* **Excel (xlsx)**: Create spreadsheets, analyze data, generate reports with charts -* **Word (docx)**: Create documents, edit content, format text -* **PDF (pdf)**: Generate formatted PDF documents and reports - -These Skills are available on the Claude API and claude.ai. See the [quickstart tutorial](/en/docs/agents-and-tools/agent-skills/quickstart) to start using them in the API. - -### Custom Skills examples - -For complete examples of custom Skills, see the [Skills cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills). - -## Limitations and constraints - -Understanding these limitations helps you plan your Skills deployment effectively. - -### Cross-surface availability - -**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others: - -* Skills uploaded to Claude.ai must be separately uploaded to the API -* Skills uploaded via the API are not available on Claude.ai -* Claude Code Skills are filesystem-based and separate from both Claude.ai and API - -You'll need to manage and upload Skills separately for each surface where you want to use them. - -### Sharing scope - -Skills have different sharing models depending on where you use them: - -* **Claude.ai**: Individual user only; each team member must upload separately -* **Claude API**: Workspace-wide; all workspace members can access uploaded Skills -* **Claude Code**: Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`); can also be shared via Claude Code Plugins +## Troubleshooting -Claude.ai does not currently support centralized admin management or org-wide distribution of custom Skills. +### Skill not triggering -### Runtime environment constraints +If Claude doesn't use your skill when expected: -The exact runtime environment available to your skill depends on the product surface where you use it. +1. Check the description includes keywords users would naturally say +2. Verify the skill appears in `What skills are available?` +3. Try rephrasing your request to match the description more closely +4. Invoke it directly with `/skill-name` if the skill is user-invocable -* **Claude.ai**: - * **Varying network access**: Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article. -* **Claude API**: - * **No network access**: Skills cannot make external API calls or access the internet - * **No runtime package installation**: Only pre-installed packages are available. You cannot install new packages during execution. - * **Pre-configured dependencies only**: Check the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool) for the list of available packages -* **Claude Code**: - * **Full network access**: Skills have the same network access as any other program on the user's computer - * **Global package installation discouraged**: Skills should only install packages locally in order to avoid interfering with the user's computer +### Skill triggers too often -Plan your Skills to work within these constraints. +If Claude uses your skill when you don't want it: -## Next steps +1. Make the description more specific +2. Add `disable-model-invocation: true` if you only want manual invocation - - - Create your first Skill - +### Claude doesn't see all my skills - - Use Skills with the Claude API - +Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget. The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Run `/context` to check for a warning about excluded skills. - - Create and manage custom Skills in Claude Code - +To override the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. - - Use Skills programmatically in TypeScript and Python - +## Related resources - - Write Skills that Claude can use effectively - - +* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents +* **[Plugins](/en/plugins)**: package and distribute skills with other extensions +* **[Hooks](/en/hooks)**: automate workflows around tool events +* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context +* **[Interactive mode](/en/interactive-mode#built-in-commands)**: built-in commands and shortcuts +* **[Permissions](/en/permissions)**: control tool and skill access diff --git a/thoughts/nikey_es/notes/create_deep_reasearch_plugin.md b/thoughts/nikey_es/notes/create_deep_reasearch_plugin.md new file mode 100644 index 0000000..5b31d6f --- /dev/null +++ b/thoughts/nikey_es/notes/create_deep_reasearch_plugin.md @@ -0,0 +1,137 @@ +# Anatomía completa del agente Research de Claude.ai + +**La función Research de Claude.ai es un sistema multi-agente con patrón orquestador-trabajador**, donde un agente líder (Claude Opus 4) coordina múltiples sub-agentes especializados (Claude Sonnet 4) que buscan información en paralelo, cada uno con su propia ventana de contexto de 200K tokens. Este sistema superó al Claude Opus 4 en modo single-agent por un **90.2%** en las evaluaciones internas de Anthropic. Anthropic publicó en junio de 2025 un blog de ingeniería extraordinariamente detallado documentando toda la arquitectura, y la comunidad ha filtrado los system prompts completos que gobiernan tanto el modo Research dedicado como las instrucciones de búsqueda del chat regular. + +--- + +## Tres agentes distintos conforman la arquitectura + +El sistema Research opera con tres tipos de agentes claramente diferenciados, según documenta el blog de ingeniería de Anthropic ("How we built our multi-agent research system", publicado el 13 de junio de 2025 por Jeremy Hadfield, Barry Zhang y equipo): + +**LeadResearcher (Orquestador):** Ejecuta Claude Opus 4 con extended thinking mode activado. Recibe la consulta del usuario, analiza la complejidad, desarrolla un plan de investigación y lo guarda en una herramienta de **Memory** (crítica porque si el contexto supera 200K tokens se trunca, y el plan debe persistir). Luego delega tareas específicas a sub-agentes, sintetiza sus resultados, y decide si necesita más investigación o puede proceder a generar el reporte final. + +**Subagents (Trabajadores):** Ejecutan Claude Sonnet 4 con interleaved thinking (razonamiento intercalado entre llamadas a herramientas). Cada sub-agente opera **independientemente** con su propia ventana de contexto, ejecuta búsquedas web iterativamente, evalúa la calidad de los resultados, y devuelve hallazgos comprimidos al LeadResearcher. Funcionan como "filtros inteligentes" y "motores de compresión" — exploran extensamente y destilan lo más importante. + +**CitationAgent:** Procesa el reporte final e identifica con precisión quirúrgica dónde corresponde cada cita. Reduce las alucinaciones de fuentes de ~10% a prácticamente 0%. Opera después de que el LeadResearcher completa la síntesis. + +La clave arquitectónica es que los sub-agentes operan en **contextos separados**, lo que resuelve el problema fundamental de la ventana de contexto limitada. Como señaló Simon Willison en su análisis: el beneficio principal es gestionar el límite de 200K tokens distribuyendo el trabajo en contextos independientes. + +--- + +## El system prompt filtrado revela dos capas de instrucciones + +Los system prompts han sido extensamente documentados por la comunidad. Existen **dos capas** de instrucciones de búsqueda distintas: + +**Capa 1 — El prompt del modo Research dedicado** fue filtrado por @fun000001 (fisherdaddy) en X el 6 de mayo de 2025. Cuando el usuario activa el botón Research en la interfaz, Claude.ai inyecta un bloque `` que incluye: + +- Instrucción de usar `launch_extended_search_task` como herramienta prioritaria sobre todas las demás +- Solo dos excepciones: mensajes conversacionales básicos ("hola") o preguntas extremadamente simples ("capital de Francia") +- Reglas de preguntas clarificadoras: máximo 3 preguntas, solo cuando hay ambigüedades genuinas; si el usuario dice "Research X" explícitamente, lanzar inmediatamente +- Instrucciones de seguridad específicas para el modo Research (bloque ``) +- Ejemplos trabajados mostrando cuándo preguntar vs. cuándo lanzar directamente + +**Capa 2 — Las instrucciones de búsqueda del chat regular** (~6,471 tokens) clasifican cada consulta en cuatro categorías: Never Search (hechos atemporales), Do Not Search But Offer (datos estables), Single Search (datos en tiempo real), y **Research** (análisis multi-fuente que requiere 2-20 llamadas a herramientas). El prompt incluye un flowchart de decisión basado en complejidad, e instruye que si una tarea necesita más de 20 llamadas, debe sugerir al usuario activar la función Research dedicada. + +Los prompts de los agentes de investigación están publicados oficialmente en el Anthropic Cookbook en GitHub: el prompt del agente líder en `anthropic-cookbook/patterns/agents/prompts/research_lead_agent.md` y el del sub-agente en `research_subagent.md`. El sub-agente usa un **loop OODA** (Observe, Orient, Decide, Act) como ciclo de investigación central, con un límite duro de **20 llamadas a herramientas y ~100 fuentes** antes de ser terminado. + +Las filtraciones completas están recopiladas en el repositorio `asgeirtj/system_prompts_leaks` (31.7K estrellas), con análisis detallados publicados por Simon Willison, PromptHub, O'Reilly Radar, y DEJAN AI. + +--- + +## Siete herramientas componen el arsenal del agente + +El sistema Research tiene acceso a las siguientes herramientas documentadas: + +- **`web_search`** — búsqueda web (se cree que usa Brave Search, con latencia de ~0.56 segundos por consulta) +- **`web_fetch`** — recupera el contenido completo de páginas web, no solo snippets +- **`launch_extended_search_task`** — la herramienta clave del modo Research, que instancia sub-agentes independientes +- **`Memory`** — persiste el plan de investigación y hallazgos clave para sobrevivir truncamientos de contexto +- **Servidores MCP** — conectan con herramientas externas como Google Workspace (Gmail, Calendar, Drive, Docs), Slack, y otras integraciones +- **`complete_task`** — herramienta que los sub-agentes invocan para devolver su reporte al agente líder +- **Llamadas paralelas a herramientas** — directiva `` que obliga a invocar herramientas simultáneamente + +La orquestación opera en **dos niveles de paralelización**: el agente líder lanza **3-5 sub-agentes en paralelo**, y cada sub-agente ejecuta **3+ herramientas en paralelo**. Este doble nivel de paralelismo redujo el tiempo de investigación hasta un **90%** para consultas complejas. + +--- + +## El flujo paso a paso desde consulta hasta reporte citado + +El workflow completo sigue estas fases: + +**1. Recepción y clasificación.** El agente líder recibe la consulta y usa extended thinking para evaluar su complejidad. Aplica reglas de escalamiento embebidas en el prompt: consultas simples → 1 agente con 3-10 llamadas; comparaciones → 2-4 sub-agentes con 10-15 llamadas cada uno; investigación compleja → **10+ sub-agentes** con responsabilidades claramente divididas. + +**2. Planificación y persistencia.** El LeadResearcher desarrolla un plan de investigación detallado y lo guarda en Memory. Este paso es crucial porque si el contexto se trunca a 200K tokens, el plan sobrevive. + +**3. Delegación paralela.** El agente líder crea sub-agentes con instrucciones extremadamente específicas: objetivo concreto, formato de salida esperado, contexto relevante, fuentes sugeridas, y límites de alcance para evitar solapamiento. + +**4. Investigación independiente.** Cada sub-agente ejecuta un loop iterativo: busca con queries **cortas y amplias** (menos de 5 palabras), evalúa resultados con interleaved thinking, luego progresivamente estrecha el enfoque. La estrategia de búsqueda imita la investigación humana experta: explorar el panorama antes de profundizar en detalles. + +**5. Síntesis iterativa.** El LeadResearcher reúne los hallazgos comprimidos de todos los sub-agentes, evalúa la completitud, e identifica vacíos. Si hay gaps, puede lanzar sub-agentes adicionales o refinar la estrategia. Este loop continúa hasta que la información es suficiente. + +**6. Citación.** El CitationAgent procesa el reporte final y mapea cada afirmación a sus fuentes con precisión (números de página, índices de caracteres, bloques de contenido). + +**7. Entrega.** El reporte citado se presenta al usuario, típicamente como un documento de ~5 páginas con 20-25 fuentes, completado en **2-6 minutos**. + +Un dato revelador: **86.7% de las citas finales provienen de los resultados de búsqueda iniciales**, y el sistema re-busca automáticamente cuando la confianza cae por debajo del 95%. + +--- + +## La documentación oficial es excepcionalmente transparente + +Anthropic ha publicado documentación técnica de calidad extraordinaria sobre este sistema: + +El **blog de ingeniería** en `anthropic.com/engineering/multi-agent-research-system` es la fuente definitiva, con arquitectura completa, métricas de rendimiento, modos de fallo tempranos, y 8 principios de diseño de prompts. Complementariamente, el blog "Building agents with the Claude Agent SDK" documenta el SDK (renombrado de "Claude Code SDK") que permite construir agentes similares, y el blog "Effective context engineering for AI agents" detalla las técnicas de gestión de contexto. + +El **Anthropic Cookbook** en GitHub contiene los prompts de producción del agente líder y del sub-agente, lo que constituye un caso excepcional de transparencia — ningún otro proveedor ha publicado los prompts reales de su sistema de investigación. Además, el repositorio `anthropics/claude-agent-sdk-demos/tree/main/research-agent` incluye una implementación oficial de referencia con agentes RESEARCHER, DATA-ANALYST, y generación de visualizaciones. + +El **anuncio de producto** en `anthropic.com/news/research` describe las capacidades desde la perspectiva del usuario, y la documentación de la API en `docs.anthropic.com` cubre la herramienta web_search para uso programático (una versión simplificada single-agent del sistema completo de Research). + +--- + +## Más de 20 proyectos de la comunidad replican la funcionalidad + +La comunidad ha creado un ecosistema vibrante de proyectos open-source que replican la funcionalidad Research: + +**Proyectos específicos para Claude Code** incluyen `willccbb/claude-deep-research` (222 estrellas), que es un wrapper de Claude Code con MCP servers (Brave Search, E2B sandbox, filesystem); `AnkitClassicVision/Claude-Code-Deep-Research` (67 estrellas), con un playbook de 7 fases y Graph-of-Thoughts; y `gtrusler/claude-code-heavy`, un orquestador shell que lanza 2-8 asistentes Claude Code en paralelo. + +**Implementaciones con la API de Anthropic** son abundantes: `dzhng/deep-research` (**18,400 estrellas**) es el proyecto fundacional — menos de 500 líneas de TypeScript con exploración recursiva depth-first + breadth-first; `Cranot/deep-research` (84 estrellas) implementa "exploración fractal" con 4 estrategias de investigación y soporte para 7 proveedores LLM incluyendo Claude; y `langchain-ai/open_deep_research` (~2,685 estrellas) usa LangGraph con arquitectura supervisor-researcher compatible con modelos Anthropic. + +**Servidores MCP** como `mcherukara/Claude-Deep-Research` proporcionan una herramienta `deep_research` para Claude Desktop usando DuckDuckGo y Semantic Scholar. El gist de XInTheDark ofrece un prompt personalizado completo con MCP servers (Brave Search, Fetch, Puppeteer) que el autor argumenta produce mejores resultados que el Research integrado. + +**La implementación oficial de referencia** en `anthropics/claude-agent-sdk-demos` usa el Claude Agent SDK con sub-agentes tipados (RESEARCHER-1, DATA-ANALYST-1), hooks de seguimiento, y generación de PDFs con visualizaciones. El curso "Agent Skills with Anthropic" de DeepLearning.AI (enseñado por Elie Schoppik) cubre la construcción de estos agentes paso a paso. + +El costo de replicación en producción oscila entre **$0.20-0.60 por consulta** para implementaciones optimizadas, pudiendo llegar a $1-5 con spawning recursivo agresivo. + +--- + +## Claude es el único sistema genuinamente multi-agente entre sus competidores + +La comparación arquitectónica con otros sistemas de deep research revela diferencias fundamentales: + +**OpenAI Deep Research** usa un agente único basado en o3 (o o4-mini para la versión ligera), entrenado end-to-end con reinforcement learning en entornos simulados de investigación. No es multi-agente — es un modelo de razonamiento extendido con un loop ReAct (Plan-Act-Observe). Ejecuta 30-60 búsquedas, lee 120-150 páginas, y tarda **5-30 minutos** produciendo reportes extensos de 8,000-15,000+ palabras. Su fortaleza es la profundidad analítica; su debilidad es la lentitud y el precio (requiere suscripción Pro de $200/mes para uso completo). + +**Gemini Deep Research** de Google opera como un agente único con gestor asíncrono de tareas y una ventana de contexto de **1M+ tokens**. Su diferenciador es que presenta el plan de investigación al usuario para revisión antes de ejecutar (único entre los competidores). Ejecuta 80-160 queries de búsqueda, tarda **15-60 minutos** (el más lento), pero lidera en precisión de datos según benchmarks independientes. Es nativamente multimodal (texto, imágenes, audio, video) y se integra profundamente con el ecosistema Google. + +**Perplexity Deep Research** usa un pipeline RAG iterativo con routing multi-modelo (Sonar propietario + GPT-5, Claude 4.5, Gemini). No es multi-agente sino un loop iterativo de 3-5 pasadas secuenciales sobre infraestructura Vespa.ai. Es **el más rápido** (2-4 minutos) y **el más accesible** ($20/mes), con la mejor transparencia de citas (cada respuesta tiene citas numeradas con enlaces directos). Lidera en accuracy en el benchmark DR-50 de AIMultiple con **34%**. + +| Dimensión | Claude Research | OpenAI Deep Research | Gemini Deep Research | Perplexity | +|---|---|---|---|---| +| **Arquitectura** | Multi-agente (orquestador + workers paralelos) | Agente único con RL | Agente único con task manager async | Pipeline RAG iterativo | +| **Modelo** | Opus 4 (líder) + Sonnet 4 (sub-agentes) | o3 / o4-mini | Gemini 3 Pro | Multi-modelo (routing) | +| **Sub-agentes** | Sí (1-10+) | No | No | No | +| **Tiempo típico** | 2-6 minutos | 5-30 minutos | 15-60 minutos | 2-4 minutos | +| **Búsquedas** | Variable (3-100+ distribuidas entre sub-agentes) | 30-60 | 80-160 | Docenas (3-5 pasadas) | +| **Precio mínimo** | $100/mes (Max) | $20/mes (Plus, limitado) | $20/mes (Advanced) | $20/mes (Pro) | +| **Fortaleza** | Cobertura de fuentes, paralelismo | Profundidad analítica | Precisión, multimodal | Velocidad, citas | + +El hallazgo más significativo de Anthropic es que el **uso de tokens explica el 80% de la varianza en rendimiento** — más tokens equivale a mejores resultados. La arquitectura multi-agente es fundamentalmente un mecanismo para escalar el consumo de tokens más allá de los límites de un agente único, con cada sub-agente aportando su propio presupuesto de 200K tokens al esfuerzo colectivo. + +--- + +## Conclusión: transparencia como ventaja competitiva + +Lo más notable del sistema Research de Claude.ai no es solo su arquitectura — es el nivel de transparencia con que Anthropic la ha documentado. Mientras OpenAI, Google y Perplexity mantienen sus implementaciones como cajas negras, Anthropic publicó el blog de ingeniería más detallado de la industria sobre diseño de agentes, junto con los prompts de producción reales en GitHub. Esta transparencia ha catalizado un ecosistema de más de 20 proyectos open-source que replican y extienden la funcionalidad. + +Los modos de fallo documentados son igualmente valiosos: agentes tempranos lanzaban 50 sub-agentes para consultas simples, elegían granjas de contenido SEO sobre fuentes autoritativas, y se distraían mutuamente con actualizaciones excesivas. Las soluciones — reglas de escalamiento embebidas, estrategia de búsqueda "ancha primero", y sub-agentes como filtros de compresión — representan lecciones prácticas que ningún paper académico sobre sistemas multi-agente ha articulado con esta claridad. + +Para quien desee replicar el sistema, el camino más directo es el Claude Agent SDK con los prompts del Anthropic Cookbook como punto de partida, complementado con Brave Search API para búsquedas web y MCP servers para integraciones. El patrón arquitectónico fundamental es sorprendentemente simple: **planificar → delegar en paralelo → comprimir resultados → iterar si hay gaps → citar**. La complejidad está en los detalles de prompt engineering, no en la orquestación. \ No newline at end of file diff --git a/thoughts/nikey_es/notes/plugins-claude-code.md b/thoughts/nikey_es/notes/plugins-claude-code.md index 341f70c..2d911d3 100644 --- a/thoughts/nikey_es/notes/plugins-claude-code.md +++ b/thoughts/nikey_es/notes/plugins-claude-code.md @@ -1,741 +1,48 @@ -[](/blog-product/claude-code) - -Claude Code - -[](/blog-usecases/coding) - -Coding - -[ - -](https://claude.ai/redirect/claudedotcom.v1.fc414c21-3f81-4ba1-a0c5-8933dee86960) - -Explore here - -Guide: Building AI agents for financial services - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/68c469d2d09b203c164ad8e6_og-claude-education.jpg) - -Learn how teams at NBIM, Brex, and more build reliable AI agents with Claude on AWS Bedrock. - -Read more - -[Read more](https://resources.anthropic.com/financial-services-guide-aws-anthropic)Read more - -Guide: Building AI agents for financial services - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -[Next](#)Next - -Learn how teams at NBIM, Brex, and more build reliable AI agents with Claude on AWS Bedrock. - -Read more - -[Read more](https://resources.anthropic.com/financial-services-guide-aws-anthropic)Read more - -Guide: Building AI agents for financial services - -Learn how teams at NBIM, Brex, and more build reliable AI agents with Claude on AWS Bedrock. - -Read more - -[Read more](https://resources.anthropic.com/financial-services-guide-aws-anthropic)Read more - -![](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6903d22d7d4c10df6024f7bc_ee580919acaba2ddc07425f7a7390c8962cadc94-1000x1000.svg) - -# - -Customize - -Claude - -Code - -with - -plugins - -Claude - -Code - -now - -supports - -plugins: - -custom - -collections - -of - -slash - -commands, - -agents, - -MCP - -servers, - -and - -hooks - -that - -install - -with - -a - -single - -command. - -[](#) - -[](#) - -* Category - - [Product announcements](https://claude.com/blog/category/announcements) - -* Product - - Claude Code - -* Date - - October 9, 2025 - -* Reading time - - 2 - - min - -* Share - - [Copy link](#) - - -### Share your Claude Code setup with plugins - -Slash commands, agents, MCP servers, and hooks are all extension points you can use to customize your experience with Claude Code. As we've rolled them out, we've seen users build increasingly powerful setups that they want to share with teammates and the broader community. We built plugins to make this easier. - -Plugins are a lightweight way to package and share any combination of: - -* **Slash commands**: Create custom shortcuts for frequently-used operations -* **Subagents**: Install purpose-built agents for specialized development tasks -* **MCP servers**: Connect to tools and data sources through the Model Context Protocol -* **Hooks**: Customize Claude Code's behavior at key points in its workflow - -You can install plugins directly within Claude Code using the `/plugin` command, now in public beta. They’re designed to toggle on and off as needed. Enable them when you need specific capabilities and disable them when you don’t to reduce system prompt context and complexity. - -![Product screenshot showing Claude Code plugin menu](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/68e95d95ecae26885bafdfde_81805a2d45f087f2cc153168759f8bf015706b04-1920x1035.png) - -Moving forward, plugins will be our standard way to bundle and share Claude Code customizations, and we’ll continue to evolve the format as we add more extension points. - -### Use cases - -Plugins help you standardize Claude Code environments around a set of shared best practices. Common plugin use cases include: - -* **Enforcing standards:** Engineering leaders can maintain consistency across their team by using plugins to ensure specific hooks run for code reviews or testing workflows -* **Supporting users**: Open source maintainers, for example, can provide slash commands that help developers use their packages correctly -* **Sharing workflows:** Developers who build productivity-boosting workflows—like debugging setups, deployment pipelines, or testing harnesses—can easily share them with others -* **Connecting tools:** Teams that need to connect internal tools and data sources through MCP servers can use plugins with the same security and configuration protocols to speed up the process -* **Bundling customizations:** Framework authors or technical leads can package multiple customizations that work together for specific use cases - -### Plugin marketplaces - -To make it easier to share these customizations, anyone can build and host plugins and create plugin marketplaces—curated collections where other developers can discover and install plugins. - -You can use plugin marketplaces to share plugins with the community, distribute approved plugins across your organization, and build on existing solutions for common development challenges. - -To host a marketplace, all you need is a git repository, GitHub repository, or URL with a properly formatted `.claude-plugin/marketplace.json` file. See our documentation for details. - -To use plugins from a marketplace, run `/plugin marketplace add user-or-org/repo-name`, then browse and install plugins using the `/plugin` menu. - -### Discover new marketplaces - -Plugin marketplaces amplify the best practices our community has already developed, and community members are leading the way. For instance, engineer Dan Ávila's [plugin marketplace](https://www.aitmpl.com/plugins) offers plugins for DevOps automation, documentation generation, project management, and testing suites, while engineer Seth Hobson has curated over 80 specialized sub-agents in his [GitHub repository](https://github.com/wshobson/agents), giving developers instant access via plugins. - -You can also check out a few [example plugins](https://github.com/anthropics/claude-code) we've developed for PR reviews, security guidance, [Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) development, and even a meta-plugin for creating new plugins. - -### Getting started - -Plugins are now in public beta for all Claude Code users. Install them with the `/plugin` command and they'll work across your terminal and VS Code. - -Check out our documentation to [get started](https://docs.claude.com/en/docs/claude-code/plugins-reference), [build your own plugins](https://docs.claude.com/en/docs/claude-code/plugins), or [publish a marketplace](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces). To see plugins in action, try this multi-agent workflow we use to develop Claude Code: - -`/plugin marketplace add anthropics/claude-code` - -```javascript -/plugin marketplace add anthropics/claude-code -``` - -```javascript -/plugin install feature-dev -``` - -eBook - -[](#) - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg)![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -FAQ - -No items found. - -[](#) - -Get the developer newsletter - -Product updates, how-tos, community spotlights, and more. Delivered monthly to your inbox. - -[Subscribe](#)Subscribe - -Please provide your email address if you'd like to receive our monthly developer newsletter. You can unsubscribe at any time. - -Thank you! You’re subscribed. - -Sorry, there was a problem with your submission, please try again later. - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -Read more - -[Read more](#)Read more - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -[Next](#)Next - -Read more - -[Read more](#)Read more - -Read more - -[Read more](#)Read more - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -Read more - -[Read more](#)Read more - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -[Next](#)Next - -Read more - -[Read more](#)Read more - -Read more - -[Read more](#)Read more - -## Related articles - -Explore more insights on how Claude supports learning, research, and innovation across education. - -![](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6903d2307f9555d7c1bc46cb_77dd9077412abc790bf2bc6fa3383b37724d6305-1000x1000.svg) - -Oct 16, 2025 - -### Introducing Agent Skills - -Product announcements - -[Introducing Agent Skills](#)Introducing Agent Skills - -[Introducing Agent Skills](/blog/skills)Introducing Agent Skills - -![](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6903d2282403b092e0358c06_e2fc86543710551b106de115176c0506c7f7e442-1000x1000.svg) - -Jul 16, 2024 - -### Claude Android app - -Product announcements - -[Claude Android app](#)Claude Android app - -[Claude Android app](/blog/android-app)Claude Android app - -![](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6909386cc7ad3ed2a7ec8eed_Object-ThoughtBubble.svg) - -Sep 11, 2025 - -### Bringing memory to Claude - -Product announcements - -[Bringing memory to Claude](#)Bringing memory to Claude - -[Bringing memory to Claude](/blog/memory)Bringing memory to Claude - -![](https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6903d228e9c51800dde13958_6507d83d1197bb8630131d363fb8bea838d79ca7-1000x1000.svg) - -Sep 9, 2025 - -### Claude can now create and edit files - -Product announcements - -[Claude can now create and edit files](#)Claude can now create and edit files - -[Claude can now create and edit files](/blog/create-files)Claude can now create and edit files - -## Transform how your organization operates with Claude - -See pricing - -[See pricing](https://claude.com/pricing#api)See pricing - -Contact sales - -[Contact sales](https://claude.com/contact-sales)Contact sales - -Get the developer newsletter - -Product updates, how-tos, community spotlights, and more. Delivered monthly to your inbox. - -[Subscribe](#)Subscribe - -Please provide your email address if you'd like to receive our monthly developer newsletter. You can unsubscribe at any time. - -Thank you! You’re subscribed. - -Sorry, there was a problem with your submission, please try again later. - -[Homepage](/?r=0)Homepage - -[Next](#)Next - -Thank you! Your submission has been received! - -Oops! Something went wrong while submitting the form. - -Write - -[Button Text](#)Button Text - -Learn - -[Button Text](#)Button Text - -Code - -[Button Text](#)Button Text - -Write - -* Help me develop a unique voice for an audience - - [](#) - - Hi Claude! Could you help me develop a unique voice for an audience? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Improve my writing style - - [](#) - - Hi Claude! Could you improve my writing style? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Brainstorm creative ideas - - [](#) - - Hi Claude! Could you brainstorm creative ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - - -Learn - -* Explain a complex topic simply - - [](#) - - Hi Claude! Could you explain a complex topic simply? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Help me make sense of these ideas - - [](#) - - Hi Claude! Could you help me make sense of these ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Prepare for an exam or interview - - [](#) - - Hi Claude! Could you prepare for an exam or interview? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - - -Code - -* Explain a programming concept - - [](#) - - Hi Claude! Could you explain a programming concept? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Look over my code and give me tips - - [](#) - - Hi Claude! Could you look over my code and give me tips? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Vibe code with me - - [](#) - - Hi Claude! Could you vibe code with me? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - - -More - -* Write case studies - - [](#) - - This is another test - -* Write grant proposals - - [](#) - - Hi Claude! Could you write grant proposals? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to — like Google Drive, web search, etc. — if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. - - Please execute the task as soon as you can - an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! - -* Write video scripts - - [](#) - - this is a test - - -[Anthropic](https://www.anthropic.com/)Anthropic - -© 2025 Anthropic PBC - -Products - -* Claude - - [Claude](/product/overview)Claude - -* Claude Code - - [Claude Code](/product/claude-code)Claude Code - -* Max plan - - [Max plan](/pricing/max)Max plan - -* Team plan - - [Team plan](/pricing/team)Team plan - -* Enterprise plan - - [Enterprise plan](/pricing/enterprise)Enterprise plan - -* Download app - - [Download app](/download)Download app - -* Pricing - - [Pricing](/pricing)Pricing - -* Log in - - [Log in](https://claude.ai/redirect/claudedotcom.v1.fc414c21-3f81-4ba1-a0c5-8933dee86960/login)Log in - - -Features - -* Claude and Slack - - [Claude and Slack](/claude-and-slack)Claude and Slack - -* Claude in Excel - - [Claude in Excel](/claude-for-excel)Claude in Excel - - -Models - -* Opus - - [Opus](https://www.anthropic.com/claude/opus)Opus - -* Sonnet - - [Sonnet](https://www.anthropic.com/claude/sonnet)Sonnet - -* Haiku - - [Haiku](https://www.anthropic.com/claude/haiku)Haiku - - -Solutions - -* AI agents - - [AI agents](/solutions/agents)AI agents - -* Code modernization - - [Code modernization](/solutions/code-modernization)Code modernization - -* Coding - - [Coding](/solutions/coding)Coding - -* Customer support - - [Customer support](/solutions/customer-support)Customer support - -* Education - - [Education](/solutions/education)Education - -* Financial services - - [Financial services](/solutions/financial-services)Financial services - -* Government - - [Government](/solutions/government)Government - -* Life sciences - - [Life sciences](/solutions/life-sciences)Life sciences - - -Claude Developer Platform - -* Overview - - [Overview](/platform/api)Overview - -* Developer docs - - [Developer docs](https://docs.claude.com/)Developer docs - -* Pricing - - [Pricing](https://claude.com/pricing#api)Pricing - -* Amazon Bedrock - - [Amazon Bedrock](/partners/amazon-bedrock)Amazon Bedrock - -* Google Cloud’s Vertex AI - - [Google Cloud’s Vertex AI](/partners/google-cloud-vertex-ai)Google Cloud’s Vertex AI - -* Console login - - [Console login](https://console.anthropic.com/)Console login - - -Learn - -* Blog - - [Blog](/blog)Blog - -* Courses - - [Courses](https://www.anthropic.com/learn)Courses - -* Use cases - - [Use cases](/resources/use-cases)Use cases - -* Connectors - - [Connectors](/connectors)Connectors - -* Customer stories - - [Customer stories](/customers)Customer stories - -* Engineering at Anthropic - - [Engineering at Anthropic](https://www.anthropic.com/engineering)Engineering at Anthropic - -* Events - - [Events](https://www.anthropic.com/events)Events - -* Powered by Claude - - [Powered by Claude](/partners/powered-by-claude)Powered by Claude - -* Service partners - - [Service partners](/partners/services)Service partners - -* Startups program - - [Startups program](/programs/startups)Startups program - - -Company - -* Anthropic - - [Anthropic](https://www.anthropic.com/)Anthropic - -* Careers - - [Careers](https://www.anthropic.com/careers)Careers - -* Economic Futures - - [Economic Futures](https://www.anthropic.com/economic-futures)Economic Futures - -* Research - - [Research](https://www.anthropic.com/research)Research - -* News - - [News](https://www.anthropic.com/news)News - -* Responsible Scaling Policy - - [Responsible Scaling Policy](https://www.anthropic.com/news/announcing-our-updated-responsible-scaling-policy)Responsible Scaling Policy - -* Security and compliance - - [Security and compliance](https://trust.anthropic.com/)Security and compliance - -* Transparency - - [Transparency](https://anthropic.com/transparency)Transparency - - -Help and security - -* Availability - - [Availability](https://www.anthropic.com/supported-countries)Availability - -* Status - - [Status](https://status.anthropic.com/)Status - -* Support center - - [Support center](https://support.claude.com/en/)Support center - - -Terms and policies - -* Privacy choices - -* Privacy policy - - [Privacy policy](https://www.anthropic.com/legal/privacy)Privacy policy - -* Responsible disclosure policy - - [Responsible disclosure policy](https://www.anthropic.com/responsible-disclosure-policy)Responsible disclosure policy - -* Terms of service: Commercial - - [Terms of service: Commercial](https://www.anthropic.com/legal/commercial-terms)Terms of service: Commercial - -* Terms of service: Consumer - - [Terms of service: Consumer](https://www.anthropic.com/legal/consumer-terms)Terms of service: Consumer - -* Usage policy - - [Usage policy](https://www.anthropic.com/legal/aup)Usage policy - - -[x.com](https://x.com/claudeai)x.com - -[LinkedIn](https://www.linkedin.com/showcase/claude/)LinkedIn - -[YouTube](https://www.youtube.com/@anthropic-ai)YouTube - -[Instagram](https://www.instagram.com/claudeai)Instagram - -English (US) - -× - -[Next](#)Next - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -[Next](#)Next - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) - -[Next](#)Next - -![](https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/6889473610b50328dbb70b58_placeholder.svg) +> ## Documentation Index +> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt +> Use this file to discover all available pages before exploring further. # Plugins reference > Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications. - For hands-on tutorials and practical usage, see [Plugins](/en/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/plugin-marketplaces). + Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces). This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools. +A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers. + ## Plugin components reference -This section documents the five types of components that plugins can provide. +### Skills + +Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke. + +**Location**: `skills/` or `commands/` directory in plugin root -### Commands +**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files + +**Skill structure**: -Plugins add custom slash commands that integrate seamlessly with Claude Code's command system. +``` +skills/ +├── pdf-processor/ +│ ├── SKILL.md +│ ├── reference.md (optional) +│ └── scripts/ (optional) +└── code-reviewer/ + └── SKILL.md +``` -**Location**: `commands/` directory in plugin root +**Integration behavior**: -**File format**: Markdown files with frontmatter +* Skills and commands are automatically discovered when the plugin is installed +* Claude can invoke them automatically based on task context +* Skills can include supporting files alongside SKILL.md -For complete details on plugin command structure, invocation patterns, and features, see [Plugin commands](/en/slash-commands#plugin-commands). +For complete details, see [Skills](/en/skills). ### Agents @@ -749,21 +56,11 @@ Plugins can provide specialized subagents for specific tasks that Claude can inv ```markdown theme={null} --- -description: What this agent specializes in -capabilities: ["task1", "task2", "task3"] +name: agent-name +description: What this agent specializes in and when Claude should invoke it --- -# Agent Name - -Detailed description of the agent's role, expertise, and when Claude should invoke it. - -## Capabilities -- Specific task the agent excels at -- Another specialized capability -- When to use this agent vs others - -## Context and examples -Provide examples of when this agent should be used and what kinds of problems it solves. +Detailed system prompt for the agent describing its role, expertise, and behavior. ``` **Integration points**: @@ -773,36 +70,7 @@ Provide examples of when this agent should be used and what kinds of problems it * Agents can be invoked manually by users * Plugin agents work alongside built-in Claude agents -### Skills - -Plugins can provide Agent Skills that extend Claude's capabilities. Skills are model-invoked—Claude autonomously decides when to use them based on the task context. - -**Location**: `skills/` directory in plugin root - -**File format**: Directories containing `SKILL.md` files with frontmatter - -**Skill structure**: - -``` -skills/ -├── pdf-processor/ -│ ├── SKILL.md -│ ├── reference.md (optional) -│ └── scripts/ (optional) -└── code-reviewer/ - └── SKILL.md -``` - -**Integration behavior**: - -* Plugin Skills are automatically discovered when the plugin is installed -* Claude autonomously invokes Skills based on matching task context -* Skills can include supporting files alongside SKILL.md - -For SKILL.md format and complete Skill authoring guidance, see: - -* [Use Skills in Claude Code](/en/skills) -* [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview#skill-structure) +For complete details, see [Subagents](/en/sub-agents). ### Hooks @@ -835,20 +103,25 @@ Plugins can provide event handlers that respond to Claude Code events automatica **Available events**: * `PreToolUse`: Before Claude uses any tool -* `PostToolUse`: After Claude uses any tool +* `PostToolUse`: After Claude successfully uses any tool +* `PostToolUseFailure`: After Claude tool execution fails +* `PermissionRequest`: When a permission dialog is shown * `UserPromptSubmit`: When user submits a prompt * `Notification`: When Claude Code sends notifications * `Stop`: When Claude attempts to stop +* `SubagentStart`: When a subagent is started * `SubagentStop`: When a subagent attempts to stop * `SessionStart`: At the beginning of sessions * `SessionEnd`: At the end of sessions +* `TeammateIdle`: When an agent team teammate is about to go idle +* `TaskCompleted`: When a task is being marked as completed * `PreCompact`: Before conversation history is compacted **Hook types**: * `command`: Execute shell commands or scripts -* `validation`: Validate file contents or project state -* `notification`: Send alerts or status updates +* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context) +* `agent`: Run an agentic verifier with tools for complex verification tasks ### MCP servers @@ -886,11 +159,113 @@ Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code w * Server capabilities integrate seamlessly with Claude's existing tools * Plugin servers can be configured independently of user MCP servers +### LSP servers + + + Looking to use LSP plugins? Install them from the official marketplace: search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace. + + +Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase. + +LSP integration provides: + +* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit +* **Code navigation**: go to definition, find references, and hover information +* **Language awareness**: type information and documentation for code symbols + +**Location**: `.lsp.json` in plugin root, or inline in `plugin.json` + +**Format**: JSON configuration mapping language server names to their configurations + +**`.lsp.json` file format**: + +```json theme={null} +{ + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } +} +``` + +**Inline in `plugin.json`**: + +```json theme={null} +{ + "name": "my-plugin", + "lspServers": { + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } + } +} +``` + +**Required fields:** + +| Field | Description | +| :-------------------- | :------------------------------------------- | +| `command` | The LSP binary to execute (must be in PATH) | +| `extensionToLanguage` | Maps file extensions to language identifiers | + +**Optional fields:** + +| Field | Description | +| :---------------------- | :-------------------------------------------------------- | +| `args` | Command-line arguments for the LSP server | +| `transport` | Communication transport: `stdio` (default) or `socket` | +| `env` | Environment variables to set when starting the server | +| `initializationOptions` | Options passed to the server during initialization | +| `settings` | Settings passed via `workspace/didChangeConfiguration` | +| `workspaceFolder` | Workspace folder path for the server | +| `startupTimeout` | Max time to wait for server startup (milliseconds) | +| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) | +| `restartOnCrash` | Whether to automatically restart the server if it crashes | +| `maxRestarts` | Maximum number of restart attempts before giving up | + + + **You must install the language server binary separately.** LSP plugins configure how Claude Code connects to a language server, but they don't include the server itself. If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary for your language. + + +**Available LSP plugins:** + +| Plugin | Language server | Install command | +| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- | +| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` | +| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` | +| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) | + +Install the language server first, then install the plugin from the marketplace. + +*** + +## Plugin installation scopes + +When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it: + +| Scope | Settings file | Use case | +| :-------- | :---------------------------- | :------------------------------------------------------- | +| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) | +| `project` | `.claude/settings.json` | Team plugins shared via version control | +| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored | +| `managed` | `managed-settings.json` | Managed plugins (read-only, update only) | + +Plugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/en/settings#configuration-scopes). + *** ## Plugin manifest schema -The `plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options. +The `.claude-plugin/plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options. + +The manifest is optional. If omitted, Claude Code auto-discovers components in [default locations](#file-locations-reference) and derives the plugin name from the directory name. Use a manifest when you need to provide metadata or custom component paths. ### Complete schema @@ -910,37 +285,49 @@ The `plugin.json` file defines your plugin's metadata and configuration. This se "keywords": ["keyword1", "keyword2"], "commands": ["./custom/commands/special.md"], "agents": "./custom/agents/", + "skills": "./custom/skills/", "hooks": "./config/hooks.json", - "mcpServers": "./mcp-config.json" + "mcpServers": "./mcp-config.json", + "outputStyles": "./styles/", + "lspServers": "./.lsp.json" } ``` ### Required fields +If you include a manifest, `name` is the only required field. + | Field | Type | Description | Example | | :----- | :----- | :---------------------------------------- | :------------------- | | `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` | +This name is used for namespacing components. For example, in the UI, the +agent `agent-creator` for the plugin with name `plugin-dev` will appear as +`plugin-dev:agent-creator`. + ### Metadata fields -| Field | Type | Description | Example | -| :------------ | :----- | :---------------------------------- | :------------------------------------------------- | -| `version` | string | Semantic version | `"2.1.0"` | -| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` | -| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` | -| `homepage` | string | Documentation URL | `"https://docs.example.com"` | -| `repository` | string | Source code URL | `"https://github.com/user/plugin"` | -| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` | -| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` | +| Field | Type | Description | Example | +| :------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- | +| `version` | string | Semantic version. If also set in the marketplace entry, `plugin.json` takes priority. You only need to set it in one place. | `"2.1.0"` | +| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` | +| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` | +| `homepage` | string | Documentation URL | `"https://docs.example.com"` | +| `repository` | string | Source code URL | `"https://github.com/user/plugin"` | +| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` | +| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` | ### Component path fields -| Field | Type | Description | Example | -| :----------- | :------------- | :----------------------------------- | :------------------------------------- | -| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` | -| `agents` | string\|array | Additional agent files | `"./custom/agents/"` | -| `hooks` | string\|object | Hook config path or inline config | `"./hooks.json"` | -| `mcpServers` | string\|object | MCP config path or inline config | `"./mcp.json"` | +| Field | Type | Description | Example | +| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- | +| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` | +| `agents` | string\|array | Additional agent files | `"./custom/agents/reviewer.md"` | +| `skills` | string\|array | Additional skill directories | `"./custom/skills/"` | +| `hooks` | string\|array\|object | Hook config paths or inline config | `"./my-extra-hooks.json"` | +| `mcpServers` | string\|array\|object | MCP config paths or inline config | `"./my-extra-mcp-config.json"` | +| `outputStyles` | string\|array | Additional output style files/directories | `"./styles/"` | +| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configs for code intelligence (go to definition, find references, etc.) | `"./.lsp.json"` | ### Path behavior rules @@ -989,19 +376,45 @@ The `plugin.json` file defines your plugin's metadata and configuration. This se *** -## Plugin directory structure +## Plugin caching and file resolution -### Standard plugin layout +Plugins are specified in one of two ways: -A complete plugin follows this structure: +* Through `claude --plugin-dir`, for the duration of a session. +* Through a marketplace, installed for future sessions. +For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files. + +### Path traversal limitations + +Installed plugins cannot reference files outside their directory. Paths that traverse outside the plugin root (such as `../shared-utils`) will not work after installation because those external files are not copied to the cache. + +### Working with external dependencies + +If your plugin needs to access files outside its directory, you can create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process: + +```bash theme={null} +# Inside your plugin directory +ln -s /path/to/shared-utils ./shared-utils ``` -enterprise-plugin/ -├── .claude-plugin/ # Metadata directory -│ └── plugin.json # Required: plugin manifest -├── commands/ # Default command location + +The symlinked content will be copied into the plugin cache. This provides flexibility while maintaining the security benefits of the caching system. + +*** + +## Plugin directory structure + +### Standard plugin layout + +A complete plugin follows this structure: + +``` +enterprise-plugin/ +├── .claude-plugin/ # Metadata directory (optional) +│ └── plugin.json # plugin manifest +├── commands/ # Default command location │ ├── status.md -│ └── logs.md +│ └── logs.md ├── agents/ # Default agent location │ ├── security-reviewer.md │ ├── performance-tester.md @@ -1016,6 +429,7 @@ enterprise-plugin/ │ ├── hooks.json # Main hook config │ └── security-hooks.json # Additional hooks ├── .mcp.json # MCP server definitions +├── .lsp.json # LSP server configurations ├── scripts/ # Hook and utility scripts │ ├── security-scan.sh │ ├── format-code.py @@ -1030,887 +444,269 @@ enterprise-plugin/ ### File locations reference -| Component | Default Location | Purpose | -| :-------------- | :--------------------------- | :------------------------------- | -| **Manifest** | `.claude-plugin/plugin.json` | Required metadata file | -| **Commands** | `commands/` | Slash command markdown files | -| **Agents** | `agents/` | Subagent markdown files | -| **Skills** | `skills/` | Agent Skills with SKILL.md files | -| **Hooks** | `hooks/hooks.json` | Hook configuration | -| **MCP servers** | `.mcp.json` | MCP server definitions | +| Component | Default Location | Purpose | +| :-------------- | :--------------------------- | :---------------------------------------------------------- | +| **Manifest** | `.claude-plugin/plugin.json` | Plugin metadata and configuration (optional) | +| **Commands** | `commands/` | Skill Markdown files (legacy; use `skills/` for new skills) | +| **Agents** | `agents/` | Subagent Markdown files | +| **Skills** | `skills/` | Skills with `/SKILL.md` structure | +| **Hooks** | `hooks/hooks.json` | Hook configuration | +| **MCP servers** | `.mcp.json` | MCP server definitions | +| **LSP servers** | `.lsp.json` | Language server configurations | *** -## Debugging and development tools +## CLI commands reference -### Debugging commands +Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation. + +### plugin install -Use `claude --debug` to see plugin loading details: +Install a plugin from available marketplaces. ```bash theme={null} -claude --debug +claude plugin install [options] ``` -This shows: - -* Which plugins are being loaded -* Any errors in plugin manifests -* Command, agent, and hook registration -* MCP server initialization +**Arguments:** -### Common issues +* ``: Plugin name or `plugin-name@marketplace-name` for a specific marketplace -| Issue | Cause | Solution | -| :--------------------- | :------------------------------ | :--------------------------------------------------- | -| Plugin not loading | Invalid `plugin.json` | Validate JSON syntax | -| Commands not appearing | Wrong directory structure | Ensure `commands/` at root, not in `.claude-plugin/` | -| Hooks not firing | Script not executable | Run `chmod +x script.sh` | -| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths | -| Path errors | Absolute paths used | All paths must be relative and start with `./` | +**Options:** -*** - -## Distribution and versioning reference +| Option | Description | Default | +| :-------------------- | :------------------------------------------------ | :------ | +| `-s, --scope ` | Installation scope: `user`, `project`, or `local` | `user` | +| `-h, --help` | Display help for command | | -### Version management +Scope determines which settings file the installed plugin is added to. For example, --scope project writes to `enabledPlugins` in .claude/settings.json, making the plugin available to everyone who clones the project repository. -Follow semantic versioning for plugin releases: +**Examples:** -```json theme={null} +```bash theme={null} +# Install to user scope (default) +claude plugin install formatter@my-marketplace -## See also +# Install to project scope (shared with team) +claude plugin install formatter@my-marketplace --scope project -- [Plugins](/en/plugins) - Tutorials and practical usage -- [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces -- [Slash commands](/en/slash-commands) - Command development details -- [Subagents](/en/sub-agents) - Agent configuration and capabilities -- [Agent Skills](/en/skills) - Extend Claude's capabilities -- [Hooks](/en/hooks) - Event handling and automation -- [MCP](/en/mcp) - External tool integration -- [Settings](/en/settings) - Configuration options for plugins +# Install to local scope (gitignored) +claude plugin install formatter@my-marketplace --scope local ``` -# Plugins - -> Extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system. - - - For complete technical specifications and schemas, see [Plugins reference](/en/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/plugin-marketplaces). - - -Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Install plugins from [marketplaces](/en/plugin-marketplaces) to add pre-built commands, agents, hooks, Skills, and MCP servers, or create your own to automate your workflows. -## Quickstart +### plugin uninstall -Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts. +Remove an installed plugin. -### Prerequisites - -* Claude Code installed on your machine -* Basic familiarity with command-line tools - -### Create your first plugin - - - - ```bash theme={null} - mkdir test-marketplace - cd test-marketplace - ``` - - - - ```bash theme={null} - mkdir my-first-plugin - cd my-first-plugin - ``` - - - - ```bash Create .claude-plugin/plugin.json theme={null} - mkdir .claude-plugin - cat > .claude-plugin/plugin.json << 'EOF' - { - "name": "my-first-plugin", - "description": "A simple greeting plugin to learn the basics", - "version": "1.0.0", - "author": { - "name": "Your Name" - } - } - EOF - ``` - - - - ```bash Create commands/hello.md theme={null} - mkdir commands - cat > commands/hello.md << 'EOF' - --- - description: Greet the user with a personalized message - --- - - # Hello Command - - Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging. - EOF - ``` - - - - ```bash Create marketplace.json theme={null} - cd .. - mkdir .claude-plugin - cat > .claude-plugin/marketplace.json << 'EOF' - { - "name": "test-marketplace", - "owner": { - "name": "Test User" - }, - "plugins": [ - { - "name": "my-first-plugin", - "source": "./my-first-plugin", - "description": "My first test plugin" - } - ] - } - EOF - ``` - - - - ```bash Start Claude Code from parent directory theme={null} - cd .. - claude - ``` - - ```shell Add the test marketplace theme={null} - /plugin marketplace add ./test-marketplace - ``` - - ```shell Install your plugin theme={null} - /plugin install my-first-plugin@test-marketplace - ``` - - Select "Install now". You'll then need to restart Claude Code in order to use the new plugin. - - ```shell Try your new command theme={null} - /hello - ``` - - You'll see Claude use your greeting command! Check `/help` to see your new command listed. - - - -You've successfully created and tested a plugin with these key components: - -* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata -* **Commands directory** (`commands/`) - Contains your custom slash commands -* **Test marketplace** - Allows you to test your plugin locally - -### Plugin structure overview - -Your plugin follows this basic structure: - -``` -my-first-plugin/ -├── .claude-plugin/ -│ └── plugin.json # Plugin metadata -├── commands/ # Custom slash commands (optional) -│ └── hello.md -├── agents/ # Custom agents (optional) -│ └── helper.md -├── skills/ # Agent Skills (optional) -│ └── my-skill/ -│ └── SKILL.md -└── hooks/ # Event handlers (optional) - └── hooks.json +```bash theme={null} +claude plugin uninstall [options] ``` -**Additional components you can add:** +**Arguments:** -* **Commands**: Create markdown files in `commands/` directory -* **Agents**: Create agent definitions in `agents/` directory -* **Skills**: Create `SKILL.md` files in `skills/` directory -* **Hooks**: Create `hooks/hooks.json` for event handling -* **MCP servers**: Create `.mcp.json` for external tool integration +* ``: Plugin name or `plugin-name@marketplace-name` - - **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, and MCP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference). - - -*** +**Options:** -## Install and manage plugins +| Option | Description | Default | +| :-------------------- | :-------------------------------------------------- | :------ | +| `-s, --scope ` | Uninstall from scope: `user`, `project`, or `local` | `user` | +| `-h, --help` | Display help for command | | -Learn how to discover, install, and manage plugins to extend your Claude Code capabilities. +**Aliases:** `remove`, `rm` -### Prerequisites +### plugin enable -* Claude Code installed and running -* Basic familiarity with command-line interfaces +Enable a disabled plugin. -### Add marketplaces - -Marketplaces are catalogs of available plugins. Add them to discover and install plugins: - -```shell Add a marketplace theme={null} -/plugin marketplace add your-org/claude-plugins -``` - -```shell Browse available plugins theme={null} -/plugin +```bash theme={null} +claude plugin enable [options] ``` -For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/plugin-marketplaces). - -### Install plugins +**Arguments:** -#### Via interactive menu (recommended for discovery) +* ``: Plugin name or `plugin-name@marketplace-name` -```shell Open the plugin management interface theme={null} -/plugin -``` +**Options:** -Select "Browse Plugins" to see available options with descriptions, features, and installation options. +| Option | Description | Default | +| :-------------------- | :--------------------------------------------- | :------ | +| `-s, --scope ` | Scope to enable: `user`, `project`, or `local` | `user` | +| `-h, --help` | Display help for command | | -#### Via direct commands (for quick installation) +### plugin disable -```shell Install a specific plugin theme={null} -/plugin install formatter@your-org -``` +Disable a plugin without uninstalling it. -```shell Enable a disabled plugin theme={null} -/plugin enable plugin-name@marketplace-name -``` - -```shell Disable without uninstalling theme={null} -/plugin disable plugin-name@marketplace-name -``` - -```shell Completely remove a plugin theme={null} -/plugin uninstall plugin-name@marketplace-name +```bash theme={null} +claude plugin disable [options] ``` -### Verify installation - -After installing a plugin: - -1. **Check available commands**: Run `/help` to see new commands -2. **Test plugin features**: Try the plugin's commands and features -3. **Review plugin details**: Use `/plugin` → "Manage Plugins" to see what the plugin provides - -## Set up team plugin workflows - -Configure plugins at the repository level to ensure consistent tooling across your team. When team members trust your repository folder, Claude Code automatically installs specified marketplaces and plugins. - -**To set up team plugins:** - -1. Add marketplace and plugin configuration to your repository's `.claude/settings.json` -2. Team members trust the repository folder -3. Plugins install automatically for all team members - -For complete instructions including configuration examples, marketplace setup, and rollout best practices, see [Configure team marketplaces](/en/plugin-marketplaces#how-to-configure-team-marketplaces). - -*** - -## Develop more complex plugins - -Once you're comfortable with basic plugins, you can create more sophisticated extensions. - -### Add Skills to your plugin - -Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context. - -To add Skills to your plugin, create a `skills/` directory at your plugin root and add Skill folders with `SKILL.md` files. Plugin Skills are automatically available when the plugin is installed. - -For complete Skill authoring guidance, see [Agent Skills](/en/skills). - -### Organize complex plugins - -For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure). - -### Test your plugins locally - -When developing plugins, use a local marketplace to test changes iteratively. This workflow builds on the quickstart pattern and works for plugins of any complexity. - - - - Organize your plugin and marketplace for testing: - - ```bash Create directory structure theme={null} - mkdir dev-marketplace - cd dev-marketplace - mkdir my-plugin - ``` - - This creates: - - ``` - dev-marketplace/ - ├── .claude-plugin/marketplace.json (you'll create this) - └── my-plugin/ (your plugin under development) - ├── .claude-plugin/plugin.json - ├── commands/ - ├── agents/ - └── hooks/ - ``` - - - - ```bash Create marketplace.json theme={null} - mkdir .claude-plugin - cat > .claude-plugin/marketplace.json << 'EOF' - { - "name": "dev-marketplace", - "owner": { - "name": "Developer" - }, - "plugins": [ - { - "name": "my-plugin", - "source": "./my-plugin", - "description": "Plugin under development" - } - ] - } - EOF - ``` - - - - ```bash Start Claude Code from parent directory theme={null} - cd .. - claude - ``` - - ```shell Add your development marketplace theme={null} - /plugin marketplace add ./dev-marketplace - ``` +**Arguments:** - ```shell Install your plugin theme={null} - /plugin install my-plugin@dev-marketplace - ``` +* ``: Plugin name or `plugin-name@marketplace-name` - Test your plugin components: +**Options:** - * Try your commands with `/command-name` - * Check that agents appear in `/agents` - * Verify hooks work as expected - +| Option | Description | Default | +| :-------------------- | :---------------------------------------------- | :------ | +| `-s, --scope ` | Scope to disable: `user`, `project`, or `local` | `user` | +| `-h, --help` | Display help for command | | - - After making changes to your plugin code: +### plugin update - ```shell Uninstall the current version theme={null} - /plugin uninstall my-plugin@dev-marketplace - ``` +Update a plugin to the latest version. - ```shell Reinstall to test changes theme={null} - /plugin install my-plugin@dev-marketplace - ``` - - Repeat this cycle as you develop and refine your plugin. - - - - - **For multiple plugins**: Organize plugins in subdirectories like `./plugins/plugin-name` and update your marketplace.json accordingly. See [Plugin sources](/en/plugin-marketplaces#plugin-sources) for organization patterns. - - -### Debug plugin issues - -If your plugin isn't working as expected: - -1. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/` -2. **Test components individually**: Check each command, agent, and hook separately -3. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques +```bash theme={null} +claude plugin update [options] +``` -### Share your plugins +**Arguments:** -When your plugin is ready to share: +* ``: Plugin name or `plugin-name@marketplace-name` -1. **Add documentation**: Include a README.md with installation and usage instructions -2. **Version your plugin**: Use semantic versioning in your `plugin.json` -3. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation -4. **Test with others**: Have team members test the plugin before wider distribution +**Options:** - - For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference). - +| Option | Description | Default | +| :-------------------- | :-------------------------------------------------------- | :------ | +| `-s, --scope ` | Scope to update: `user`, `project`, `local`, or `managed` | `user` | +| `-h, --help` | Display help for command | | *** -## Next steps - -Now that you understand Claude Code's plugin system, here are suggested paths for different goals: - -### For plugin users - -* **Discover plugins**: Browse community marketplaces for useful tools -* **Team adoption**: Set up repository-level plugins for your projects -* **Marketplace management**: Learn to manage multiple plugin sources -* **Advanced usage**: Explore plugin combinations and workflows - -### For plugin developers - -* **Create your first marketplace**: [Plugin marketplaces guide](/en/plugin-marketplaces) -* **Advanced components**: Dive deeper into specific plugin components: - * [Slash commands](/en/slash-commands) - Command development details - * [Subagents](/en/sub-agents) - Agent configuration and capabilities - * [Agent Skills](/en/skills) - Extend Claude's capabilities - * [Hooks](/en/hooks) - Event handling and automation - * [MCP](/en/mcp) - External tool integration -* **Distribution strategies**: Package and share your plugins effectively -* **Community contribution**: Consider contributing to community plugin collections +## Debugging and development tools -### For team leads and administrators +### Debugging commands -* **Repository configuration**: Set up automatic plugin installation for team projects -* **Plugin governance**: Establish guidelines for plugin approval and security review -* **Marketplace maintenance**: Create and maintain organization-specific plugin catalogs -* **Training and documentation**: Help team members adopt plugin workflows effectively +Use `claude --debug` (or `/debug` within the TUI) to see plugin loading details: -## See also +This shows: -* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing plugin catalogs -* [Slash commands](/en/slash-commands) - Understanding custom commands -* [Subagents](/en/sub-agents) - Creating and using specialized agents -* [Agent Skills](/en/skills) - Extend Claude's capabilities -* [Hooks](/en/hooks) - Automating workflows with event handlers -* [MCP](/en/mcp) - Connecting to external tools and services -* [Settings](/en/settings) - Configuration options for plugins +* Which plugins are being loaded +* Any errors in plugin manifests +* Command, agent, and hook registration +* MCP server initialization -# Plugin marketplaces +### Common issues -> Create and manage plugin marketplaces to distribute Claude Code extensions across teams and communities. +| Issue | Cause | Solution | +| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- | +| Plugin not loading | Invalid `plugin.json` | Validate JSON syntax with `claude plugin validate` or `/plugin validate` | +| Commands not appearing | Wrong directory structure | Ensure `commands/` at root, not in `.claude-plugin/` | +| Hooks not firing | Script not executable | Run `chmod +x script.sh` | +| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths | +| Path errors | Absolute paths used | All paths must be relative and start with `./` | +| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) | -Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution. +### Example error messages -## Overview +**Manifest validation errors**: -A marketplace is a JSON file that lists available plugins and describes where to find them. Marketplaces provide: +* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings +* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing +* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error -* **Centralized discovery**: Browse plugins from multiple sources in one place -* **Version management**: Track and update plugin versions automatically -* **Team distribution**: Share required plugins across your organization -* **Flexible sources**: Support for git repositories, GitHub repos, local paths, and package managers +**Plugin loading errors**: -### Prerequisites +* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files +* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory +* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or remove `strict: false` in marketplace entry -* Claude Code installed and running -* Basic familiarity with JSON file format -* For creating marketplaces: Git repository or local development environment +### Hook troubleshooting -## Add and use marketplaces +**Hook script not executing**: -Add marketplaces using the `/plugin marketplace` commands to access plugins from different sources: +1. Check the script is executable: `chmod +x ./scripts/your-script.sh` +2. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash` +3. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"` +4. Test the script manually: `./scripts/your-script.sh` -### Add GitHub marketplaces +**Hook not triggering on expected events**: -```shell Add a GitHub repository containing .claude-plugin/marketplace.json theme={null} -/plugin marketplace add owner/repo -``` +1. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse` +2. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations +3. Confirm the hook type is valid: `command`, `prompt`, or `agent` -### Add Git repositories +### MCP server troubleshooting -```shell Add any git repository theme={null} -/plugin marketplace add https://gitlab.com/company/plugins.git -``` +**Server not starting**: -### Add local marketplaces for development +1. Check the command exists and is executable +2. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable +3. Check the MCP server logs: `claude --debug` shows initialization errors +4. Test the server manually outside of Claude Code -```shell Add local directory containing .claude-plugin/marketplace.json theme={null} -/plugin marketplace add ./my-marketplace -``` +**Server tools not appearing**: -```shell Add direct path to marketplace.json file theme={null} -/plugin marketplace add ./path/to/marketplace.json -``` +1. Ensure the server is properly configured in `.mcp.json` or `plugin.json` +2. Verify the server implements the MCP protocol correctly +3. Check for connection timeouts in debug output -```shell Add remote marketplace.json via URL theme={null} -/plugin marketplace add https://url.of/marketplace.json -``` +### Directory structure mistakes -### Install plugins from marketplaces +**Symptoms**: Plugin loads but components (commands, agents, hooks) are missing. -Once you've added marketplaces, install plugins directly: +**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`. -```shell Install from any known marketplace theme={null} -/plugin install plugin-name@marketplace-name ``` - -```shell Browse available plugins interactively theme={null} -/plugin +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json ← Only manifest here +├── commands/ ← At root level +├── agents/ ← At root level +└── hooks/ ← At root level ``` -### Verify marketplace installation - -After adding a marketplace: - -1. **List marketplaces**: Run `/plugin marketplace list` to confirm it's added -2. **Browse plugins**: Use `/plugin` to see available plugins from your marketplace -3. **Test installation**: Try installing a plugin to verify the marketplace works correctly +If your components are inside `.claude-plugin/`, move them to the plugin root. -## Configure team marketplaces - -Set up automatic marketplace installation for team projects by specifying required marketplaces in `.claude/settings.json`: - -```json theme={null} -{ - "extraKnownMarketplaces": { - "team-tools": { - "source": { - "source": "github", - "repo": "your-org/claude-plugins" - } - }, - "project-specific": { - "source": { - "source": "git", - "url": "https://git.company.com/project-plugins.git" - } - } - } -} -``` +**Debug checklist**: -When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field. +1. Run `claude --debug` and look for "loading plugin" messages +2. Check that each component directory is listed in the debug output +3. Verify file permissions allow reading the plugin files *** -## Create your own marketplace - -Build and distribute custom plugin collections for your team or community. - -### Prerequisites for marketplace creation - -* Git repository (GitHub, GitLab, or other git hosting) -* Understanding of JSON file format -* One or more plugins to distribute - -### Create the marketplace file - -Create `.claude-plugin/marketplace.json` in your repository root: - -```json theme={null} -{ - "name": "company-tools", - "owner": { - "name": "DevTools Team", - "email": "devtools@company.com" - }, - "plugins": [ - { - "name": "code-formatter", - "source": "./plugins/formatter", - "description": "Automatic code formatting on save", - "version": "2.1.0", - "author": { - "name": "DevTools Team" - } - }, - { - "name": "deployment-tools", - "source": { - "source": "github", - "repo": "company/deploy-plugin" - }, - "description": "Deployment automation tools" - } - ] -} -``` - -### Marketplace schema - -#### Required fields - -| Field | Type | Description | -| :-------- | :----- | :--------------------------------------------- | -| `name` | string | Marketplace identifier (kebab-case, no spaces) | -| `owner` | object | Marketplace maintainer information | -| `plugins` | array | List of available plugins | - -#### Optional metadata - -| Field | Type | Description | -| :--------------------- | :----- | :------------------------------------ | -| `metadata.description` | string | Brief marketplace description | -| `metadata.version` | string | Marketplace version | -| `metadata.pluginRoot` | string | Base path for relative plugin sources | - -### Plugin entries - - - Plugin entries are based on the *plugin manifest schema* (with all fields made optional) plus marketplace-specific fields (`source`, `category`, `tags`, `strict`), with `name` being required. - - -**Required fields:** - -| Field | Type | Description | -| :------- | :------------- | :---------------------------------------- | -| `name` | string | Plugin identifier (kebab-case, no spaces) | -| `source` | string\|object | Where to fetch the plugin from | - -#### Optional plugin fields - -**Standard metadata fields:** - -| Field | Type | Description | -| :------------ | :------ | :---------------------------------------------------------------- | -| `description` | string | Brief plugin description | -| `version` | string | Plugin version | -| `author` | object | Plugin author information | -| `homepage` | string | Plugin homepage or documentation URL | -| `repository` | string | Source code repository URL | -| `license` | string | SPDX license identifier (e.g., MIT, Apache-2.0) | -| `keywords` | array | Tags for plugin discovery and categorization | -| `category` | string | Plugin category for organization | -| `tags` | array | Tags for searchability | -| `strict` | boolean | Require plugin.json in plugin folder (default: true) 1 | - -**Component configuration fields:** - -| Field | Type | Description | -| :----------- | :------------- | :----------------------------------------------- | -| `commands` | string\|array | Custom paths to command files or directories | -| `agents` | string\|array | Custom paths to agent files | -| `hooks` | string\|object | Custom hooks configuration or path to hooks file | -| `mcpServers` | string\|object | MCP server configurations or path to MCP config | - -*1 - When `strict: true` (default), the plugin must include a `plugin.json` manifest file, and marketplace fields supplement those values. When `strict: false`, the plugin.json is optional. If it's missing, the marketplace entry serves as the complete plugin manifest.* - -### Plugin sources +## Distribution and versioning reference -#### Relative paths +### Version management -For plugins in the same repository: +Follow semantic versioning for plugin releases: ```json theme={null} { "name": "my-plugin", - "source": "./plugins/my-plugin" -} -``` - -#### GitHub repositories - -```json theme={null} -{ - "name": "github-plugin", - "source": { - "source": "github", - "repo": "owner/plugin-repo" - } + "version": "2.1.0" } ``` -#### Git repositories +**Version format**: `MAJOR.MINOR.PATCH` -```json theme={null} -{ - "name": "git-plugin", - "source": { - "source": "url", - "url": "https://gitlab.com/team/plugin.git" - } -} -``` +* **MAJOR**: Breaking changes (incompatible API changes) +* **MINOR**: New features (backward-compatible additions) +* **PATCH**: Bug fixes (backward-compatible fixes) -#### Advanced plugin entries +**Best practices**: -Plugin entries can override default component locations and provide additional metadata. Note that `${CLAUDE_PLUGIN_ROOT}` is an environment variable that resolves to the plugin's installation directory (for details see [Environment variables](/en/plugins-reference#environment-variables)): - -```json theme={null} -{ - "name": "enterprise-tools", - "source": { - "source": "github", - "repo": "company/enterprise-plugin" - }, - "description": "Enterprise workflow automation tools", - "version": "2.1.0", - "author": { - "name": "Enterprise Team", - "email": "enterprise@company.com" - }, - "homepage": "https://docs.company.com/plugins/enterprise-tools", - "repository": "https://github.com/company/enterprise-plugin", - "license": "MIT", - "keywords": ["enterprise", "workflow", "automation"], - "category": "productivity", - "commands": [ - "./commands/core/", - "./commands/enterprise/", - "./commands/experimental/preview.md" - ], - "agents": [ - "./agents/security-reviewer.md", - "./agents/compliance-checker.md" - ], - "hooks": { - "PostToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"}] - } - ] - }, - "mcpServers": { - "enterprise-db": { - "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", - "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"] - } - }, - "strict": false -} -``` - - - **Schema relationship**: Plugin entries use the plugin manifest schema with all fields made optional, plus marketplace-specific fields (`source`, `strict`, `category`, `tags`). This means any field valid in a `plugin.json` file can also be used in a marketplace entry. When `strict: false`, the marketplace entry serves as the complete plugin manifest if no `plugin.json` exists. When `strict: true` (default), marketplace fields supplement the plugin's own manifest file. - - -*** - -## Host and distribute marketplaces - -Choose the best hosting strategy for your plugin distribution needs. - -### Host on GitHub (recommended) - -GitHub provides the easiest distribution method: - -1. **Create a repository**: Set up a new repository for your marketplace -2. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions -3. **Share with teams**: Team members add with `/plugin marketplace add owner/repo` - -**Benefits**: Built-in version control, issue tracking, and team collaboration features. - -### Host on other git services - -Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository. - -For example, using GitLab: - -```shell theme={null} -/plugin marketplace add https://gitlab.com/company/plugins.git -``` - -### Use local marketplaces for development - -Test your marketplace locally before distribution: - -```shell Add local marketplace for testing theme={null} -/plugin marketplace add ./my-local-marketplace -``` - -```shell Test plugin installation theme={null} -/plugin install test-plugin@my-local-marketplace -``` - -## Manage marketplace operations - -### List known marketplaces - -```shell List all configured marketplaces theme={null} -/plugin marketplace list -``` - -Shows all configured marketplaces with their sources and status. - -### Update marketplace metadata - -```shell Refresh marketplace metadata theme={null} -/plugin marketplace update marketplace-name -``` - -Refreshes plugin listings and metadata from the marketplace source. - -### Remove a marketplace - -```shell Remove a marketplace theme={null} -/plugin marketplace remove marketplace-name -``` - -Removes the marketplace from your configuration. +* Start at `1.0.0` for your first stable release +* Update the version in `plugin.json` before distributing changes +* Document changes in a `CHANGELOG.md` file +* Use pre-release versions like `2.0.0-beta.1` for testing - Removing a marketplace will uninstall any plugins you installed from it. - - -*** - -## Troubleshooting marketplaces - -### Common marketplace issues - -#### Marketplace not loading - -**Symptoms**: Can't add marketplace or see plugins from it - -**Solutions**: - -* Verify the marketplace URL is accessible -* Check that `.claude-plugin/marketplace.json` exists at the specified path -* Ensure JSON syntax is valid using `claude plugin validate` -* For private repositories, confirm you have access permissions - -#### Plugin installation failures - -**Symptoms**: Marketplace appears but plugin installation fails - -**Solutions**: - -* Verify plugin source URLs are accessible -* Check that plugin directories contain required files -* For GitHub sources, ensure repositories are public or you have access -* Test plugin sources manually by cloning/downloading + Claude Code uses the version to determine whether to update your plugin. If you change your plugin's code but don't bump the version in `plugin.json`, your plugin's existing users won't see your changes due to caching. -### Validation and testing - -Test your marketplace before sharing: - -```bash Validate marketplace JSON syntax theme={null} -claude plugin validate . -``` - -```shell Add marketplace for testing theme={null} -/plugin marketplace add ./path/to/marketplace -``` - -```shell Install test plugin theme={null} -/plugin install test-plugin@marketplace-name -``` - -For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference). + If your plugin is within a [marketplace](/en/plugin-marketplaces) directory, you can manage the version through `marketplace.json` instead and omit the `version` field from `plugin.json`. + *** -## Next steps - -### For marketplace users - -* **Discover community marketplaces**: Search GitHub for Claude Code plugin collections -* **Contribute feedback**: Report issues and suggest improvements to marketplace maintainers -* **Share useful marketplaces**: Help your team discover valuable plugin collections - -### For marketplace creators - -* **Build plugin collections**: Create themed marketplace around specific use cases -* **Establish versioning**: Implement clear versioning and update policies -* **Community engagement**: Gather feedback and maintain active marketplace communities -* **Documentation**: Provide clear README files explaining your marketplace contents - -### For organizations - -* **Private marketplaces**: Set up internal marketplaces for proprietary tools -* **Governance policies**: Establish guidelines for plugin approval and security review -* **Training resources**: Help teams discover and adopt useful plugins effectively - ## See also -* [Plugins](/en/plugins) - Installing and using plugins -* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas -* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins -* [Settings](/en/settings#plugin-configuration) - Plugin configuration options +* [Plugins](/en/plugins) - Tutorials and practical usage +* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces +* [Skills](/en/skills) - Skill development details +* [Subagents](/en/sub-agents) - Agent configuration and capabilities +* [Hooks](/en/hooks) - Event handling and automation +* [MCP](/en/mcp) - External tool integration +* [Settings](/en/settings) - Configuration options for plugins diff --git a/web/.claude-plugin/plugin.json b/web/.claude-plugin/plugin.json new file mode 100644 index 0000000..da0cf2a --- /dev/null +++ b/web/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "stepwise-web", + "version": "0.0.7", + "description": "Web search and research capabilities for external context", + "author": { + "name": "Jorge Castro", + "url": "https://github.com/nikeyes" + }, + "homepage": "https://github.com/nikeyes/stepwise-dev", + "repository": "https://github.com/nikeyes/stepwise-dev", + "license": "Apache-2.0", + "keywords": [ + "web", + "search", + "research", + "external" + ] +} diff --git a/web/README.md b/web/README.md new file mode 100644 index 0000000..fbb8235 --- /dev/null +++ b/web/README.md @@ -0,0 +1,46 @@ +# Stepwise Web Plugin + +Web search and research capabilities for gathering external context and information. + +## What's Included + +### Agents (1) +- `web-search-researcher` - Deep web research agent that searches and analyzes web content to answer questions + +## Installation + +```bash +# Add marketplace +/plugin marketplace add nikeyes/stepwise-dev + +# Install this plugin +/plugin install stepwise-web@stepwise-dev +``` + +## Usage + +The `web-search-researcher` agent is automatically invoked by Claude when you ask questions that require external information: + +``` +"What are the best practices for implementing OAuth 2.0?" +"How do other projects handle rate limiting?" +"What's the current state of React Server Components?" +``` + +You can also invoke it explicitly via the Task tool when you need Claude to perform deep web research on a specific topic. + +## Features + +- **Deep research**: Performs thorough web searches to find relevant information +- **Source analysis**: Fetches and analyzes web pages for accurate answers +- **Citation support**: Provides sources for all information gathered +- **Context-aware**: Integrates findings with your existing codebase context + +## Related Plugins + +- **stepwise-core**: Core workflow for Research → Plan → Implement → Validate +- **stepwise-git**: Git commit workflow without Claude attribution + +## License + +Apache License 2.0 - See LICENSE file for details. diff --git a/agents/web-search-researcher.md b/web/agents/web-search-researcher.md similarity index 100% rename from agents/web-search-researcher.md rename to web/agents/web-search-researcher.md