Skillsmith: Write AI Skills Once, Export Everywhere

Summary

Every AI coding assistant (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex) uses a different format for "skills" or "rules" — different YAML frontmatter, different file locations, different activation mechanisms. If your team uses more than one tool, you end up with 5 copies of the same coding standards that inevitably drift apart. I built Skillsmith — an open-source CLI tool that lets you write a skill once and export it to any format with a single command.

The Problem: Five Formats for One Rule

In a typical dev team, everyone has their favorite AI tool. One person uses Claude Code, another lives in Cursor, someone else switched to Windsurf, and the rest are on Copilot. Each of those tools has its own format:

• Claude Code — .claude/skills/{name}/SKILL.md with frontmatter name, description, allowed-tools
• Cursor — .cursor/rules/{name}/RULE.md with frontmatter description, globs, alwaysApply
• Windsurf — .windsurf/rules/{name}.md with frontmatter trigger (always_on, manual, model_decision, glob)
• GitHub Copilot — .github/instructions/{name}.instructions.md with frontmatter applyTo
• Codex — AGENTS.md with ## {name} sections

They all use Markdown. They all have YAML frontmatter. But each one is slightly different. When you want to update your TypeScript standards, you have to do it in five places. Inevitably, you forget one or two, and within a month each tool has different rules.

The Solution: One Universal Format

Skillsmith defines a simple universal format — a skill.md file with YAML frontmatter that covers all vendor-specific concepts:

---
name: typescript-standards
description: Enforce TypeScript coding standards
globs: "**/*.ts,**/*.tsx"
activation: auto
allowed-tools: "Read Grep"
---

Your instructions for the AI assistant...

Five fields that intelligently map to each vendor's native concepts:

How It Works

Install a skill with one command:

# Export to a single vendor
npx skillsmith add ./typescript-standards -a claude

# Export to all vendors at once
npx skillsmith add ./typescript-standards -a all

Skillsmith reads your skill.md, picks the right adapter, translates the frontmatter, creates the file in the right location, and writes a record to the .skillsmith.json lockfile.

That lockfile is the key — it tracks where a skill came from and which vendors it was installed for. When you update the source skill, just run:

npx skillsmith sync

And everything gets re-exported.

Organization Workflow

The real power of Skillsmith shows when you centralize skills in a shared repository:

your-org/ai-skills/
  skills/
    typescript-standards/skill.md
    code-review/skill.md
    react-patterns/skill.md
    security-rules/skill.md

One repository, one source of truth. Install into a project:

for skill in ../ai-skills/skills/*/; do
  npx skillsmith add "$skill" -a all
done

Automated Sync via CI

Add a GitHub Action that pulls the latest skills weekly and opens a PR:

name: Sync AI Skills
on:
  schedule:
    - cron: '0 8 * * 1'
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
        with:
          repository: your-org/ai-skills
          path: .ai-skills
      - run: npm install -g skillsmith
      - run: npx skillsmith sync
      - uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: sync AI coding skills"
          branch: chore/sync-ai-skills

Skills update automatically. The PR shows exactly what changed. Review and merge.

5 Most Common Mistakes When Sharing AI Skills

1. Duplication instead of sharing. Copying .cursorrules into a new project is easy. Keeping it up to date across 20 projects is not. Centralize the source.

2. Ignoring vendor-specific differences. Cursor alwaysApply: true and Windsurf trigger: always_on mean the same thing, but written differently. Manual translation is error-prone.

3. No tracking of what's installed. Without a lockfile, you don't know which skills are in a project, where they came from, or whether they're current.

4. Updating one vendor and forgetting the others. The Cursor team updates a rule, but the Claude Code team doesn't notice. Skills drift.

5. Over-engineering the solution. Plugin systems, schema validation, dependency graphs — for 5 vendors with Markdown files, an adapter pattern and a simple Map is enough.

Architecture

Skillsmith is a TypeScript CLI with minimal dependencies (just gray-matter for frontmatter parsing). The architecture is straightforward:

• Parser — reads skill.md, extracts frontmatter + body
• Adapters — one per vendor, each implements buildFrontmatter() and getOutputPath()
• Registry — Map<VendorName, Adapter>, 5 entries
• Lockfile — .skillsmith.json tracks source → vendor mappings

Adding a new vendor = one file in src/adapters/ + one line in the registry.

FAQ

How does this differ from AGENTS.md?

AGENTS.md is a universal standard for AI coding instructions — supported by 8+ tools. Skillsmith supports it as one of its output formats. But AGENTS.md doesn't cover vendor-specific features like Claude's allowed-tools or Windsurf's trigger modes.

Does it work with existing rules?

Skillsmith currently works one-way — from the universal format to vendor-specific. Importing existing .cursorrules or SKILL.md back into the universal format is planned.

Should I commit the generated files?

Yes, we recommend committing the generated vendor-specific files. They're small, readable, and the diff in a PR clearly shows what changed.

Does it handle resources (scripts, references)?

Yes, but only for Claude Code, which is the only vendor that supports bundled resources. Other adapters emit a warning.

Find the project on GitHub. Stars, issues, and PRs are all welcome.