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

Defining a new skill for Anthropic's Knowledge Work plugins requires creating a 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 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 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 file containing YAML front-matter followed by a structured markdown body:

---
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)
• Gotchas: Common failure modes and edge cases (e.g., 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 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:

---
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

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

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 – Reusable boilerplate for data-analysis skills
• 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 – Reference implementation for external API integration
• 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 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 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 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 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 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. This template provides specialized placeholders for SQL queries, warehouse connections, and metric definitions appropriate for analytical workflows.

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