How to Contribute New Skills to the Knowledge-Work-Plugins Repository

Adding a new skill requires creating a markdown-based SKILL.md file inside a skills/<skill-name>/ directory, updating the parent plugin's plugin.json manifest, and optionally defining slash commands in a commands/ folder.

The knowledge-work-plugins repository by Anthropic is a collection of markdown-based plugins that transform Claude into a specialist for specific roles, teams, or workflows. Each plugin follows a strict file-based architecture where new capabilities are added through plain markdown and JSON configuration files—no compiled code or build steps required. Understanding this structure allows you to contribute skills that Claude automatically discovers and integrates.

Understanding the Plugin Architecture

The repository organizes capabilities into plugin directories, each containing a standardized layout that Claude reads to understand available tools and commands.

Core Components

• .claude-plugin/plugin.json: Declares the plugin's metadata, version, and exposed commands or skills. Claude reads this manifest to determine what capabilities are available. Located at paths like sales/.claude-plugin/plugin.json.
• .mcp.json: Maps logical connector names to MCP (Model Context Protocol) endpoint URLs, enabling skills to invoke external APIs such as Slack or Salesforce. Example: sales/.mcp.json.
• skills/<skill-folder>/SKILL.md: The only required file for any new skill. Contains frontmatter metadata (name, description, argument-hint, triggers) followed by markdown instructions that guide Claude's responses.
• commands/*.md: Optional slash-command definitions that let users explicitly invoke skills (e.g., /sales:pipeline-review).
• references/: Optional directory inside skill folders for auxiliary documentation, code snippets, or large tables that would exceed the recommended 500-line limit for SKILL.md.

Step-by-Step Guide to Adding a New Skill

Follow these steps to create a skill that integrates with the anthropics/knowledge-work-plugins repository.

1. Create the Skill Directory

Create a new folder under skills/ using a logical, hyphen-separated name in lowercase:

mkdir -p plugin-name/skills/budget-review/references

Replace plugin-name with the target plugin directory (e.g., finance, sales, engineering).

2. Write the SKILL.md Entry Point

Create skills/budget-review/SKILL.md with required frontmatter followed by instructional content:

---
name: budget-review
description: |
  Review a department's quarterly budget, flag overspend, and suggest re-allocations.
  Use when a manager asks "How are we doing against the Q2 budget?".
argument-hint: "<CSV-file-or-text>"
---

# Budget Review

> If you need to see which connectors are configured, check [CONNECTORS.md](../../CONNECTORS.md).

## Usage

/budget-review [CSV file or raw text]

## What I Need From You

- **Option A – CSV upload** – Include columns: `Category, Planned, Actual`.
- **Option B – Inline text** – Example:

Marketing, 50000, 62000 Engineering, 75000, 71000

## Output

```markdown

# Q2 Budget Review

| Category   | Planned | Actual | Δ (%) |
|------------|--------:|-------:|------:|
| Marketing  | $50,000 | $62,000 | +24% |
| Engineering| $75,000 | $71,000 | -5%  |

**Total Overspend:** $12,000 (≈ 4% over budget)

**Recommendations**
- Reduce Marketing spend by $8k (e.g., cut paid-social budget).
- Re-allocate $4k from Engineering to Marketing to maintain momentum.

Keep the primary [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) under **500 lines**. Move large reference tables or extended documentation to the `references/` subfolder, as seen in [`small-business/skills/ticket-deflector/reference/gotchas.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/reference/gotchas.md).

### 3. Update the Plugin Manifest

Edit the [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file in the plugin root to ensure Claude recognizes the new skill. The manifest automatically discovers any [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files placed under `skills/`, but you should verify the `skills` array or discovery patterns include your new directory path.

Example manifest structure from [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json):

```json
{
  "name": "sales",
  "version": "1.0.0",
  "description": "Sales team workflow automation",
  "skills": [
    "skills/pipeline-review",
    "skills/budget-review"
  ]
}

4. Add Optional Slash Commands

For explicit invocation via commands like /budget-review, create a markdown file in the commands/ directory:

---
name: budget-review
description: Run a budget review using the new skill.
---

# /budget-review

Invoke the **budget-review** skill directly:

/budget-review path/to/budget.csv

See pdf-viewer/commands/open.md for additional examples of command formatting.

Complete Example: Budget Review Skill Structure

Here is the full file tree for a hypothetical budget-review skill added to the finance plugin:

finance/
├── .claude-plugin/
│   └── plugin.json          ← Update to include new skill path
├── .mcp.json                ← Add MCP connector mappings if needed
├── skills/
│   └── budget-review/
│       ├── SKILL.md         ← Required entry point (frontmatter + instructions)
│       └── references/
│           └── example-budget-csv.md  ← Optional extended documentation
└── commands/
    └── budget-review.md     ← Optional slash command definition

Best Practices for Skill Development

When contributing to anthropics/knowledge-work-plugins, follow these guidelines to ensure quality and consistency:

• Reference the Zoom plugin CONTRIBUTING.md: The file at partner-built/zoom-plugin/CONTRIBUTING.md contains the generic "Skill Format Guidelines" used across the entire repository.
• Study existing implementations: Examine sales/skills/pipeline-review/SKILL.md for a production-quality example of skill structure and tone.
• Limit file sizes: Keep SKILL.md under 500 lines by offloading reference material to the references/ folder.
• Use proper frontmatter: Always include name, description, and argument-hint in the YAML header to help Claude understand when and how to invoke the skill.
• No build required: Since everything is plain markdown and JSON, you can test your skill files directly without compilation. Submit your contribution as a standard GitHub Pull Request.

Summary

• knowledge-work-plugins uses a markdown-based architecture requiring no compiled code.
• Create a folder under skills/<skill-name>/ and add a SKILL.md file with proper frontmatter.
• Update .claude-plugin/plugin.json to register the new skill with Claude.
• Add optional slash commands in commands/<command-name>.md for explicit user invocation.
• Maintain SKILL.md files under 500 lines using the references/ folder for auxiliary content.

Frequently Asked Questions

Do I need to know programming languages to contribute a skill?

No. The knowledge-work-plugins repository deliberately avoids compiled code. Skills are written entirely in markdown with optional JSON configuration files. You only need to understand YAML frontmatter syntax for the metadata headers in SKILL.md files.

How does Claude discover new skills automatically?

Claude reads the .claude-plugin/plugin.json manifest in each plugin root directory. According to the sales/.claude-plugin/plugin.json implementation, the manifest automatically picks up any SKILL.md files located under skills/ subdirectories. Once your PR is merged, Claude immediately recognizes the new capability without requiring redeployment.

What is the maximum length for a SKILL.md file?

Keep the primary SKILL.md entry point under 500 lines. If your skill requires extensive reference tables, code snippets, or documentation, move this content to files in the references/ folder within your skill directory, following the pattern used in small-business/skills/ticket-deflector/reference/gotchas.md.

Can my skill connect to external APIs like Slack or Salesforce?

Yes. Define MCP (Model Context Protocol) connector mappings in the .mcp.json file at your plugin root, as shown in sales/.mcp.json. This JSON file maps logical connector names to actual endpoint URLs, allowing your skill's markdown instructions to reference external tools via the MCP system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}