Skip to content

docs: add architecture documentation for commands vs skills #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shrinet82 wants to merge 1 commit into
base: main
Choose a base branch
from
+328 −13
Open

docs: add architecture documentation for commands vs skills #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 18 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ Each plugin bundles the skills, connectors, slash commands, and sub-agents for a

We're open-sourcing 11 plugins built and inspired by our own work:

| Plugin | How it helps | Connectors |
|--------|-------------|------------|
| **[productivity](./productivity)** | Manage tasks, calendars, daily workflows, and personal context so you spend less time repeating yourself. | Slack, Notion, Asana, Linear, Jira, Monday, ClickUp, Microsoft 365 |
| **[sales](./sales)** | Research prospects, prep for calls, review your pipeline, draft outreach, and build competitive battlecards. | Slack, HubSpot, Close, Clay, ZoomInfo, Notion, Jira, Fireflies, Microsoft 365 |
| **[customer-support](./customer-support)** | Triage tickets, draft responses, package escalations, research customer context, and turn resolved issues into knowledge base articles. | Slack, Intercom, HubSpot, Guru, Jira, Notion, Microsoft 365 |
| **[product-management](./product-management)** | Write specs, plan roadmaps, synthesize user research, keep stakeholders updated, and track the competitive landscape. | Slack, Linear, Asana, Monday, ClickUp, Jira, Notion, Figma, Amplitude, Pendo, Intercom, Fireflies |
| **[marketing](./marketing)** | Draft content, plan campaigns, enforce brand voice, brief on competitors, and report on performance across channels. | Slack, Canva, Figma, HubSpot, Amplitude, Notion, Ahrefs, SimilarWeb, Klaviyo |
| **[legal](./legal)** | Review contracts, triage NDAs, navigate compliance, assess risk, prep for meetings, and draft templated responses. | Slack, Box, Egnyte, Jira, Microsoft 365 |
| **[finance](./finance)** | Prep journal entries, reconcile accounts, generate financial statements, analyze variances, manage close, and support audits. | Snowflake, Databricks, BigQuery, Slack, Microsoft 365 |
| **[data](./data)** | Query, visualize, and interpret datasets — write SQL, run statistical analysis, build dashboards, and validate your work before sharing. | Snowflake, Databricks, BigQuery, Hex, Amplitude, Jira |
| **[enterprise-search](./enterprise-search)** | Find anything across email, chat, docs, and wikis — one query across all your company's tools. | Slack, Notion, Guru, Jira, Asana, Microsoft 365 |
| **[bio-research](./bio-research)** | Connect to preclinical research tools and databases (literature search, genomics analysis, target prioritization) to accelerate early-stage life sciences R&D. | PubMed, BioRender, bioRxiv, ClinicalTrials.gov, ChEMBL, Synapse, Wiley, Owkin, Open Targets, Benchling |
| **[cowork-plugin-management](./cowork-plugin-management)** | Create new plugins or customize existing ones for your organization's specific tools and workflows. | — |
| Plugin | How it helps | Connectors |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **[productivity](./productivity)** | Manage tasks, calendars, daily workflows, and personal context so you spend less time repeating yourself. | Slack, Notion, Asana, Linear, Jira, Monday, ClickUp, Microsoft 365 |
| **[sales](./sales)** | Research prospects, prep for calls, review your pipeline, draft outreach, and build competitive battlecards. | Slack, HubSpot, Close, Clay, ZoomInfo, Notion, Jira, Fireflies, Microsoft 365 |
| **[customer-support](./customer-support)** | Triage tickets, draft responses, package escalations, research customer context, and turn resolved issues into knowledge base articles. | Slack, Intercom, HubSpot, Guru, Jira, Notion, Microsoft 365 |
| **[product-management](./product-management)** | Write specs, plan roadmaps, synthesize user research, keep stakeholders updated, and track the competitive landscape. | Slack, Linear, Asana, Monday, ClickUp, Jira, Notion, Figma, Amplitude, Pendo, Intercom, Fireflies |
| **[marketing](./marketing)** | Draft content, plan campaigns, enforce brand voice, brief on competitors, and report on performance across channels. | Slack, Canva, Figma, HubSpot, Amplitude, Notion, Ahrefs, SimilarWeb, Klaviyo |
| **[legal](./legal)** | Review contracts, triage NDAs, navigate compliance, assess risk, prep for meetings, and draft templated responses. | Slack, Box, Egnyte, Jira, Microsoft 365 |
| **[finance](./finance)** | Prep journal entries, reconcile accounts, generate financial statements, analyze variances, manage close, and support audits. | Snowflake, Databricks, BigQuery, Slack, Microsoft 365 |
| **[data](./data)** | Query, visualize, and interpret datasets — write SQL, run statistical analysis, build dashboards, and validate your work before sharing. | Snowflake, Databricks, BigQuery, Hex, Amplitude, Jira |
| **[enterprise-search](./enterprise-search)** | Find anything across email, chat, docs, and wikis — one query across all your company's tools. | Slack, Notion, Guru, Jira, Asana, Microsoft 365 |
| **[bio-research](./bio-research)** | Connect to preclinical research tools and databases (literature search, genomics analysis, target prioritization) to accelerate early-stage life sciences R&D. | PubMed, BioRender, bioRxiv, ClinicalTrials.gov, ChEMBL, Synapse, Wiley, Owkin, Open Targets, Benchling |
| **[cowork-plugin-management](./cowork-plugin-management)** | Create new plugins or customize existing ones for your organization's specific tools and workflows. | — |

Install these directly from Cowork, browse the full collection here on GitHub, or build your own.

Expand Down Expand Up @@ -64,6 +64,11 @@ plugin-name/

Every component is file-based — markdown and JSON, no code, no infrastructure, no build steps.

For a deeper understanding of plugin architecture, see:

- [Architecture Overview](./docs/ARCHITECTURE.md) — How plugins are structured and loaded
- [Commands vs Skills](./docs/COMMANDS_VS_SKILLS.md) — Understanding when to use each

## Making Them Yours

These plugins are generic starting points. They become much more useful when you customize them for how your company actually works:
Expand Down
103 changes: 103 additions & 0 deletions docs/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Plugin Architecture

This document explains how Claude Cowork and Claude Code plugins are structured and how they work together.

## Plugin Structure

Every plugin follows this directory structure:

```
plugin-name/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (name, description, version)
├── .mcp.json # MCP server connections for external tools
├── README.md # Plugin documentation
├── CONNECTORS.md # Guide to available tool connections
├── LICENSE # License file
├── commands/ # Slash commands (explicit user actions)
│ ├── command-one.md
│ └── command-two.md
└── skills/ # Domain knowledge (automatic context)
├── skill-one/
│ ├── SKILL.md
│ └── references/ # Supporting files
└── skill-two/
└── SKILL.md
```

## Component Overview

### Plugin Manifest (`.claude-plugin/plugin.json`)

Defines plugin metadata:

- `name`: Plugin identifier
- `description`: What the plugin does
- `version`: Semantic version number

### MCP Configuration (`.mcp.json`)

Connects Claude to external tools via [Model Context Protocol](https://modelcontextprotocol.io/). Defines which servers to connect (CRMs, databases, project trackers, etc.).

### Commands (`commands/`)

Markdown files that define **explicit slash commands** users invoke directly.

- Triggered by typing `/plugin:command-name`
- Contains step-by-step workflow instructions
- Specifies expected inputs and outputs
- References skills automatically when needed

See [Commands vs Skills](./COMMANDS_VS_SKILLS.md) for details.

### Skills (`skills/`)

Markdown files containing **domain knowledge** Claude uses automatically.

- Activated when relevant to the conversation
- Contains best practices, terminology, and expertise
- Can include reference files in subdirectories
- Not invoked directly by users

See [Commands vs Skills](./COMMANDS_VS_SKILLS.md) for details.

## How Claude Loads Plugins

1. **Plugin Discovery**: Claude scans for plugins in the configured directories
2. **Manifest Reading**: Loads `plugin.json` to register the plugin
3. **Command Registration**: Makes all commands available as slash commands
4. **Skill Loading**: Indexes all skills for contextual retrieval
5. **MCP Connection**: Establishes connections to configured external tools

## How Commands and Skills Interact

When a user invokes a command:

1. Claude reads the command file for the workflow
2. Claude automatically retrieves relevant skills based on context
3. Claude executes the workflow using both command instructions and skill knowledge
4. External tools are accessed via MCP connections as needed

```
User: /legal:review-contract

Claude loads:
├── commands/review-contract.md ← Workflow steps
├── skills/contract-review/ ← Domain expertise (automatic)
└── .mcp.json ← Tool connections (Box, Slack, etc.)
```

## Customization Points

Plugins use `~~` prefixes to mark customizable placeholders:

```markdown
Send the summary to ~~your-team-channel
```

These can be replaced with organization-specific values during setup.

## Related Documentation

- [Commands vs Skills](./COMMANDS_VS_SKILLS.md) - Detailed comparison
- [README](../README.md) - Getting started guide
207 changes: 207 additions & 0 deletions docs/COMMANDS_VS_SKILLS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
# Commands vs Skills: Understanding the Difference

This document clarifies the distinction between **commands** and **skills** in Claude plugins, addressing common confusion about their overlap and relationship.

## Quick Summary

| Aspect | Commands | Skills |
| -------------------- | ------------------------------ | -------------------------------- |
| **Invocation** | Explicit (`/plugin:command`) | Automatic (contextual) |
| **Purpose** | Define _what_ to do | Define _how_ to do it |
| **User interaction** | User triggers directly | Claude retrieves when relevant |
| **Content focus** | Workflow steps, inputs/outputs | Domain expertise, best practices |
| **File location** | `commands/*.md` | `skills/*/SKILL.md` |

## Commands: Explicit Actions

Commands are **explicit actions** that users trigger with slash commands.

### What Commands Contain

- **Step-by-step workflow** — The sequence of actions to perform
- **Input expectations** — What the user should provide
- **Output format** — How results should be structured
- **Tool interactions** — Which MCP connections to use

### Example: `/legal:review-contract`

```markdown
---
description: Review a contract against your organization's negotiation playbook
argument-hint: "<contract file or text>"
---

# /review-contract

## Workflow

### Step 1: Accept the Contract

Accept the contract in any of these formats:

- File upload: PDF, DOCX, or other document format
- URL: Link to a contract in your CLM or cloud storage
- Pasted text: Contract text pasted directly

### Step 2: Gather Context

Ask the user for context before beginning the review:

1. Which side are you on? (vendor, customer, etc.)
2. Deadline: When does this need to be finalized?
...
```

**Key observation**: Commands tell Claude _what steps to follow_.

---

## Skills: Domain Knowledge

Skills provide **domain expertise** that Claude draws on automatically when relevant.

### What Skills Contain

- **Domain knowledge** — Terminology, concepts, best practices
- **Expert guidance** — How to approach specific situations
- **Classification criteria** — How to categorize or evaluate things
- **Reference material** — Supporting documentation

### Example: `legal/skills/contract-review`

```markdown
---
name: contract-review
description: Review contracts against your organization's negotiation playbook...
---

# Contract Review Skill

You are a contract review assistant for an in-house legal team...

## Common Clause Analysis

### Limitation of Liability

**Key elements to review:**

- Cap amount (fixed dollar amount, multiple of fees, or uncapped)
- Whether the cap is mutual or applies differently to each party
- Carveouts from the cap (what liabilities are uncapped)
...

## Deviation Severity Classification

### GREEN -- Acceptable

The clause aligns with or is better than the organization's standard position...

### YELLOW -- Negotiate

The clause falls outside the standard position but within a negotiable range...

### RED -- Escalate

The clause falls outside acceptable range or triggers a defined escalation criterion...
```

**Key observation**: Skills tell Claude _how to think about the domain_.

---

## Why They Overlap (And That's Intentional)

Issue #5 correctly observes that commands and skills often cover similar ground. This is **by design**:

```
┌─────────────────────────────────────────────────────────────┐
│ USER INVOKES COMMAND │
│ /legal:review-contract │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ COMMAND (Workflow) │
│ "Step 1: Accept contract. Step 2: Gather context..." │
│ │
│ Claude follows these explicit steps │
└─────────────────────────────────────────────────────────────┘
│
│ Claude automatically retrieves
│ relevant domain knowledge
▼
┌─────────────────────────────────────────────────────────────┐
│ SKILL (Expertise) │
│ "When reviewing Limitation of Liability clauses, │
│ look for: cap amount, carveouts, mutual vs unilateral..." │
│ │
│ Claude uses this expertise while executing the command │
└─────────────────────────────────────────────────────────────┘
```

### The Command Needs Context

Without the skill, the command would say "analyze each clause" but Claude wouldn't know:

- What makes a good vs bad liability cap
- How to classify deviations (GREEN/YELLOW/RED)
- What redline language to suggest

### The Skill Needs Structure

Without the command, the skill provides expertise but not:

- When to apply it (explicit user intent)
- What order to follow
- What output format to produce

---

## How Claude Uses Both Together

1. **User invokes command**: `/legal:review-contract`
2. **Claude reads command file**: Gets the workflow steps
3. **Claude retrieves relevant skills**: Based on the command's domain
4. **Claude executes workflow**: Uses skill knowledge to inform each step
5. **Output follows command format**: Structure from command, intelligence from skill

Skills within a plugin are **scoped to that plugin**. When you invoke `/legal:review-contract`, Claude has access to all skills in the `legal` plugin, not skills from `sales` or `marketing`.

---

## Practical Guidelines for Contributors

### When to Create a Command

- User needs to trigger a specific action
- There's a defined workflow with inputs/outputs
- The action should appear in slash command suggestions

### When to Create a Skill

- Domain expertise that applies across multiple commands
- Best practices Claude should know but users don't explicitly request
- Classification criteria, terminology, or specialized knowledge

### When You Need Both

Most features need both:

| Command (the "what") | Skill (the "how") |
| -------------------- | ------------------------------------------- |
| `/analyze` | `data-exploration`, `statistical-analysis` |
| `/review-contract` | `contract-review` |
| `/call-prep` | `account-research`, `discovery-methodology` |

### Avoiding Duplication

- **Commands**: Focus on workflow orchestration
- **Skills**: Focus on domain knowledge
- If content appears in both, ask: "Is this a step (command) or expertise (skill)?"

---

## Related Documentation

- [Architecture](./ARCHITECTURE.md) — Overall plugin structure
- [README](../README.md) — Getting started guide