claude-code-skills-reference/AGENTS.md

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

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

# 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

claude plugin install macos-cleaner@daymade-skills

Step 2: CLI locates marketplace

# Check ~/.claude/plugins/marketplaces/daymade-skills/
# If not exists, git clone from GitHub

Step 3: Read marketplace.json

{
  "plugins": [
    {
      "name": "macos-cleaner",
      "version": "1.0.0",
      "skills": ["./macos-cleaner"]
    }
  ]
}

Step 4: Download to cache

# 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

// ~/.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 for detailed debugging steps.

References

• Official Skills Documentation
• Plugin Reference
• Marketplace Discovery
• Anthropic Skills Best Practices