From 8c1ef43e9a5b53ceaeca51f06306bde7a7455dbd Mon Sep 17 00:00:00 2001 From: daymade Date: Sun, 11 Jan 2026 16:21:49 +0800 Subject: [PATCH] docs: Consolidate AGENTS.md into CLAUDE.md via symlink - Migrated all valuable architecture content from AGENTS.md into CLAUDE.md - Created new 'Plugin and Skill Architecture' section in CLAUDE.md - Includes: Core Concepts (Skills, Plugins, Agents, Commands) - Includes: Architecture diagrams, installation flow, data flow - Includes: Common misconceptions and best practices - Deleted original AGENTS.md file - Created symlink AGENTS.md -> CLAUDE.md to avoid duplicate maintenance - Updated internal references to point to CLAUDE.md sections This consolidation ensures single source of truth for plugin/skill architecture documentation. --- AGENTS.md | 317 +----------------------------------------------------- CLAUDE.md | 308 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 308 insertions(+), 317 deletions(-) mode change 100644 => 120000 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index cb3785a..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,316 +0,0 @@ -# Claude Code Architecture: Plugins, Skills, and Agents - -This document explains the architecture of Claude Code's extension system and how different components work together. - -## Core Concepts - -### 1. Skills - -**What**: Functional units that extend Claude's capabilities with specialized knowledge and workflows. - -**Structure**: -``` -skill-name/ -├── SKILL.md (required) # YAML frontmatter + Markdown instructions -├── scripts/ (optional) # Executable code (Python/Bash) -├── references/ (optional) # Documentation loaded as needed -└── assets/ (optional) # Templates and resources -``` - -**Loading mechanism** (Progressive Disclosure): -1. **Metadata** (~100 tokens): Always in context (name + description from YAML frontmatter) -2. **SKILL.md body** (<5k tokens): Loaded when Claude determines the skill applies -3. **Bundled resources**: Loaded only as needed by Claude - -**Location**: -- **Personal**: `~/.claude/skills/` (user-specific, not shared) -- **Project**: `.claude/skills/` (checked into git, shared with team) -- **Plugin cache**: `~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/{skill}/` - -**Example**: When you ask "analyze my disk space", Claude loads the `macos-cleaner` skill's SKILL.md, then reads `references/cleanup_targets.md` as needed. - -### 2. Plugins - -**What**: Distribution units that package one or more skills for installation via marketplaces. - -**Purpose**: Plugins enable: -- One-command installation (`claude plugin install skill-name@marketplace-name`) -- Version management -- Dependency tracking -- Marketplace distribution - -**Relationship to Skills**: -``` -Plugin (marketplace.json entry) -├── Skill 1 (./skill-name-1/) -├── Skill 2 (./skill-name-2/) -└── Skill 3 (./skill-name-3/) -``` - -**Configuration** (in `.claude-plugin/marketplace.json`): -```json -{ - "name": "my-plugin", - "description": "Use when...", - "version": "1.0.0", - "category": "utilities", - "keywords": ["keyword1", "keyword2"], - "skills": ["./skill-1", "./skill-2"] -} -``` - -**Example**: The `skill-creator` plugin contains one skill (`./skill-creator`), while a hypothetical `developer-tools` plugin might contain multiple skills like `./git-helper`, `./code-reviewer`, `./test-runner`. - -### 3. Agents (Subagents) - -**What**: Specialized autonomous agents invoked via the `Task` tool for complex, multi-step operations. - -**Types**: -- **Bash**: Command execution specialist -- **general-purpose**: Research, search, multi-step tasks -- **Explore**: Fast codebase exploration -- **Plan**: Software architecture planning -- **skill-creator**: Meta-agent for creating skills -- **Custom**: Domain-specific agents (e.g., `test-runner`, `build-validator`) - -**When to use**: -- Tasks requiring multiple rounds of tool calls -- Open-ended exploration (finding files, searching code) -- Planning before implementation -- Autonomous execution without user intervention - -**Example**: -```python -# Instead of manually searching multiple times: -Task( - subagent_type="Explore", - description="Find error handling code", - prompt="Search the codebase for error handling patterns and list all files that handle HTTP errors" -) -``` - -### 4. Commands - -**What**: Slash commands (e.g., `/commit`, `/review-pr`) that trigger skills. - -**Relationship**: Commands are shortcuts to invoke skills. -- `/commit` → invokes `commit` skill -- `/review-pr` → invokes `review-pr` skill - -**Configuration**: Defined in plugin's `commands/` directory or skill metadata. - -## Architecture Diagram - -``` -Marketplace (GitHub) - ↓ (git clone) -~/.claude/plugins/marketplaces/{marketplace-name}/ - ↓ (plugin install) -~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/ - ├── skill-1/ - │ ├── SKILL.md - │ ├── scripts/ - │ └── references/ - └── skill-2/ - └── SKILL.md - ↓ (Claude loads) -Claude Code Context - ├── Metadata (always loaded) - ├── SKILL.md (loaded when relevant) - └── Resources (loaded as needed) -``` - -## Installation Flow - -### Step 1: User initiates installation -```bash -claude plugin install macos-cleaner@daymade-skills -``` - -### Step 2: CLI locates marketplace -```bash -# Check ~/.claude/plugins/marketplaces/daymade-skills/ -# If not exists, git clone from GitHub -``` - -### Step 3: Read marketplace.json -```json -{ - "plugins": [ - { - "name": "macos-cleaner", - "version": "1.0.0", - "skills": ["./macos-cleaner"] - } - ] -} -``` - -### Step 4: Download to cache -```bash -# Clone entire marketplace repo to: -~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/ - -# Extract skill to: -~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/macos-cleaner/ -``` - -### Step 5: Record installation -```json -// ~/.claude/plugins/installed_plugins.json -{ - "plugins": { - "macos-cleaner@daymade-skills": [{ - "scope": "user", - "installPath": "~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0", - "version": "1.0.0", - "installedAt": "2026-01-11T08:03:46.593Z" - }] - } -} -``` - -### Step 6: Claude Code loads skill -``` -When user asks: "My Mac is running out of space" - ↓ -Claude scans installed plugins metadata - ↓ -Finds "macos-cleaner" description matches - ↓ -Loads SKILL.md into context - ↓ -Executes workflow (analyze → report → confirm → cleanup) - ↓ -Loads references/scripts as needed -``` - -## Key Files and Locations - -### Configuration Files - -| File | Location | Purpose | -|------|----------|---------| -| `marketplace.json` | `~/.claude/plugins/marketplaces/{name}/.claude-plugin/` | Defines available plugins | -| `installed_plugins.json` | `~/.claude/plugins/` | Tracks installed plugins | -| `known_marketplaces.json` | `~/.claude/plugins/` | Lists registered marketplaces | - -### Directory Structure - -``` -~/.claude/ -├── skills/ # Personal skills (not from marketplace) -├── plugins/ -│ ├── marketplaces/ # Marketplace clones -│ │ ├── daymade-skills/ # Marketplace name -│ │ │ └── .claude-plugin/ -│ │ │ └── marketplace.json -│ │ └── anthropic-agent-skills/ -│ ├── cache/ # Installed plugins -│ │ └── daymade-skills/ -│ │ └── macos-cleaner/ -│ │ └── 1.0.0/ # Version -│ │ └── macos-cleaner/ # Skill directory -│ │ ├── SKILL.md -│ │ ├── scripts/ -│ │ └── references/ -│ ├── installed_plugins.json # Installation registry -│ └── known_marketplaces.json # Marketplace registry -``` - -## Data Flow - -### Skill Activation -``` -User message - ↓ -Claude analyzes installed plugin metadata - ↓ -Matches description to user intent - ↓ -Loads SKILL.md (progressive disclosure) - ↓ -Executes instructions - ↓ -Loads bundled resources (scripts, references) as needed - ↓ -Generates response -``` - -### Plugin Update -``` -Local changes to skill - ↓ -git add & commit - ↓ -git push to GitHub - ↓ -User runs: claude plugin marketplace update {marketplace-name} - ↓ -CLI pulls latest from GitHub - ↓ -Updates ~/.claude/plugins/marketplaces/{marketplace-name}/ - ↓ -User runs: claude plugin update {plugin-name@marketplace} - ↓ -Re-downloads to cache with new version number - ↓ -Updates installed_plugins.json -``` - -## Common Misconceptions - -### ❌ Myth 1: "Updating local files immediately updates the plugin" -**Reality**: Plugins are distributed via GitHub. Local changes require `git push` before users can install updates. - -### ❌ Myth 2: "Skills and plugins are the same thing" -**Reality**: Skills are functional units (SKILL.md + resources). Plugins are distribution packages (can contain multiple skills). - -### ❌ Myth 3: "marketplace.json is just metadata" -**Reality**: marketplace.json is the **source of truth** for plugin discovery. Without correct configuration here, `claude plugin install` will fail with "Plugin not found". - -### ❌ Myth 4: "Cache is just for performance" -**Reality**: Cache (`~/.claude/plugins/cache/`) is where installed plugins actually live. Deleting cache uninstalls all plugins. - -### ❌ Myth 5: "Skills in ~/.claude/skills/ work the same as plugin skills" -**Reality**: -- `~/.claude/skills/` = Personal skills (manual management, no versioning) -- Plugin cache = Managed by CLI (versioned, updateable, shareable) - -## Best Practices - -### For Skill Authors - -1. **Clear metadata**: Description should clearly state "Use when..." to help Claude match user intent -2. **Progressive disclosure**: Keep SKILL.md lean, move details to `references/` -3. **Test locally first**: Copy to `~/.claude/skills/` for testing before packaging -4. **Version properly**: Use semver (MAJOR.MINOR.PATCH) in marketplace.json -5. **Document bundled resources**: All scripts and references should be mentioned in SKILL.md - -### For Marketplace Maintainers - -1. **Git workflow**: Always `git push` after updating marketplace.json -2. **Validate JSON**: Run `python -m json.tool marketplace.json` before committing -3. **Update cache**: Remind users to run `claude plugin marketplace update` after releases -4. **Version consistency**: Marketplace version ≠ plugin versions (they track independently) - -### For Users - -1. **Update marketplaces**: Run `claude plugin marketplace update {name}` periodically -2. **Check installed plugins**: Inspect `~/.claude/plugins/installed_plugins.json` -3. **Clear cache on issues**: `rm -rf ~/.claude/plugins/cache/{marketplace-name}` then reinstall -4. **Understand scopes**: - - `--scope user`: Only you (default) - - `--scope project`: Shared with team via `.claude/plugins/` - - `--scope local`: Gitignored, local only - -## Troubleshooting Guide - -See [CLAUDE.md § Plugin and Skill Troubleshooting](#plugin-and-skill-troubleshooting) for detailed debugging steps. - -## References - -- [Official Skills Documentation](https://code.claude.com/docs/en/skills) -- [Plugin Reference](https://code.claude.com/docs/en/plugins-reference) -- [Marketplace Discovery](https://code.claude.com/docs/en/discover-plugins) -- [Anthropic Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md) diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000..681311e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 6d9f990..d19d399 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -690,6 +690,312 @@ Always consult Anthropic's skill authoring best practices before creating or upd https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md - remember this release workflow in claude.md +## Plugin and Skill Architecture + +This section explains the architecture of Claude Code's extension system and how different components work together. + +### Core Concepts + +#### 1. Skills + +**What**: Functional units that extend Claude's capabilities with specialized knowledge and workflows. + +**Structure**: +``` +skill-name/ +├── SKILL.md (required) # YAML frontmatter + Markdown instructions +├── scripts/ (optional) # Executable code (Python/Bash) +├── references/ (optional) # Documentation loaded as needed +└── assets/ (optional) # Templates and resources +``` + +**Loading mechanism** (Progressive Disclosure): +1. **Metadata** (~100 tokens): Always in context (name + description from YAML frontmatter) +2. **SKILL.md body** (<5k tokens): Loaded when Claude determines the skill applies +3. **Bundled resources**: Loaded only as needed by Claude + +**Location**: +- **Personal**: `~/.claude/skills/` (user-specific, not shared) +- **Project**: `.claude/skills/` (checked into git, shared with team) +- **Plugin cache**: `~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/{skill}/` + +**Example**: When you ask "analyze my disk space", Claude loads the `macos-cleaner` skill's SKILL.md, then reads `references/cleanup_targets.md` as needed. + +#### 2. Plugins + +**What**: Distribution units that package one or more skills for installation via marketplaces. + +**Purpose**: Plugins enable: +- One-command installation (`claude plugin install skill-name@marketplace-name`) +- Version management +- Dependency tracking +- Marketplace distribution + +**Relationship to Skills**: +``` +Plugin (marketplace.json entry) +├── Skill 1 (./skill-name-1/) +├── Skill 2 (./skill-name-2/) +└── Skill 3 (./skill-name-3/) +``` + +**Configuration** (in `.claude-plugin/marketplace.json`): +```json +{ + "name": "my-plugin", + "description": "Use when...", + "version": "1.0.0", + "category": "utilities", + "keywords": ["keyword1", "keyword2"], + "skills": ["./skill-1", "./skill-2"] +} +``` + +**Example**: The `skill-creator` plugin contains one skill (`./skill-creator`), while a hypothetical `developer-tools` plugin might contain multiple skills like `./git-helper`, `./code-reviewer`, `./test-runner`. + +#### 3. Agents (Subagents) + +**What**: Specialized autonomous agents invoked via the `Task` tool for complex, multi-step operations. + +**Types**: +- **Bash**: Command execution specialist +- **general-purpose**: Research, search, multi-step tasks +- **Explore**: Fast codebase exploration +- **Plan**: Software architecture planning +- **skill-creator**: Meta-agent for creating skills +- **Custom**: Domain-specific agents (e.g., `test-runner`, `build-validator`) + +**When to use**: +- Tasks requiring multiple rounds of tool calls +- Open-ended exploration (finding files, searching code) +- Planning before implementation +- Autonomous execution without user intervention + +**Example**: +```python +# Instead of manually searching multiple times: +Task( + subagent_type="Explore", + description="Find error handling code", + prompt="Search the codebase for error handling patterns and list all files that handle HTTP errors" +) +``` + +#### 4. Commands + +**What**: Slash commands (e.g., `/commit`, `/review-pr`) that trigger skills. + +**Relationship**: Commands are shortcuts to invoke skills. +- `/commit` → invokes `commit` skill +- `/review-pr` → invokes `review-pr` skill + +**Configuration**: Defined in plugin's `commands/` directory or skill metadata. + +### Architecture Diagram + +``` +Marketplace (GitHub) + ↓ (git clone) +~/.claude/plugins/marketplaces/{marketplace-name}/ + ↓ (plugin install) +~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/ + ├── skill-1/ + │ ├── SKILL.md + │ ├── scripts/ + │ └── references/ + └── skill-2/ + └── SKILL.md + ↓ (Claude loads) +Claude Code Context + ├── Metadata (always loaded) + ├── SKILL.md (loaded when relevant) + └── Resources (loaded as needed) +``` + +### Installation Flow + +#### Step 1: User initiates installation +```bash +claude plugin install macos-cleaner@daymade-skills +``` + +#### Step 2: CLI locates marketplace +```bash +# Check ~/.claude/plugins/marketplaces/daymade-skills/ +# If not exists, git clone from GitHub +``` + +#### Step 3: Read marketplace.json +```json +{ + "plugins": [ + { + "name": "macos-cleaner", + "version": "1.0.0", + "skills": ["./macos-cleaner"] + } + ] +} +``` + +#### Step 4: Download to cache +```bash +# Clone entire marketplace repo to: +~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/ + +# Extract skill to: +~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/macos-cleaner/ +``` + +#### Step 5: Record installation +```json +// ~/.claude/plugins/installed_plugins.json +{ + "plugins": { + "macos-cleaner@daymade-skills": [{ + "scope": "user", + "installPath": "~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0", + "version": "1.0.0", + "installedAt": "2026-01-11T08:03:46.593Z" + }] + } +} +``` + +#### Step 6: Claude Code loads skill +``` +When user asks: "My Mac is running out of space" + ↓ +Claude scans installed plugins metadata + ↓ +Finds "macos-cleaner" description matches + ↓ +Loads SKILL.md into context + ↓ +Executes workflow (analyze → report → confirm → cleanup) + ↓ +Loads references/scripts as needed +``` + +### Key Files and Locations + +#### Configuration Files + +| File | Location | Purpose | +|------|----------|---------| +| `marketplace.json` | `~/.claude/plugins/marketplaces/{name}/.claude-plugin/` | Defines available plugins | +| `installed_plugins.json` | `~/.claude/plugins/` | Tracks installed plugins | +| `known_marketplaces.json` | `~/.claude/plugins/` | Lists registered marketplaces | + +#### Directory Structure + +``` +~/.claude/ +├── skills/ # Personal skills (not from marketplace) +├── plugins/ +│ ├── marketplaces/ # Marketplace clones +│ │ ├── daymade-skills/ # Marketplace name +│ │ │ └── .claude-plugin/ +│ │ │ └── marketplace.json +│ │ └── anthropic-agent-skills/ +│ ├── cache/ # Installed plugins +│ │ └── daymade-skills/ +│ │ └── macos-cleaner/ +│ │ └── 1.0.0/ # Version +│ │ └── macos-cleaner/ # Skill directory +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ └── references/ +│ ├── installed_plugins.json # Installation registry +│ └── known_marketplaces.json # Marketplace registry +``` + +### Data Flow + +#### Skill Activation +``` +User message + ↓ +Claude analyzes installed plugin metadata + ↓ +Matches description to user intent + ↓ +Loads SKILL.md (progressive disclosure) + ↓ +Executes instructions + ↓ +Loads bundled resources (scripts, references) as needed + ↓ +Generates response +``` + +#### Plugin Update +``` +Local changes to skill + ↓ +git add & commit + ↓ +git push to GitHub + ↓ +User runs: claude plugin marketplace update {marketplace-name} + ↓ +CLI pulls latest from GitHub + ↓ +Updates ~/.claude/plugins/marketplaces/{marketplace-name}/ + ↓ +User runs: claude plugin update {plugin-name@marketplace} + ↓ +Re-downloads to cache with new version number + ↓ +Updates installed_plugins.json +``` + +### Common Misconceptions + +#### ❌ Myth 1: "Updating local files immediately updates the plugin" +**Reality**: Plugins are distributed via GitHub. Local changes require `git push` before users can install updates. + +#### ❌ Myth 2: "Skills and plugins are the same thing" +**Reality**: Skills are functional units (SKILL.md + resources). Plugins are distribution packages (can contain multiple skills). + +#### ❌ Myth 3: "marketplace.json is just metadata" +**Reality**: marketplace.json is the **source of truth** for plugin discovery. Without correct configuration here, `claude plugin install` will fail with "Plugin not found". + +#### ❌ Myth 4: "Cache is just for performance" +**Reality**: Cache (`~/.claude/plugins/cache/`) is where installed plugins actually live. Deleting cache uninstalls all plugins. + +#### ❌ Myth 5: "Skills in ~/.claude/skills/ work the same as plugin skills" +**Reality**: +- `~/.claude/skills/` = Personal skills (manual management, no versioning) +- Plugin cache = Managed by CLI (versioned, updateable, shareable) + +### Best Practices + +#### For Skill Authors + +1. **Clear metadata**: Description should clearly state "Use when..." to help Claude match user intent +2. **Progressive disclosure**: Keep SKILL.md lean, move details to `references/` +3. **Test locally first**: Copy to `~/.claude/skills/` for testing before packaging +4. **Version properly**: Use semver (MAJOR.MINOR.PATCH) in marketplace.json +5. **Document bundled resources**: All scripts and references should be mentioned in SKILL.md + +#### For Marketplace Maintainers + +1. **Git workflow**: Always `git push` after updating marketplace.json +2. **Validate JSON**: Run `python -m json.tool marketplace.json` before committing +3. **Update cache**: Remind users to run `claude plugin marketplace update` after releases +4. **Version consistency**: Marketplace version ≠ plugin versions (they track independently) + +#### For Users + +1. **Update marketplaces**: Run `claude plugin marketplace update {name}` periodically +2. **Check installed plugins**: Inspect `~/.claude/plugins/installed_plugins.json` +3. **Clear cache on issues**: `rm -rf ~/.claude/plugins/cache/{marketplace-name}` then reinstall +4. **Understand scopes**: + - `--scope user`: Only you (default) + - `--scope project`: Shared with team via `.claude/plugins/` + - `--scope local`: Gitignored, local only + ## Plugin and Skill Troubleshooting This section provides systematic debugging steps for common plugin and skill installation issues. @@ -1133,6 +1439,6 @@ If you're still stuck: 4. **Document your debugging**: Include output from all diagnostic commands above For this project specifically, refer to: -- [AGENTS.md](./AGENTS.md) - Architecture overview +- [Plugin and Skill Architecture](#plugin-and-skill-architecture) - Architecture overview (this document) - [skill-creator/SKILL.md](./skill-creator/SKILL.md) - Skill creation guide - [CONTRIBUTING.md](./CONTRIBUTING.md) - Development workflow