How Skills Are Organized Within the Plugin Structure in Claude Knowledge Work Plugins

Skills in the knowledge-work-plugins repository are organized as self-contained Markdown files within plugin-specific skills/ directories, where each skill is defined by a SKILL.md file containing YAML front-matter for metadata and Markdown content for workflow instructions.

The anthropics/knowledge-work-plugins repository implements a file-based architecture that keeps domain-specific capabilities organized and version-controllable. Understanding how different skills are organized within the plugin structure enables developers to extend existing plugins or build custom internal tools without writing executable code.

Plugin Directory Structure Overview

Every plugin follows a consistent four-component layout at the repository root. This separation of concerns ensures that capabilities, configuration, and command definitions remain modular:

plugin-name/
├── .claude-plugin/plugin.json      # Manifest that registers the plugin

├── .mcp.json                       # Connector configuration for external tools

├── commands/                       # Explicit slash-commands you invoke

└── skills/                         # Domain-specific knowledge assets

The .claude-plugin/plugin.json file registers the plugin with Claude and enumerates its available commands and skills. For example, sales/.claude-plugin/plugin.json defines the sales plugin manifest and its registered capabilities.

The Skills Directory Structure

The skills/ directory contains the bulk of a plugin’s intelligence. Each skill is a Markdown file ending in SKILL.md that lives within a folder named after the skill identifier.

Skill Metadata in YAML Front-Matter

Every SKILL.md file begins with a YAML front-matter block that defines three critical fields:

• name – The identifier used in the slash-command (e.g., write-query, pipeline-review).
• description – A concise sentence describing when the skill should be invoked.
• argument-hint – A short hint shown to the user for required parameters.

Below the front-matter, the file contains Markdown instructions that define the workflow, usage examples, and expected output formats.

Skill Organization by Functional Domain

Skills are grouped by the functional area of the plugin. The repository uses a flat structure inside each skills/ folder, though sub-folders are permitted for complex domains.

Sales Plugin Skills

Located in sales/skills/, this directory contains capabilities for revenue operations. The pipeline-review skill, defined in sales/skills/pipeline-review/SKILL.md, analyzes pipeline health and takes a team identifier as an argument:

/pipeline-review west-coast-team

Small Business Plugin Skills

The small-business/skills/ directory contains operational tools for SMB workflows. The ticket-deflector skill at small-business/skills/ticket-deflector/SKILL.md routes support tickets to appropriate teams:

/ticket-deflector "Customer reports login failure on mobile app"

Some plugins use nested sub-folders when domains contain multiple related assets, such as small-business/skills/tax-season-organizer/, though each leaf node still contains a single SKILL.md file.

Data Plugin Skills

The data/skills/ directory houses analytics capabilities. The write-query skill in data/skills/write-query/SKILL.md generates optimized SQL from natural language descriptions:

/write-query Count of orders by status for the last 30 days

This skill connects to databases via the connector defined in the plugin's .mcp.json configuration.

How Claude Resolves and Executes Skills

When a user types a slash command, Claude executes a four-step resolution process against the plugin structure:

1. Parse the command name (e.g., write-query).
2. Locate the matching SKILL.md file in the plugin's skills/ directory.
3. Load the YAML front-matter to understand arguments and description.
4. Execute the workflow defined in the skill file, prompting for missing details if necessary.

Because skills are pure Markdown, they can be version-controlled, reviewed via pull requests, and customized for organizational terminology directly in the repository without deploying code.

Connector Configuration Integration

Skills often interact with external tools through the Model Context Protocol (MCP). The .mcp.json file at the plugin root maps skill requirements to external APIs. For instance, sales/.mcp.json configures CRM and calendar connectors that the pipeline-review skill invokes when analyzing deal flow.

Summary

• File-based organization: Each skill is a standalone SKILL.md file within a plugin's skills/ directory.
• Metadata-driven: YAML front-matter defines the skill name, description, and argument hints that Claude uses for command discovery.
• Domain grouping: Plugins like sales, small-business, and data organize skills by functional area, with optional sub-folders for complex domains.
• Zero-code customization: Skills are Markdown-only assets that support version control and organizational customization without code changes.
• Manifest registration: The .claude-plugin/plugin.json file registers available skills, while .mcp.json configures external tool connectors.

Frequently Asked Questions

How does Claude know which skill to execute when I type a slash command?

Claude parses the command identifier (the text after the slash) and searches all plugin skills/ directories for a SKILL.md file with a matching name field in its YAML front-matter. Once found, it loads the metadata and executes the workflow defined in the Markdown content.

Can I organize skills into subdirectories within the skills folder?

Yes. While the standard pattern places SKILL.md files immediately inside skills/, you can create subdirectories for related capabilities. For example, small-business/skills/tax-season-organizer/ contains grouped assets while still following the one-SKILL.md-per-capability rule.

What is the difference between the commands/ folder and the skills/ folder?

The commands/ directory typically contains explicit slash-command definitions, while the skills/ directory houses the domain-specific knowledge assets and workflow instructions. The SKILL.md files in skills/ contain the actual implementation logic written in Markdown, whereas commands/ may define the command structure and routing.

Do I need to modify the plugin manifest when adding a new skill?

Yes. When you add a new SKILL.md file to a plugin's skills/ directory, you should ensure the .claude-plugin/plugin.json manifest is updated to register the skill. This manifest tells Claude which capabilities are available in the plugin and maps command names to their respective skill files.

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