Jak stworzyć skill dla Claude i przenieść go na inne konto

Problem

Claude od jakiegoś czasu wspiera skille — paczki z instrukcjami i opcjonalnymi zasobami (skrypty, szablony, dokumentacja referencyjna), które ładują się tylko wtedy, gdy są potrzebne. Zamiast wpychać wszystko do system promptu albo kopiować ten sam zestaw instrukcji do każdej rozmowy, definiujesz workflow raz i Claude sięga po niego sam, gdy temat pasuje.

Problem pojawia się, kiedy skill już działa na jednym koncie (np. firmowym Claude Code) i chcesz go przenieść na drugie konto, na inne urządzenie albo udostępnić zespołowi. Trzeba wiedzieć, co dokładnie spakować, jak, i gdzie to wgrać po drugiej stronie.

Niżej cały proces — od pustego katalogu do działającego .skill zainstalowanego na drugim koncie.

Anatomia skilla

Skill to po prostu katalog z jednym wymaganym plikiem SKILL.md i opcjonalnymi zasobami:

moj-skill/
├── SKILL.md          # wymagany — frontmatter YAML + instrukcje w Markdown
├── scripts/          # opcjonalne — skrypty wykonywalne (Python, bash itp.)
├── references/       # opcjonalne — dokumentacja doczytywana w razie potrzeby
└── assets/           # opcjonalne — szablony, ikony, fonty używane w outpucie

Sercem jest SKILL.md. Frontmatter ma dwa wymagane pola: name i description. To description jest mechanizmem wyzwalania — Claude czyta go w każdej rozmowie i decyduje, czy skill pasuje do zapytania użytkownika.

Krok 1: szkielet katalogu

Załóżmy, że chcemy skilla, który generuje wpisy blogowe w określonym formacie (akurat tym, którego używasz). Tworzymy strukturę:

$mkdir -p ~/skills/blog-post-infinityweb
$cd ~/skills/blog-post-infinityweb
$touch SKILL.md

Krok 2: napisanie SKILL.md

Frontmatter musi mieć name i description. Dobry description zawiera co skill robi i kiedy się ma uruchamiać — z konkretnymi frazami użytkownika.

---
name: blog-post-infinityweb
description: Generuje gotowy plik Markdown z wpisem blogowym dla
  serwisu infinityweb.pl na podstawie bieżącej rozmowy. Użyj tego
  skilla zawsze, gdy użytkownik prosi o "wpis na bloga", "post
  blogowy", "artykuł na infinityweb" lub przesyła template z
  frontmatterem zawierającym slug/cat/tags.
---

# Blog Post — infinityweb.pl

Generujesz pojedynczy plik `.md` zgodny z formatem CMS-a infinityweb.pl.

## Format frontmattera

Wymagane pola:
- `slug` — kebab-case, po angielsku
- `title` — po polsku, w cudzysłowie
- `desc` — jedno zdanie, co czytelnik wyniesie
- `cat` — jedna z: frontend, backend, linux, security, ai, prestashop, home assistant
- `tags` — lista 3-5 tagów
- `date` — YYYY-MM-DD

## Styl treści

- Język polski, ton zwięzły i techniczny
- Zaczynaj od sekcji `## Problem`
- Bloki kodu zawsze z określonym językiem (```bash, ```nginx itp.)
- Wyjścia terminala poprzedzaj `$ `
- Używaj calloutów `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`

## Output

Wypisz wyłącznie gotowy plik Markdown jako jeden blok kodu —
bez komentarzy przed ani po.

Kilka zasad, które się sprawdzają:

• Pisz w trybie rozkazującym. "Generujesz X", "Używaj Y" — zamiast "Skill powinien generować X".
• Tłumacz dlaczego. Model lepiej trafia w intencję, gdy wie po co coś robi, niż gdy dostanie samą listę nakazów.
• Trzymaj SKILL.md poniżej ~500 linii. Większe rzeczy wynoś do references/ i wskazuj, kiedy je doczytać.

Krok 3: dodanie zasobów (opcjonalnie)

Jeśli skill robi coś deterministycznego — np. waliduje YAML, konwertuje pliki, generuje boilerplate — wynieś to do scripts/. Claude wykona skrypt zamiast wymyślać logikę za każdym razem.

$mkdir scripts references
$cat > scripts/validate_frontmatter.py <<'EOF'
#!/usr/bin/env python3
"""Waliduje frontmatter wpisu blogowego — sprawdza wymagane pola i kategorię."""
import sys
import yaml
ALLOWED_CATS = {"frontend", "backend", "linux", "security",
                "ai", "prestashop", "home assistant"}
REQUIRED = {"slug", "title", "desc", "cat", "tags", "date"}
def main(path: str) -> int:
    text = open(path, encoding="utf-8").read()
    if not text.startswith("---"):
        print("Brak frontmattera", file=sys.stderr)
        return 1
    fm_raw = text.split("---", 2)[1]
    fm = yaml.safe_load(fm_raw)
    missing = REQUIRED - fm.keys()
    if missing:
        print(f"Brakujące pola: {missing}", file=sys.stderr)
        return 1
    if fm["cat"] not in ALLOWED_CATS:
        print(f"Niedozwolona kategoria: {fm['cat']}", file=sys.stderr)
        return 1
    print("OK")
    return 0
if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))
EOF
$chmod +x scripts/validate_frontmatter.py

W SKILL.md dopisujesz wtedy sekcję typu "Po wygenerowaniu wpisu uruchom scripts/validate_frontmatter.py <plik> żeby sprawdzić poprawność frontmattera" — i Claude będzie to robił sam.

Krok 4: instalacja lokalna i test

Teraz zależy gdzie używasz Claude'a:

Claude Code

Skille żyją w ~/.claude/skills/. Wystarczy skopiować katalog:

$cp -r ~/skills/blog-post-infinityweb ~/.claude/skills/
$ls ~/.claude/skills/
blog-post-infinityweb

Po restarcie sesji Claude Code skill jest widoczny. Sprawdź wpisując np. "Napisz wpis na bloga o tym, jak…" — Claude powinien sam sięgnąć po skill.

Claude.ai (web/desktop)

W aplikacji webowej skille instaluje się przez panel ustawień jako pliki .skill (zip). O tym za chwilę.

Krok 5: pakowanie do .skill

Format .skill to po prostu zip z całym katalogiem skilla (z wykluczeniem __pycache__, node_modules, .DS_Store i podobnych śmieci). Można to zrobić ręcznie:

$cd ~/skills
$zip -r blog-post-infinityweb.skill blog-post-infinityweb \
    -x '*/__pycache__/*' '*.pyc' '*/.DS_Store'
  adding: blog-post-infinityweb/ (stored 0%)
  adding: blog-post-infinityweb/SKILL.md (deflated 52%)
  adding: blog-post-infinityweb/scripts/validate_frontmatter.py (deflated 48%)
$ls -lh blog-post-infinityweb.skill
-rw-r--r-- 1 pawel pawel 2,1K maj  8 14:22 blog-post-infinityweb.skill

Plik .skill można przerzucić przez SCP, wysłać mailem, wrzucić do prywatnego repo — to zwykły zip.

Krok 6: instalacja na drugim koncie

Claude Code (drugie urządzenie)

Najprostsza droga — rozpakuj i wrzuć do katalogu skilli:

$scp blog-post-infinityweb.skill user@drugi-host:~/
$ssh user@drugi-host
$unzip ~/blog-post-infinityweb.skill -d ~/.claude/skills/
$ls ~/.claude/skills/blog-post-infinityweb/
SKILL.md  scripts  references

Claude.ai

W panelu Claude.ai: Settings → Capabilities → Skills → Upload skill i wskazujesz plik .skill. Po chwili skill pojawia się na liście aktywnych. Dostępność tej opcji zależy od planu — na koncie Pro/Team zwykle jest, na Free bywa ograniczona.

Krok 7: weryfikacja po przeniesieniu

Po instalacji warto sprawdzić, czy skill faktycznie się wyzwala. Najprostszy test — zacznij rozmowę, w której pojawia się fraza z description:

$ claude
> Napisz mi wpis na bloga o konfiguracji nginx.

Jeśli Claude w odpowiedzi sięga po SKILL.md i trzyma się formatu — działa. Jeśli odpowiada generycznie, opis prawdopodobnie nie pasuje wystarczająco mocno do zapytania. W takiej sytuacji edytujesz description (im bardziej "popychający" i konkretne frazy, tym lepiej trafia) i pakujesz na nowo.

Co się dzieje pod spodem

Kiedy startujesz rozmowę, Claude dostaje listę dostępnych skilli — ale tylko ich name i description. To metadane (~100 słów na skill), które siedzą w kontekście cały czas. Treść SKILL.md ładuje się dopiero gdy Claude uzna, że temat pasuje. Pliki z references/ doczytywane są jeszcze później, na żądanie z poziomu instrukcji w SKILL.md. Skrypty z scripts/ w ogóle nie muszą trafiać do kontekstu — są wykonywane jako zewnętrzne procesy.

To po prostu lazy loading dla wiedzy specjalistycznej — i właśnie dlatego format jest taki minimalny: katalog z plikami i jeden Markdown z frontmatterem, spakowany jako zip. Żadnej magii, żadnego runtime'u — wystarczy skopiować katalog i Claude widzi nowy skill.