Component Schemas

Detailed format specifications for every plugin component type. Reference this when implementing components in Phase 4.

Skills

Location: skills/skill-name/SKILL.md Format: Markdown with YAML frontmatter

Frontmatter Fields

Example Skill

---
name: api-design
description: >
  This skill should be used when the user asks to "design an API",
  "create API endpoints", "review API structure", or needs guidance
  on REST API best practices, endpoint naming, or request/response design.
metadata:
  version: "0.1.0"
---

Writing Style Rules

• Frontmatter description: Third-person ("This skill should be used when..."), with specific trigger phrases in quotes.
• Body: Imperative/infinitive form ("Parse the config file," not "You should parse the config file").
• Length: Keep SKILL.md body under 3,000 words (ideally 1,500-2,000). Move detailed content to references/.

Skill Directory Structure

skill-name/
├── SKILL.md              # Core knowledge (required)
├── references/           # Detailed docs loaded on demand
│   ├── patterns.md
│   └── advanced.md
├── examples/             # Working code examples
│   └── sample-config.json
└── scripts/              # Utility scripts
    └── validate.sh

Progressive Disclosure Levels

1. Metadata (always in context): name + description (~100 words)
2. SKILL.md body (when skill triggers): core knowledge (<5k words)
3. Bundled resources (as needed): references, examples, scripts (unlimited)

Agents

Location: agents/agent-name.md Format: Markdown with YAML frontmatter

Frontmatter Fields

Example Agent

---
name: code-reviewer
description: Use this agent when the user asks for a thorough code review or wants detailed analysis of code quality, security, and best practices.

<example>
Context: User has just written a new module
user: "Can you do a deep review of this code?"
assistant: "I'll use the code-reviewer agent to provide a thorough analysis."
<commentary>
User explicitly requested a detailed review, which matches this agent's specialty.
</commentary>
</example>

<example>
Context: User is about to merge a PR
user: "Review this before I merge"
assistant: "Let me run a comprehensive review using the code-reviewer agent."
<commentary>
Pre-merge review benefits from the agent's structured analysis process.
</commentary>
</example>

model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---

You are a code review specialist focused on identifying issues across security, performance, maintainability, and correctness.

**Your Core Responsibilities:**

1. Analyze code structure and organization
2. Identify security vulnerabilities
3. Flag performance concerns
4. Check adherence to best practices

**Analysis Process:**

1. Read all files in scope
2. Identify patterns and anti-patterns
3. Categorize findings by severity
4. Provide specific remediation suggestions

**Output Format:**
Present findings grouped by severity (Critical, Warning, Info) with:

- File path and line number
- Description of the issue
- Suggested fix

Agent Naming Rules

• 3-50 characters
• Lowercase letters, numbers, hyphens only
• Must start and end with alphanumeric
• No underscores, spaces, or special characters

Color Guidelines

• Blue/Cyan: Analysis, review
• Green: Success-oriented tasks
• Yellow: Caution, validation
• Red: Critical, security
• Magenta: Creative, generation

Hooks

Location: hooks/hooks.json Format: JSON

Available Events

Hook Types

Prompt-based (recommended for complex logic):

{
  "type": "prompt",
  "prompt": "Evaluate whether this file write follows project conventions: $TOOL_INPUT",
  "timeout": 30
}

Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse.

Command-based (deterministic checks):

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
  "timeout": 60
}

Example hooks.json

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Check that this file write follows project coding standards. If it violates standards, explain why and block.",
          "timeout": 30
        }
      ]
    }
  ],
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "cat ${CLAUDE_PLUGIN_ROOT}/context/project-context.md",
          "timeout": 10
        }
      ]
    }
  ]
}

Hook Output Format (Command Hooks)

Command hooks return JSON to stdout:

{
  "decision": "block",
  "reason": "File write violates naming convention"
}

Decisions: approve, block, ask_user (ask for confirmation).

MCP Servers

Location: .mcp.json at plugin root Format: JSON

Server Types

stdio (local process):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

SSE (remote server, server-sent events transport):

{
  "mcpServers": {
    "asana": {
      "type": "sse",
      "url": "https://mcp.asana.com/sse"
    }
  }
}

HTTP (remote server, streamable HTTP transport):

{
  "mcpServers": {
    "api-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Environment Variable Expansion

All MCP configs support ${VAR_NAME} substitution:

• ${CLAUDE_PLUGIN_ROOT} — plugin directory (always use for portability)
• ${ANY_ENV_VAR} — user environment variables

Document all required environment variables in the plugin README.

Directory Servers Without a URL

Some MCP directory entries have no url because the endpoint is dynamic. Plugins can reference these servers by name instead — if the server name in the plugin's MCP config matches the directory entry name, it is treated the same as a URL match.

Commands (Legacy)

**Prefer skills/*/SKILL.md for new plugins.** The Cowork UI now presents commands and skills as a single "Skills" concept. The commands/ format still works, but only use it if you specifically need the single-file format with $ARGUMENTS/$1 substitution and inline bash execution.

Location: commands/command-name.md Format: Markdown with optional YAML frontmatter

Frontmatter Fields

Example Command

---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
argument-hint: [file-path]
---

Review @$1 for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

Provide specific line numbers, severity ratings, and remediation suggestions.

Key Rules

• Commands are instructions FOR Claude, not messages for the user. Write them as directives.
• $ARGUMENTS captures all arguments as a single string; $1, $2, $3 capture positional arguments.
• @path syntax includes file contents in the command context.
• ! backtick syntax executes bash inline for dynamic context (e.g., ` !git diff --name-only `).
• Use ${CLAUDE_PLUGIN_ROOT} to reference plugin files portably.

allowed-tools Patterns

# Specific tools
allowed-tools: Read, Write, Edit, Bash(git:*)

# Bash with specific commands only
allowed-tools: Bash(npm:*), Read

# MCP tools (specific)
allowed-tools: ["mcp__plugin_name_server__tool_name"]

CONNECTORS.md

Location: Plugin root When to create: When the plugin references external tools by category rather than specific product

Format

# Connectors

## How tool references work

Plugin files use `~~category` as a placeholder for whatever tool the user
connects in that category. For example, `~~project tracker` might mean
Asana, Linear, Jira, or any other project tracker with an MCP server.

Plugins are tool-agnostic — they describe workflows in terms of categories
rather than specific products.

## Connectors for this plugin

| Category        | Placeholder         | Included servers | Other options            |
| --------------- | ------------------- | ---------------- | ------------------------ |
| Chat            | `~~chat`            | Slack            | Microsoft Teams, Discord |
| Project tracker | `~~project tracker` | Linear           | Asana, Jira, Monday      |

Using ~~ Placeholders

In plugin files (skills, agents), reference tools generically:

Check ~~project tracker for open tickets assigned to the user.
Post a summary to ~~chat in the team channel.

During customization (via the cowork-plugin-customizer skill), these get replaced with specific tool names.

README.md

Every plugin should include a README with:

1. Overview — what the plugin does
2. Components — list of skills, agents, hooks, MCP servers
3. Setup — any required environment variables or configuration
4. Usage — how to trigger each skill
5. Customization — if CONNECTORS.md exists, mention it