Skills Distribution for Claude: Filling the Gap Anthropic Left Open

Executive Summary

Anthropic provides a directory — ~/.claude/skills/ — where skill files define how Claude should behave in specific domains. The documentation says “place your skill files here.” For a single developer, that is sufficient. For a team, it is a distribution problem with no prescribed answer.

This paper compares three approaches to filling that gap: manual copy, MCP-bundled file distribution (our current solution), and Windows network infrastructure. We also briefly describe a fourth approach — skills as MCP tools — that we tried and abandoned.

1. The Gap: A Directory With No Delivery Mechanism

Claude Code loads skill files from ~/.claude/skills/ at conversation start. Project skills live in .claude/skills/ at the repo root. Claude.ai reads from /mnt/skills/user/. In every case, the mechanism is the same: a directory on the local filesystem with Markdown files in it.

The filesystem is the delivery mechanism. But how do the files get there? Anthropic does not prescribe this. For a 50-line workflow shared between two developers, a Slack message with a file attachment works. For a 500-line procedure with tax rules, item codes, and contract edge cases — distributed to ten employees, some using Claude Code, others Claude.ai — the problem is real.

The problem decomposes into three sub-problems:

• Initial distribution. How does the skill reach a new employee’s machine?
• Updates. When the skill changes, how does the change reach all users?
• Version sync. When a skill references an MCP tool by name, how do you ensure that tool exists in the installed version?

2. What We Tried First: Skills as MCP Tools

Our first approach was elegant in theory. We implemented three MCP tools — list_skills, get_skill, and get_skill_detail — that served skill content on demand with tiered loading. The compact summary loaded first (~500 tokens). Detailed sections loaded only when requested. Intellectual property was protected inside compiled JavaScript.

In practice, this approach failed for a simple reason: the iteration loop. Every skill edit — a corrected tax rule, an adjusted reference format, a new edge case — required rebuilding the MCP server, republishing the npm package, and restarting Claude Desktop. No shortcut existed. TypeScript string constants are immutable after compilation.

For a stable, frozen product, this might be acceptable. For skills under active development — where you are refining rules over weeks of real production use — it is a dealbreaker. We abandoned this approach after two weeks.

3. What Works: MCP-Bundled File Distribution

The solution we use now is simpler. Skills are Markdown files stored in the MCP server repository, in a skills/ directory. At build time, they are copied into the output directory. On MCP server startup, they are copied to ~/.claude/skills/ on the local machine.

The entire distribution mechanism fits in a single function:

// src/helpers/install-skills.ts
import { copyFileSync, existsSync, mkdirSync, readdirSync } from "fs";
import { homedir } from "os";
import { join } from "path";

export function installSkills(): void {
  const srcDir = join(__dirname, "..", "claude-skills");
  const destDir = join(homedir(), ".claude", "skills");
  if (!existsSync(srcDir)) return;
  const files = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
  if (files.length === 0) return;
  mkdirSync(destDir, { recursive: true });
  for (const file of files) {
    copyFileSync(join(srcDir, file), join(destDir, file));
  }
}

The server entry point calls installSkills() before registering MCP tools. When an employee runs npx @dibblee/dibblee-xero-core, skills are installed automatically. When the package is updated via npm update, skills are replaced on next startup.

4. The Enterprise Alternative: Windows Network Infrastructure

For organisations with Active Directory-joined workstations, Windows already has mature file distribution mechanisms: network shares (UNC paths), Group Policy Objects (GPO), login scripts, and SCCM/Intune. Any of these can place files into a user’s ~/.claude/skills/ directory.

This approach makes sense when the organisation already has the infrastructure, the IT team manages software deployments, and all workstations are domain-joined. It has real advantages: updates require no build step, no Claude Desktop restart, and security group targeting enables granular permissions (accounting skills for accounting, procurement skills for purchasing).

The downside: skills and MCP tools are decoupled. IT deploys skill files. npm deploys the MCP server. There is no guarantee that the skill version matches the server version. Additionally, this approach only works on Windows — employees on macOS or Linux need a separate distribution mechanism.

5. Comparison

6. When to Use Which Approach

• Single developer, simple skills. Manual copy. One file in ~/.claude/skills/. Nothing more.
• Team, skills coupled to MCP tools. MCP-bundled distribution. Skills travel with the tools. Version sync is automatic. Local edits are possible during development.
• Large org, existing AD, skills independent of tools. Windows network infrastructure. IT manages deployment. Security group targeting is built-in. But version sync between skills and tools is not guaranteed.
• Frozen skills, IP protection critical. Skills as MCP tools. The only approach that genuinely protects content. But only if the content changes rarely.

7. Build Pipeline Detail

The complete mechanism involves two coordinated steps in package.json and the server entry point:

// package.json — build script
"build": "tsc && shx chmod +x dist/*.js && shx cp -r skills dist/claude-skills"

// src/index.ts — server entry point
import { installSkills } from "./helpers/install-skills.js";

async function main() {
  installSkills();  // copy skills before anything else
  const server = XeroMcpServer.GetServer();
  const factory = new ToolFactory(server);
  factory.registerAll();
  // ... connect to stdio transport
}

The shx command ensures cross-platform compatibility for file operations. The skills/ directory in the repository contains the source Markdown files. They are copied to dist/claude-skills/ during build, then to ~/.claude/skills/ at runtime.

Skill files use standard YAML frontmatter:

---
name: dnd-xero-workflow
description: Parse DND procurement contracts and create invoices or
  purchase orders in Xero with correct tax mapping and item codes
---

## Workflow Steps
1. Receive a DND contract document...

Claude Code reads the name and description from the frontmatter to determine when to invoke the skill. The body is loaded only when the model decides the skill is relevant to the current task.

Conclusion

Anthropic built a powerful skills system with a simple deployment assumption: one developer, one filesystem. The system works remarkably well in that context. But the moment you have two people who need to use the same skill, the distribution gap appears.

We tried the elegant approach. It was too rigid. We now use the pragmatic one: bundle skills with the MCP server, copy them to the local filesystem on startup, and let developers edit locally when they need to iterate. Fifteen lines of Node.js. No framework. No infrastructure.

For organisations with existing Windows infrastructure, network shares and GPOs are a viable alternative — particularly for skills that are not coupled to specific MCP tools. But for most teams, the npm package is the right delivery mechanism. It is already there. It works on every platform. And it syncs skills with the tools they reference.