# How to Define New Skills for Anthropic's Knowledge Work Plugins: A Complete Guide

> Learn how to define new skills for Anthropic's knowledge work plugins. Create a SKILL.md file with YAML front-matter for auto-discovery by Claude runtime.

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

---

**Defining a new skill for Anthropic's Knowledge Work plugins requires creating a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file with YAML front-matter inside a plugin's `skills/` directory, which the Claude runtime auto-discovers at load time without additional registration.**

In the `anthropics/knowledge-work-plugins` repository, skills are self-contained markdown documents that expose slash-commands and natural-language triggers to Claude. This flat, file-based architecture allows developers to extend the knowledge work ecosystem by writing structured documentation rather than code.

## Understanding the Skill Architecture

The plugin system uses a **declarative markdown-driven approach** where each skill exists as a standalone [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file. The runtime walks the `skills/` subtree at load time, parsing each file to extract:

- **Identifiers** from YAML front-matter that generate slash-commands (`/your-skill`)
- **Trigger phrases** that Claude matches during conversations
- **Workflow steps** encoded as numbered markdown lists
- **Guardrails** that constrain Claude's behavior (e.g., read-only operations)

The plugin manifest at [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) registers the top-level plugin, but individual skills require no explicit registration. When Claude receives a user utterance, it scans the skill corpus for matching triggers, selects the highest-confidence match, and executes the stepwise instructions while respecting any defined guardrails before performing connector calls.

## Step-by-Step Guide to Defining a New Skill

### 1. Create the Skill Directory

Navigate to the appropriate plugin directory and create a new folder under its `skills/` subtree. For example:

- `small-business/skills/` for business automation tools
- `partner-built/zoom-plugin/skills/` for partner-built integrations
- `data/skills/` for data-centric analysis tools

Name the directory descriptively (e.g., `tax-season-organizer` or `project-status`).

### 2. Author the SKILL.md File

Create a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file containing **YAML front-matter** followed by a structured markdown body:

```markdown
---
name: project-status
description: |
  Summarizes the current status of all active tasks for a given project.
---

# Project Status

> **Framing:** This skill provides a read-only snapshot of project health.

## Trigger

Run this skill whenever the user mentions:
- "project status", "current progress", "what's left to do"

## Workflow

1. **Identify the project** – Ask the user which project they want status for.
2. **Query the task connector** – Use the `tasks/list` API to fetch open tasks.
3. **Aggregate** – Group tasks by assignee and priority.
4. **Generate output** – Return a markdown table with results.

## Guardrails

- *Read-only*: Do not modify any task fields.
- *Privacy*: Redact confidential information in task descriptions.

## Reference files

- [reference/connector-queries.md](reference/connector-queries.md)

```

### 3. Add Reference Materials

Create a `reference/` subdirectory within your skill folder for supplemental documentation:

- **Connector queries**: API details and authentication notes (e.g., [`reference/connector-queries.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/reference/connector-queries.md))
- **Gotchas**: Common failure modes and edge cases (e.g., [`reference/gotchas.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/reference/gotchas.md))
- **Skill templates**: Boilerplate starting points for similar skills

### 4. Commit for Auto-Discovery

Commit the new directory to the repository. The plugin loader automatically discovers any [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) under a `skills/` subtree, requiring no additional configuration or registration steps.

## SKILL.md Structure and Syntax

A valid skill definition requires two distinct sections:

**YAML Front-matter**
- `name`: Machine-readable identifier used for the slash-command
- `description`: Natural-language explanation of the skill's purpose

**Markdown Body Sections**
- **Trigger**: Bullet list of phrases that activate the skill
- **Workflow**: Numbered steps describing the execution logic
- **Guardrails**: Safety instructions and constraints (e.g., "never give tax advice")
- **Reference files**: Links to supporting documentation within the skill directory

## Practical Example: Creating a Custom Project Status Skill

Below is a complete implementation for a hypothetical task-tracking skill:

```markdown
---
name: project-status
description: |
  Summarizes the current status of all active tasks for a given project.
---

# Project Status

> **Framing:** This skill provides a read-only snapshot of project health; it does not modify any task data.

## Trigger

Run this skill whenever the user mentions:
- "project status", "current progress", "what's left to do", or "show me my open tasks".

## Workflow

1. **Identify the project** – Ask the user which project they want a status for, unless a project name is already present in the conversation context.
2. **Query the task connector** – Use the `tasks/list` API to fetch all tasks where `status = "open"` for the selected project. See the connector query reference at `reference/connector-queries.md`.
3. **Aggregate** – Group tasks by assignee and priority, counting how many are overdue.
4. **Generate output** – Return a markdown table with columns `Assignee`, `# Open`, `# Overdue`, and a short narrative summary.

5. **Guardrails** –  
   - *Read-only*: Do not modify any task fields.  
   - *Privacy*: Do not expose task descriptions that contain confidential information; redact if needed.

## Reference files

- [reference/connector-queries.md](reference/connector-queries.md) – API details for the task connector.
- [reference/gotchas.md](reference/gotchas.md) – Common failure modes for list-type queries.

```

## Leveraging Templates and Reference Files

For **data-centric skills** involving warehouse queries or analytics, start with the generic skill template located at:

[`data/skills/data-context-extractor/references/skill-template.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/data-context-extractor/references/skill-template.md)

This template provides placeholders for SQL dialects, metric definitions, and data source configurations that you replace with concrete values.

For skills integrating external APIs (such as QuickBooks, PayPal, or Zoom), reference the connector pattern exemplified in:

[`small-business/skills/tax-season-organizer/reference/connector-queries.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/tax-season-organizer/reference/connector-queries.md)

This file demonstrates how to document API endpoints, authentication requirements, and specific query parameters.

## Key Files in the Repository

- **[`data/skills/data-context-extractor/references/skill-template.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/data-context-extractor/references/skill-template.md)** – Reusable boilerplate for data-analysis skills
- **[`small-business/skills/tax-season-organizer/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/tax-season-organizer/SKILL.md)** – Complete production example showing trigger phrases, workflow steps, and guardrails (lines 97-100 contain the safety instructions)
- **[`small-business/skills/tax-season-organizer/reference/connector-queries.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/tax-season-organizer/reference/connector-queries.md)** – Reference implementation for external API integration
- **[`partner-built/zoom-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/.claude-plugin/plugin.json)** – Example plugin manifest showing top-level registration

## Summary

Defining new skills for Anthropic's Knowledge Work plugins follows a straightforward markdown-driven workflow:

- Skills are self-contained [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files living under a plugin's `skills/` directory
- YAML front-matter defines the skill's name and description for slash-commands
- The markdown body encodes triggers, numbered workflow steps, and safety guardrails
- Reference files in a `reference/` subdirectory document API specifics and failure modes
- The runtime auto-discovers skills at load time with no registration required

## Frequently Asked Questions

### What is the minimum required structure for a SKILL.md file?

A valid [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) requires YAML front-matter containing `name` and `description` fields, followed by markdown sections defining at minimum a **Trigger** (how Claude recognizes when to use the skill) and a **Workflow** (the numbered steps to execute). Guardrails and reference files are optional but recommended for production skills.

### Do I need to register my new skill in a plugin manifest?

No. While the plugin requires a [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) manifest at the root level (as seen in `partner-built/zoom-plugin/`), individual skills are auto-discovered. The runtime recursively walks the `skills/` directory tree at load time and parses every [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file it encounters.

### Can I create skills that interact with external APIs?

Yes. Skills can reference connector-specific documentation placed in a `reference/` subdirectory within the skill folder. For example, the tax-season organizer skill at `small-business/skills/tax-season-organizer/` uses [`reference/connector-queries.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/reference/connector-queries.md) to document QuickBooks and PayPal API interactions, which the skill invokes during its workflow steps.

### Where should data-analysis skills be placed?

Data-centric skills should be created under the `data/skills/` directory, utilizing the generic skill template at [`data/skills/data-context-extractor/references/skill-template.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/data-context-extractor/references/skill-template.md). This template provides specialized placeholders for SQL queries, warehouse connections, and metric definitions appropriate for analytical workflows.