Skillsmith: napište AI skill jednou, exportujte všude

Shrnutí

Každý AI coding assistant (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex) používá jiný formát pro "skills" nebo "rules" — jiné YAML frontmatter, jiné umístění souborů, jiné aktivační mechanismy. Pokud váš tým používá víc než jeden nástroj, skončíte s 5 kopiemi stejných coding standards, které se nevyhnutelně rozjedou. Vytvořil jsem Skillsmith — open-source CLI nástroj, který vám umožní napsat skill jednou a exportovat ho do jakéhokoli formátu jedním příkazem.

Problém: pět formátů pro jedno pravidlo

V typickém dev týmu má každý svůj oblíbený AI nástroj. Jeden používá Claude Code, druhý žije v Cursoru, třetí přešel na Windsurf, zbytek je na Copilotu. Každý z těch nástrojů má svůj vlastní formát:

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

Všechny používají Markdown. Všechny mají YAML frontmatter. Ale každý jinak. Když chcete aktualizovat TypeScript standard, musíte to udělat na pěti místech. Nevyhnutelně se zapomene jedno nebo dvě, a za měsíc máte v každém nástroji jiná pravidla.

Řešení: jeden univerzální formát

Skillsmith definuje jednoduchý univerzální formát — skill.md soubor s YAML frontmatter, který pokrývá všechny vendor-specific koncepty:

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

Vaše instrukce pro AI asistenta...

Pět polí, které se inteligentně mapují na nativní koncepty každého vendora:

Jak to funguje

Nainstalujete skill jedním příkazem:

# Export do jednoho vendora
npx skillsmith add ./typescript-standards -a claude

# Export do všech vendorů najednou
npx skillsmith add ./typescript-standards -a all

Skillsmith přečte váš skill.md, vybere správný adapter, přeloží frontmatter, vytvoří soubor na správném místě a zapíše záznam do .skillsmith.json lockfilu.

Ten lockfile je klíčový — trackuje, odkud skill přišel a pro které vendory byl nainstalován. Když aktualizujete zdrojový skill, stačí:

npx skillsmith sync

A všechno se přeexportuje.

Workflow pro organizaci

Skutečná síla Skillsmithe se projeví, když centralizujete skills do sdíleného repozitáře:

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

Jeden repozitář, jeden zdroj pravdy. Instalace do projektu:

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

Automatický sync přes CI

Přidejte GitHub Action, který jednou týdně pullne nejnovější skills a otevře 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 se aktualizují automaticky. PR ukazuje přesně co se změnilo. Review a merge.

5 nejčastějších chyb při sdílení AI skills

1. Duplikace místo sdílení. Zkopírovat .cursorrules do nového projektu je snadné. Udržovat ho aktuální ve 20 projektech už ne. Centralizujte zdroj.

2. Ignorování vendor-specific rozdílů. Cursor alwaysApply: true a Windsurf trigger: always_on znamenají totéž, ale zapsané jinak. Ruční překlad je náchylný k chybám.

3. Žádný tracking co je nainstalované. Bez lockfilu nevíte, které skills jsou v projektu, odkud přišly, ani jestli jsou aktuální.

4. Aktualizace jednoho vendora a zapomenutí na ostatní. Tým na Cursoru aktualizuje rule, ale tým na Claude Code to nezjistí. Skills driftují.

5. Over-engineering řešení. Plugin systém, schéma validace, grafové závislosti — pro 5 vendorů s Markdown soubory stačí adapter pattern a simple Map.

Architektura

Skillsmith je TypeScript CLI s minimálními dependencies (jen gray-matter pro frontmatter parsing). Architektura je jednoduchá:

• Parser — přečte skill.md, extrahuje frontmatter + body
• Adaptery — jeden per vendor, každý implementuje buildFrontmatter() a getOutputPath()
• Registry — Map<VendorName, Adapter>, 5 záznamů
• Lockfile — .skillsmith.json trackuje source → vendor mapování

Přidání nového vendora = jeden soubor v src/adapters/ + jeden řádek v registry.

Často kladené otázky

Jak se to liší od AGENTS.md?

AGENTS.md je univerzální standard pro AI coding instructions — podporuje ho 8+ nástrojů. Skillsmith ho podporuje jako jeden z výstupních formátů. Ale AGENTS.md nepokryje vendor-specific funkce jako Claude allowed-tools nebo Windsurf trigger modes.

Funguje to i na existující pravidla?

Skillsmith momentálně funguje jednosměrně — z univerzálního formátu do vendor-specific. Import existujících .cursorrules nebo SKILL.md zpět do univerzálního formátu je plánovaný.

Musím commitovat vygenerované soubory?

Ano, doporučujeme commitovat vygenerované vendor-specific soubory. Jsou malé, čitelné a diff v PR jasně ukazuje, co se změnilo.

Zvládne to resources (skripty, reference)?

Ano, ale jen pro Claude Code, který jako jediný vendor podporuje bundlované resources. Ostatní adaptery vypíšou warning.

Projekt najdete na GitHubu. Budu rád za hvězdičku, issues i PR.