How to Reuse Existing Skill Definitions in knowledge-work-plugins: A Complete Guide

Yes, the Knowledge Work Plugins framework is explicitly designed for reusing skill definitions through the Data-Context Extractor's Iteration mode and shared reference file patterns.

The anthropics/knowledge-work-plugins repository provides a modular architecture where skills are self-contained folders that can be imported, extended, and referenced across multiple projects. Understanding how to leverage existing definitions prevents duplication and ensures consistency across your knowledge base.

What Constitutes a Skill Definition?

A skill in this framework is a folder containing a SKILL.md manifest file and a collection of reference files that define entities, metrics, table schemas, and domain-specific logic. According to the source code in data/skills/data-context-extractor/SKILL.md, skills function as portable knowledge packages that expose two primary operational modes: Bootstrap (creating from scratch) and Iteration (loading existing definitions).

The reference files typically include:

• Entity disambiguation tables
• Metric formulas and calculations
• Standard filters and queries
• Domain-specific documentation

Methods to Reuse Existing Skill Definitions

Using Data-Context Extractor Iteration Mode

The canonical approach to reuse existing skill definitions is the Iteration mode implemented in data/skills/data-context-extractor/SKILL.md. This mode loads the current SKILL.md and its associated reference files, prompts you with targeted questions about what to add or modify, and writes new reference files back into the same folder structure.

When you trigger Iteration mode with commands like "Add context about marketing" or "Improve the finance reference," the system preserves the existing knowledge base while appending new domain-specific context.

Sharing Reference Files via Relative Paths

Many skills in the repository, such as the small-business Ticket Deflector (small-business/skills/ticket-deflector/SKILL.md), demonstrate how to share definitions by referencing markdown files via relative paths like reference/gotchas.md or reference/examples/...md. By pointing multiple skills at the same reference files, you create a single source of truth for entity definitions and business logic.

The Create Cowork Plugin skill (cowork-plugin-management/skills/create-cowork-plugin/SKILL.md) extends this pattern by importing existing agent definitions from shared agents/ folders, allowing you to reuse entire agent configurations across different plugin contexts.

Step-by-Step Workflow for Extending a Skill

Follow this process to safely reuse and extend any existing skill definition:

1. Locate the existing skill folder (e.g., data-context-extractor/ or any specific skill directory you want to extend).

2. Load the skill using the Data-Context Extractor's Iteration mode, or manually copy the folder structure to create a derivative work.

3. Add new reference files in the references/ directory (e.g., references/<domain>.md) or modify existing ones to update definitions.

4. Re-package the skill as a zip archive or commit the changes to version control. Downstream skills that import these reference files will automatically receive updates.

Practical Implementation Examples

Loading an Existing Skill in Iteration Mode

name: data-context-extractor
description: |
  Load an existing skill and add a new domain.
  → Use the "Iteration Mode" triggers:
  - "Add context about marketing"
  - "Improve the finance reference"

CLI Invocation Pattern

$ claude-plugin run data-context-extractor \
    --trigger "Add context about marketing" \
    --skill-path ./my-company-data-analyst/

Adding a Shared Reference File

Create domain-specific reference documentation that other skills can import:

# my-company-data-analyst/references/marketing.md

| Term | Definition | Notes |
|------|------------|-------|
| Campaign | A marketing campaign run in HubSpot | Used for ARR uplift calculations |

Updating Skill Navigation

The Data-Context Extractor automatically updates the SKILL.md navigation table to include new reference files:

---
name: my-company-data-analyst
---

## Knowledge Base Navigation

| Domain | Reference File | Use For |
|--------|----------------|---------|
| Marketing | `references/marketing.md` | Campaign-level metrics |

Packaging for Distribution

$ zip -r my-company-data-analyst.zip my-company-data-analyst/

Once packaged, any skill importing references/marketing.md (such as sales-brief or margin-analyzer) will instantly access the updated definitions.

Critical Files for Reuse Implementation

Understanding these specific source files helps you implement reuse patterns correctly:

• data/skills/data-context-extractor/SKILL.md — Defines the Bootstrap and Iteration modes; the official entry point for loading and extending existing skills.

• data/skills/data-context-extractor/references/skill-template.md — Provides the required sections (entity disambiguation, metrics, filters) that serve as reusable templates across skills.

• small-business/skills/ticket-deflector/SKILL.md — Demonstrates practical usage of shared reference/gotchas.md and reference/examples/...md files.

• cowork-plugin-management/skills/create-cowork-plugin/SKILL.md — Shows how to import existing agent definitions from shared folders for cross-plugin reuse.

• partner-built/zoom-plugin/.mcp.json — Illustrates how MCP server definitions can be referenced by multiple Zoom-related skills without duplication.

Summary

• Iteration mode in the Data-Context Extractor is the primary mechanism for reusing and extending existing skill definitions.
• Reference files can be shared across multiple skills via relative paths, creating reusable knowledge components.
• The skill structure (SKILL.md plus references/ folder) supports both inheritance and composition patterns.
• Updates to shared reference files automatically propagate to all dependent skills that import them.
• The repository contains concrete examples in data-context-extractor/, ticket-deflector/, and create-cowork-plugin/ demonstrating various reuse patterns.

Frequently Asked Questions

How do I know if a skill can be safely extended?

Check for the presence of a SKILL.md file and a references/ directory. According to the patterns in data/skills/data-context-extractor/SKILL.md, any skill following this structure supports Iteration mode. Skills that explicitly document their reference file dependencies (like those in small-business/skills/ticket-deflector/) are designed specifically for reuse and extension.

Can multiple skills reference the same entity definitions simultaneously?

Yes. By placing entity disambiguation tables and metric definitions in shared reference files (e.g., references/marketing.md) and having multiple SKILL.md files point to those paths, you create a single source of truth. Any update to the shared file immediately affects all skills that import it, ensuring consistency across your knowledge base.

What is the difference between Bootstrap and Iteration modes?

Bootstrap mode initializes a completely new skill folder with a fresh SKILL.md and template reference files. Iteration mode, as implemented in data/skills/data-context-extractor/SKILL.md, loads an existing skill's current state, preserves its accumulated knowledge, and adds new reference files or updates existing ones based on your inputs. Use Bootstrap for new projects, Iteration for extending existing work.

Do I need to manually update navigation tables when adding reference files?

No. When using the Data-Context Extractor's Iteration mode, the system automatically updates the Knowledge Base Navigation table in SKILL.md to include new reference files. If you are manually copying files, you should update the navigation table to maintain the skill's internal documentation standards, though the skill will function as long as the relative paths in your logic remain correct.

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