diff --git a/README.md b/README.md index c902fcb..0c22ab5 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..1d439e8 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -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 diff --git a/docs/COMMANDS_VS_SKILLS.md b/docs/COMMANDS_VS_SKILLS.md new file mode 100644 index 0000000..d5cf16b --- /dev/null +++ b/docs/COMMANDS_VS_SKILLS.md @@ -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: "" +--- + +# /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