What Are Key Skill Files in the Knowledge Work Plugins Repository?

Key skill files are plain-text markdown documents stored in each plugin's skills/ directory that encode domain-specific workflows, terminology, and organizational context, enabling Claude to function as a specialized expert for specific business roles.

The anthropics/knowledge-work-plugins repository provides a modular system for transforming Claude into role-specific specialists through specialized plugins. At the heart of this architecture are key skill files—often named SKILL.md—that serve as the primary mechanism for injecting proprietary knowledge and company-specific processes into Claude's reasoning.

What Are Key Skill Files?

Key skill files reside within the skills/ subdirectory of each plugin folder (e.g., plugins/sales/skills/, plugins/product-management/skills/). These files contain structured markdown instructions that teach Claude how to perform specific tasks for a given domain. According to the repository's README.md (lines 71-73), these files exist so you can "Drop your terminology, org structure, and processes into skill files so Claude understands your world."

The small-business/README.md (line 144) reinforces this purpose, stating that skill files allow you to "Drop your industry, products, customers, and processes" into the system. This file-based approach means expertise is stored as readable text rather than code, making the repository accessible to domain experts who may not be developers.

Why Key Skill Files Matter

Domain Knowledge Carriers

Skill files encode the precise terminology, best-practice workflows, and step-by-step instructions that Claude must understand to be helpful. When a user invokes a command, the engine scans the relevant skill files and extracts guidance to generate contextually appropriate responses. This makes Claude act as a knowledgeable partner rather than a generic assistant.

Customization Hooks

These files serve as the primary interface for tailoring generic plugins to specific organizations. By editing markdown in plugins/<role>/skills/, you inject company-specific language, organizational structure, and standard operating procedures directly into Claude's context window. This customization happens without modifying the underlying plugin code.

File-Based, No Code Required

Because skill files use standard markdown, you can edit, version-control, and share them using familiar text editors and Git workflows. The plugin runtime loads these files at execution time, meaning changes take effect immediately without redeployment or restarts.

Working with Key Skill Files

Creating a Skill File

To add new expertise, create a markdown file under the appropriate plugin's skills/ directory. The file typically includes a header and numbered workflow steps:

# plugins/sales/skills/lead-qualification/SKILL.md

## Lead Qualification

1. Pull the lead's recent activity from the CRM (connector `salesforce`).
2. Check for recent engagement signals (email opens, website visits).
3. Score the lead using our internal weighting system.
4. Summarize the qualification rationale for the sales rep.

Linking Skills to Commands

The .claude-plugin/plugin.json manifest maps slash commands to specific skill files. When you define a command, you reference the skill identifier that corresponds to the subdirectory name:

{
  "name": "sales",
  "commands": {
    "qualify-lead": {
      "description": "Run lead qualification workflow",
      "skill": "lead-qualification"
    }
  }
}

When a user runs /sales:qualify-lead, Claude automatically loads lead-qualification/SKILL.md and follows the steps defined there.

Customizing for Your Organization

To adapt a generic skill to your specific tools and processes, edit the markdown to reflect your actual technology stack. For example, if your organization uses HubSpot and LinkedIn rather than generic web analytics, modify the file:

@@ -2,7 +2,7 @@
-2. Check for recent engagement signals (email opens, website visits).
+2. Check for recent engagement signals (email opens, HubSpot website visits, and LinkedIn profile views).

Because the system reads these files at runtime, the updated workflow applies immediately to the next command invocation.

Key Repository Files

Understanding the relationship between skill files and configuration files is essential for effective customization:

• README.md (lines 71-73): Contains the core documentation explaining the skill file concept and its role in providing company context to Claude.

• plugins/<role>/skills/SKILL.md: The actual knowledge carriers containing domain expertise and workflow instructions for specific functional areas like sales, finance, or product management.

• .claude-plugin/plugin.json: Declares the plugin metadata and maps command identifiers to skill file locations, serving as the bridge between user commands and skill content.

• .mcp.json: Defines connector configurations (e.g., CRM, data warehouse) that skill files reference when specifying external data sources.

Summary

• Key skill files are markdown documents in plugins/<role>/skills/ that store domain-specific expertise for Claude.
• They function as customization hooks, allowing organizations to inject proprietary terminology and workflows without writing code.
• The .claude-plugin/plugin.json manifest links slash commands to specific skill files by subdirectory name.
• Changes to skill files take effect immediately because the runtime loads them at execution time.
• Supporting files like .mcp.json provide connector configurations that skills reference for external data access.

Frequently Asked Questions

What file format do key skill files use?

Key skill files use plain-text markdown (.md files), often specifically named SKILL.md. This format allows for structured headers, numbered lists, and formatting while remaining human-readable and editable in any text editor.

How do I link a key skill file to a Claude command?

You link skills through the .claude-plugin/plugin.json file by specifying the skill property in the command definition. The value should match the subdirectory name containing your SKILL.md file within the skills/ folder.

Do I need to restart Claude after editing a key skill file?

No. Because the knowledge-work-plugins system loads markdown files at execution time, any changes to skill files are reflected immediately in subsequent command invocations without requiring restarts or redeployment.

Where should I place custom key skill files?

Place custom skill files in the appropriate plugin's skills/ directory, typically at plugins/<role>/skills/<skill-name>/SKILL.md. The <skill-name> directory should match the identifier referenced in the plugin.json command configuration to ensure proper mapping.

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