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

> Learn how to contribute new skills to the knowledge-work-plugins repository. Follow our guide to create SKILL.md files, update plugin manifests, and define commands.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Adding a new skill requires creating a markdown-based [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file inside a `skills/<skill-name>/` directory, updating the parent plugin's [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json).
- **[`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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:

```bash
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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/skills/budget-review/SKILL.md) with required frontmatter followed by instructional content:

```markdown
---
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:

```markdown
---
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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/skills/pipeline-review/SKILL.md) for a production-quality example of skill structure and tone.
- **Limit file sizes**: Keep [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file with proper frontmatter.
- Update [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files.

### How does Claude discover new skills automatically?

Claude reads the [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest in each plugin root directory. According to the [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json) implementation, the manifest automatically picks up any [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file at your plugin root, as shown in [`sales/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.