[Intum Dev](https://intum.dev.md) / [Narzędzia AI](https://intum.dev/narzedzia-ai.md)

# [Skills vs MCP - jak agenty AI korzystają z narzędzi](https://intum.dev/narzedzia-ai/skills-vs-mcp-jak-agenty-ai-korzystaja-z-narzedzi.md)

Agenty AI (Claude Code, Cursor, Copilot) mogą korzystać z zewnętrznych usług na dwa sposoby: przez Skills albo przez MCP. Oba podejścia rozwiązują ten sam problem - jak dać agentowi dostęp do narzędzi - ale robią to zupełnie inaczej.

## Porównanie

| --- | Plik .md | Skill (/komenda) | MCP |
|---|---|---|---|
| Co to jest | Zwykły plik Markdown w repo | Zarejestrowana komenda w `.claude/skills/` | Serwer udostępniający narzędzia przez protokół |
| Jak agent się o nim dowiaduje | Musisz mu powiedzieć "przeczytaj plik X" albo dać wzmiankę w CLAUDE.md | Automatycznie - użytkownik wpisuje `/nazwa` | Automatycznie - widzi listę dostępnych narzędzi |
| Jak agent wykonuje akcję | Sam składa komendy (curl, git) na podstawie instrukcji | Sam składa komendy na podstawie instrukcji | Wywołuje gotową funkcję ze schematem parametrów |
| Gdzie działa | Terminal (Claude Code, Cursor) | Terminal (Claude Code) | Wszędzie gdzie klient obsługuje MCP (terminal, web, telefon) |
| Konfiguracja | Żadna - tworzysz plik i gotowe | Trzeba zarejestrować w `.claude/skills/` | Trzeba postawić/skonfigurować serwer MCP |
| Edycja i iteracja | Najłatwiejsza - edytujesz plik, od razu testujesz | Trzeba edytować skill i przeładować | Trzeba zmodyfikować serwer |
| Powtarzalność wyników | Zależy od interpretacji agenta | Zależy od interpretacji agenta | Wysoka - schemat parametrów ogranicza pole błędu |
| Bezpieczeństwo tokenów | Token w treści rozmowy lub .env | Token w treści rozmowy lub .env | OAuth na poziomie protokołu |
| Kiedy stosować | Eksperymentowanie, prototypowanie instrukcji | Sprawdzony workflow, gotowy do użycia przez zespół | Częsta/skomplikowana integracja z zewnętrzną usługą |

## Skills - instrukcja obsługi dla agenta

Skill to plik z instrukcjami (zwykle Markdown), który mówi agentowi co i jak ma robić. Sam w sobie nic nie wykonuje - opisuje proces, który agent realizuje dostępnymi narzędziami (Bash, curl, edycja plików).

Przykład: skill do tworzenia wpisów w bazie wiedzy zawiera opis endpointów API, format requestu, wymagane nagłówki. Agent czyta te instrukcje, sam składa curla i wysyła request przez terminal.

### Co skill potrafi

- Opisać workflow krok po kroku ("najpierw pobierz listę, potem utwórz wpis")
- Przekazywać wiedzę domenową ("w tym projekcie używamy takich konwencji")
- Standaryzować powtarzalne zadania (code review, commit, deploy)
- Nauczyć agenta korzystać z istniejących CLI (git, curl, gcloud)

### Ograniczenia

Skill zakłada dostęp do terminala. Działa w Claude Code, Cursor czy innym narzędziu z shellem. Nie zadziała w webowym chacie, na telefonie ani w ChatGPT.

Agent musi sam interpretować instrukcje i składać komendy. Jeśli API jest skomplikowane (OAuth, paginacja, nietypowe formaty), skill robi się długi i łatwo o błędy. Agent dosłownie czyta instrukcję napisaną ludzkim językiem i próbuje ją wykonać - nie ma gwarancji że za każdym razem zrobi to identycznie.

## W Claude Code - plik .md vs zarejestrowany Skill

W Claude Code są dwa sposoby korzystania z instrukcji, i warto rozumieć różnicę.

### Plik .md - luźna instrukcja

Zwykły plik Markdown w repozytorium (np. `docs/llm/kb_entry_api.md`). Agent nie wie o nim dopóki mu nie powiesz - "przeczytaj instrukcję z docs/llm/kb_entry_api.md i utwórz wpis". Albo masz wzmiankę w CLAUDE.md, że taki plik istnieje.

To dobry format na etapie eksperymentowania. Piszesz instrukcję, testujesz z agentem, poprawiasz, znów testujesz. Plik możesz edytować na bieżąco, nie musisz nic konfigurować.

### Zarejestrowany Skill (komenda /nazwa)

Skill zarejestrowany w konfiguracji Claude Code (`.claude/skills/`). Użytkownik wywołuje go komendą `/review-pr` albo `/done` i agent automatycznie wie co robić. Nie trzeba mu wskazywać pliku ani tłumaczyć kontekstu.

Skill ma też metadane - kiedy się uruchamia, jaki prompt dostaje agent, jakie narzędzia powinien użyć. Jest "oficjalny" - część konfiguracji projektu.

### Kiedy co stosować

Naturalna ścieżka wygląda tak:

1. **Zacznij od pliku .md** - piszesz instrukcję, testujesz ją z agentem w rozmowie ("przeczytaj ten plik i zrób X"). Poprawiasz treść aż agent robi to co trzeba. Na tym etapie nie wiesz jeszcze dokładnie jak powinna wyglądać finalna instrukcja.

2. **Dopracuj przez kilka sesji** - za każdym razem widzisz gdzie agent się myli, co pomija, co robi niepotrzebnie. Dodajesz brakujące kroki, usuwasz nadmiarowe. Plik .md łatwo edytować bo to zwykły tekst w repo.

3. **Jak działa stabilnie - zrób z tego Skill** - kiedy instrukcja jest przetestowana i wiesz że agent radzi sobie dobrze, rejestrujesz ją jako Skill z komendą `/nazwa`. Od tego momentu każdy w zespole może użyć `/nazwa` bez wiedzy co jest pod spodem.

I tu fajny szczegół - sam ten krok ("zarejestruj to jako Skill") możesz zlecić agentowi. Mówisz mu "weź ten plik .md i zrób z niego Skill pod komendą /create-kb-entry" i agent sam utworzy odpowiednią konfigurację w `.claude/skills/`.

Nie ma sensu robić Skilla od razu. Najpierw musisz wiedzieć co ma robić i jak - a to wychodzi dopiero po kilku próbach z luźnym plikiem .md.

## MCP - standardowy adapter do usług

MCP (Model Context Protocol) to protokół stworzony przez Anthropic w 2024 roku. Definiuje standardowy sposób udostępniania narzędzi agentom AI.

Serwer MCP to osobny proces, który wystawia listę dostępnych akcji z opisem parametrów. Agent widzi np. `create_kb_entry(title, content, category_id)` i może to wywołać bezpośrednio. Nie musi wiedzieć jaki jest URL, jakie nagłówki, jaki format body.

### Co daje MCP

- Agent dostaje gotowe narzędzia ze schematem parametrów - wie co może wywołać i jakie dane podać
- Autoryzacja (OAuth) obsługiwana na poziomie protokołu, bez tokenów w plikach .env
- Serwer można zaktualizować raz i zmiana działa dla wszystkich klientów
- Działa wszędzie gdzie klient obsługuje MCP - terminal, web, telefon
- Narzędzia są "discoverable" - agent może zapytać serwer co jest dostępne

### Ograniczenia

Trzeba postawić i utrzymywać serwer MCP (albo użyć hostowanego). Trudniej debugować niż zwykłego curla. Kompozycja wielu serwerów MCP bywa problematyczna.

## Praktyczny przykład - ta sama operacja

**Plik .md + curl**: agent czyta instrukcję z pliku, sam buduje request:
```
curl -X POST /kb/entries.json -H "Authorization: Bearer TOKEN" -d '{"entry": {"title": "..."}}'  
```
Agent musi znać URL, nagłówki, strukturę JSON. Instrukcja mu to podpowiada, ale to on składa komendę.

**Skill /create-entry**: użytkownik wpisuje `/create-entry` i agent wie co robić. Pod spodem robi dokładnie to samo (curl), ale nie trzeba mu przypominać skąd wziąć instrukcje.

**MCP**: agent wywołuje narzędzie bezpośrednio:
```
mcp__intum__create_kb_entry(title: "...", content: "...", category_id: 123)
```
Nie musi wiedzieć co jest pod spodem. Serwer MCP zajmuje się resztą.

## Można łączyć wszystkie podejścia

Skill jako "podręcznik" + MCP jako "adapter" to rozsądna kombinacja. Skill opisuje kiedy i dlaczego użyć narzędzia, MCP daje samo narzędzie. Np. skill mówi "po zakończeniu pracy zapisz podsumowanie w bazie wiedzy", a MCP dostarcza metodę `create_kb_entry`.

A plik .md jest naturalnym punktem wyjścia do obu - prototypujesz instrukcję, a potem decydujesz czy ma być Skillem czy może lepiej napisać serwer MCP.

## Nazewnictwo skilli w zespole

Gdy skilli jest kilka, nazwy mogą być dowolne. Przy 10+ warto mieć konwencję, bo inaczej nikt nie pamięta co jest dostępne.

### Po module + akcji (najczęstsze)

```
/kb-create, /kb-update
/deploy-staging, /deploy-prod
/sentry-fix
/ci-check, /ci-fix
```

Wpisujesz `/kb-` i widzisz wszystkie skille związane z bazą wiedzy. Grupowanie przez prefix dobrze skaluje się przy rosnącej liczbie skilli.

### Po etapie workflow

```
/start       - na początku sesji (recall kontekstu)
/done        - na koniec sesji (zapis postępu)
/review-pr   - przed mergem
/ship        - deploy
```

Dobre dla skilli opisujących proces zespołowy - każdy wie w jakim momencie czego użyć.

### Zasady które się sprawdzają

- Krótkie nazwy, max 2-3 słowa z myślnikami
- Prefix grupujący jeśli masz dużo skilli (`kb-`, `deploy-`, `sentry-`)
- Czasownik na końcu (`kb-create`) albo na początku (`create-entry`) - byle konsekwentnie w projekcie
- Unikaj generycznych nazw (`/do`, `/run`, `/fix`) - za miesiąc nikt nie pamięta co robią
- Claude Code nie ma wbudowanych kategorii skilli - wszystkie są w jednej płaskiej liście. Prefixy w nazwach (`/kb-`, `/deploy-`) to jedyny sposób na grupowanie. Wpisujesz prefix i widzisz tylko pasujące skille
- Przy mniejszej liczbie skilli nie komplikuj - `/review-pr` i `/done` jest ok

## Źródła

- [I Still Prefer MCP Over Skills](https://david.coffee/i-still-prefer-mcp-over-skills/) - David Mohl, porównanie obu podejść z praktycznymi argumentami
- [Dyskusja na Hacker News](https://news.ycombinator.com/item?id=47712718) - komentarze m.in. twórcy Redisa o tym kiedy które podejście ma sens
- [Model Context Protocol](https://modelcontextprotocol.io/) - oficjalna dokumentacja MCP (Anthropic)