Schema Research: Claude Code Plugin, Agent, and Skill Formats

Schema Research: Claude Code Plugin, Agent, and Skill Formats

Sources:

• https://code.claude.com/docs/en/plugins-reference.md (fetched 2026-02-19)
• https://code.claude.com/docs/en/skills.md (fetched 2026-02-19)
• https://code.claude.com/docs/en/sub-agents.md (fetched 2026-02-19)
• Real agent files in /home/ubuntulinuxqa2/repos/claude_skills/plugins/

1. Agent Frontmatter — Complete Schema

Required Fields

Optional Fields

Critical Formatting Constraint

tools, disallowedTools, and skills MUST be comma-separated strings, NOT YAML arrays.

# CORRECT
tools: Read, Grep, Glob, Bash
skills: python3-development, uv

# WRONG — will fail validation
tools:
  - Read
  - Grep

Complete Example Agent File

---
name: dasel-operator
description: Executes dasel queries and transformations on YAML, TOML, JSON, and JSONC files. Use when querying structured config files, applying path-based updates, or converting between config formats.
tools: Read, Bash, Write, Edit, Grep, Glob
model: sonnet
color: cyan
---

Agent system prompt body goes here in Markdown.

2. Model Field — Exact Values

The model field accepts aliases only (not full model IDs):

inherit is the default when model is omitted.

In agent frontmatter:

model: haiku    # Fast, use for retrieval-only agents
model: sonnet   # Default for most specialist agents
model: opus     # Use for complex reasoning (e.g., refactor-skill)
model: inherit  # Explicitly inherit from orchestrator

In SKILL.md frontmatter — same aliases apply:

model: sonnet

3. SKILL.md Frontmatter — Complete Schema

Fields

Bug: name Field in Plugin Skills

Confirmed Claude Code v2.1.23 bug: plugin skills with an explicit name: field in frontmatter do NOT appear as slash commands. Affects ONLY plugin skills (plugins/*/skills/*/SKILL.md). Skills in ~/.claude/skills/ and .claude/skills/ work correctly.

Workaround: Omit the name: field in plugin SKILL.md files. Claude Code uses the directory name instead.

Complete SKILL.md Example

---
description: Runs dasel queries against structured config files. Use when reading or updating YAML, TOML, JSON fields by path selector.
disable-model-invocation: false
allowed-tools: Bash, Read, Write
model: sonnet
---

Skill body in Markdown.

SKILL.md with Subagent Fork

---
description: Deep research on dasel selectors and expressions
context: fork
agent: Explore
allowed-tools: Bash(dasel *)
---

Research $ARGUMENTS thoroughly using dasel documentation...

4. plugin.json — Complete Schema

Location: <plugin-root>/.claude-plugin/plugin.json

The manifest is optional. name is the only required field if the manifest exists.

Complete Schema

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": ["./agents/agent-one.md", "./agents/agent-two.md"],
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

Field Reference

Critical: agents Field Format

The agents field must be an array of individual file paths, not a directory string.

// CORRECT
"agents": ["./agents/dasel-operator.md", "./agents/config-researcher.md"]

// WRONG — causes "agents: Invalid input" validation error
"agents": "./agents/"

Path Rules

• All paths must be relative to plugin root
• All paths must start with ./
• Custom paths supplement default directories (they don't replace them)

Environment Variable

${CLAUDE_PLUGIN_ROOT} — absolute path to the plugin directory at runtime. Use in hooks and MCP server configs:

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.py"
      }]
    }]
  }
}

5. How Skills Reference Agents

Two mechanisms exist:

Mechanism 1: Skill Forks into an Agent (context: fork)

A skill runs inside a named subagent. The skill content becomes the task/prompt for that agent.

---
description: Research dasel selectors thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS using dasel documentation...

The agent field can be:

• Built-in: Explore, Plan, general-purpose
• Custom agent name (must exist in .claude/agents/ or a plugin's agents/ directory)
• Omitted: defaults to general-purpose

Mechanism 2: Agent Preloads Skills (skills field in agent frontmatter)

An agent declares skills to inject at startup. Full skill content is loaded into the agent's context.

---
name: dasel-operator
description: Expert dasel operator
skills: dasel-reference, yaml-patterns
---

The agent does not inherit skills from the parent conversation — skills must be listed explicitly.

6. Agent File — Location and Naming Rules

Location Priority (highest to lowest)

Naming

• Filename: <agent-name>.md (kebab-case)
• name field in frontmatter must match kebab-case, lowercase letters and hyphens only, max 64 characters
• Namespaced in UI as plugin-name:agent-name when from a plugin

File Structure

---
name: agent-name
description: When Claude should delegate here
tools: Read, Grep, Glob
model: sonnet
color: cyan
---

System prompt body in Markdown. This is what the agent receives
as its system prompt. It does NOT receive the full Claude Code
system prompt — only this body plus basic environment details
(working directory, etc.).

7. Validation Rules Summary

Run validation:

# Validate single agent or skill file
uv run plugins/plugin-creator/scripts/plugin_validator.py <path>

# Validate entire plugin
uv run plugins/plugin-creator/scripts/plugin_validator.py plugins/my-plugin

# Validate plugin structure (Claude Code built-in)
claude plugin validate plugins/my-plugin

Agent Validation Rules

• name: required, kebab-case, max 64 chars
• description: required, max 1024 chars, no colons except in URLs (use em dash — instead)
• model: must be sonnet, opus, haiku, or inherit if specified
• tools: must be comma-separated string (not YAML array, not JSON array)
• disallowedTools: must be comma-separated string
• skills: must be comma-separated string

Skill Validation Rules

• name: optional (omit for plugin skills due to bug)
• description: optional but recommended
• allowed-tools: must be comma-separated string (not YAML array)
• model: must be valid alias if specified

plugin.json Validation Rules

• name: required, kebab-case
• agents: must be array of individual file paths (not a directory path string)
• All path values must start with ./
• JSON must be syntactically valid

8. Real Examples from This Repository

Agent with All Common Fields

From plugins/python3-development/agents/python-cli-architect.md:

---
name: python-cli-architect
description: Creates, enhances, and reviews Python CLI code using modern patterns with Typer and Rich. Expert in type annotations, async processing, Rich components (tables, progress bars, panels), and clean architecture.
color: pink
permissionMode: bypassPermissions
---

From plugins/agentskill-kaizen/agents/transcript-analyst.md:

---
name: transcript-analyst
description: "Deep-dive into Claude Code session transcripts using DuckDB SQL and process mining tools — spawned by analyze and explore commands to query JSONL data, detect anti-patterns, extract frustration signals, and mine workflow patterns across sessions"
model: sonnet
color: cyan
skills: transcript-analysis
---

Agent with All Fields (Example/Reference File)

From plugins/plugin-creator/examples/agents/example-agent.md:

---
name: example-agent
description: "Demonstrates all available agent frontmatter fields. Use when you need a reference for agent configuration or when learning about agent capabilities. Handles example tasks, demonstration requests, and tutorial scenarios."
tools: Read, Grep, Glob, WebFetch, WebSearch
disallowedTools: Bash, Write, Edit
model: sonnet
permissionMode: default
skills: python3-development, claude-skills-overview-2026
hooks:
  PreToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "echo 'About to read a file'"
          timeout: 5
color: cyan
---

Minimal Agent (No Optional Fields)

From plugins/summarizer/agents/image-summarizer.md:

---
name: image-summarizer
description: Autonomous image and screenshot summarization agent. Use when user requests description of images, screenshots, diagrams, or visual content and does not need to discuss it interactively.
---

9. Hooks Configuration Format (in Agent/Skill Frontmatter)

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
          timeout: 30
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/lint.py"
  Stop:
    - hooks:
        - type: prompt
          prompt: "Summarize what was accomplished."

Hook types: command, prompt, agent

Stop hooks in agent frontmatter are automatically converted to SubagentStop at runtime.

10. Standard Plugin Directory Layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest (optional)
├── agents/                  # agent .md files
│   └── my-agent.md
├── skills/                  # skill directories
│   └── my-skill/
│       └── SKILL.md
├── commands/                # legacy (use skills/ for new work)
├── hooks/
│   └── hooks.json
├── scripts/                 # helper scripts
├── .mcp.json                # MCP server definitions
└── .lsp.json                # LSP server configs

Components (agents/, skills/, hooks/) must be at the plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.