Agent Skill

Jeśli korzystasz z asystenta programistycznego AI, takiego jak Claude Code, Codex czy Cursor, Skill SpicyAPI uczy go, jak poprawnie pracować ze SpicyAPI. Instalujesz go raz. Potem możesz powiedzieć „dodaj do mojej aplikacji generowanie obrazów w SpicyAPI”, a asystent będzie trzymał się zasad SpicyAPI, zamiast zgadywać.

Nie musisz być programistą, żeby skorzystać z tej strony. Jeśli potrafisz wkleić polecenie do terminala, zainstalujesz Skill.

Czym jest Skill

Skill to folder instrukcji napisanych dla asystenta AI, a nie dla ludzi. Pomyśl o nim jak o instrukcji stanowiskowej wręczanej nowej osobie w zespole: sam nie wykonuje pracy, ale mówi temu, kto ją wykonuje, jakie kroki podjąć, w jakiej kolejności i czego nigdy nie robić.

Asystenci AI dużo wiedzą o programowaniu w ogóle, ale nie mają rzetelnej wiedzy o konkretnych zasadach SpicyAPI. Zdany na zgadywanie asystent może:

• zmyślić identyfikator modelu albo pole wejściowe, które nie istnieje;
• wkleić twój klucz API prosto do kodu;
• po chwilowym problemie z siecią wysłać to samo płatne żądanie dwa razy i dwa razy za nie zapłacić;
• dać ci link do wyniku, który kilka dni później przestanie działać.

Z zainstalowanym Skillem asystent czyta zasady SpicyAPI, zanim zacznie pracę. W praktyce wygląda to tak:

1. Folder Skilla leży w miejscu, które asystent sprawdza na początku sesji.
2. Asystent czyta jednoakapitowe podsumowanie Skilla. Gdy twoja prośba dotyczy SpicyAPI, otwiera pełne instrukcje. Nie musisz wymieniać Skilla z nazwy.
3. Trzyma się tych instrukcji, gdy pisze dla ciebie kod albo uruchamia polecenia.

Trzy fakty, które warto znać od początku:

• To tylko tekst. Pliki Markdown i YAML: żadnych programów, żadnych skryptów, nic, co uruchamia się przy instalacji. Każdy plik otworzysz w edytorze tekstu; zobacz Co jest w środku.
• Nie zawiera klucza API i niczego nie wywołuje. Sam z siebie nie ma dostępu do twojego konta i nie wyda twoich pieniędzy.
• Jest bezpłatny i ma otwarty kod. Udostępniony na licencji MIT, opublikowany w npm jako @spicyapi/skill i rozwijany otwarcie pod adresem github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK i CLI

SpicyAPI ma cztery oficjalne narzędzia. Rozwiązują różne problemy i są zaprojektowane tak, żeby używać ich razem.

Skill nie zastępuje żadnego z nich. Mówi asystentowi, jak z nich korzystać: z narzędzi MCP, gdy są podłączone, z CLI przy jednorazowych operacjach i z SDK dla twojego języka w kodzie, który trafia do twojej aplikacji.

• Tylko Skill. Asystent pisze poprawny kod integracji dla twojego projektu, ale nie może niczego sprawdzić na twoim koncie ani uruchomić za ciebie zadań.
• Tylko MCP. Asystent może działać na twoim koncie, ale za każdym razem sam musi ustalać właściwą kolejność kroków.
• Oba. Asystent może coś za ciebie wypróbować i robi to w udokumentowany sposób. Jeśli chcesz, żeby asystent uruchamiał prawdziwe zadania, zainstaluj oba. Nie kolidują ze sobą.

W czym pomaga

Lewa kolumna to twoja prośba. Prawa kolumna to to, czego Skill wymaga od asystenta przy jej realizacji.

Czego nie zrobi

• Nie wyda pieniędzy na własną rękę. Skill to tekst i niczego nie może wywołać. Jeśli twój asystent ma również serwer MCP albo CLI i klucz API, może tworzyć płatne zadania. Skill każe mu najpierw pokazać ci cenę i uzyskać twoje wyraźne potwierdzenie, chyba że twoja prośba już jednoznacznie zezwoliła na dokładnie to płatne uruchomienie. Z serwerem MCP każde płatne działanie dodatkowo zatrzymuje się na potwierdzeniu, którego asystent nie może pominąć.
• Nie zmyśla funkcji. Nie napisze wywołań czegoś, czego publiczne API nie oferuje, na przykład anulowania zadania, usunięcia zapisu zadania albo ponownego wysłania webhooka.
• Nie rusza ustawień twojego konta. Rejestracja, logowanie, płatności, doładowania, członkowie zespołu, wnioski dotyczące prywatności i zamknięcie konta zostają w konsoli SpicyAPI. Asystent nie będzie próbował ich automatyzować.
• Nie udaje testów. Jeśli poprosisz o prawdziwy test, wysyła prawdziwe (i po twoim potwierdzeniu być może płatne) żądanie i relacjonuje, co faktycznie się stało. Zaliczony test na atrapie nigdy nie jest zgłaszany jako „zweryfikowany”.
• Nie dodaje ustawienia treści. SpicyAPI nie ma przełącznika trybu treści ani sprawdzania treści w poszczególnych żądaniach, a Skill żadnego nie wymyśla. O tym, co jest możliwe, decyduje wybrany przez ciebie model.

Zanim zaczniesz

Potrzebujesz czterech rzeczy. Do samej instalacji wystarczą pierwsze trzy.

1. Asystenta programistycznego AI, który obsługuje Agent Skills. Obsługują je Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf i wiele innych. Skill używa przenośnego formatu folderów Agent Skills, więc działa z każdym asystentem, który ten format czyta. Jeśli nie masz pewności co do swojego, poszukaj w jego dokumentacji hasła „skills”.

2. Node.js w wersji 22 lub nowszej, który dostarcza polecenie npx. Sprawdź wersję poleceniem:

   node --version

   Instalator skills wymaga obecnie Node.js w wersji 22.20 lub nowszej, a własny instalator pakietu – w wersji 22.13 lub nowszej. Jeśli polecenie nie zostanie znalezione albo wersja jest niższa, zainstaluj wydanie LTS z nodejs.org i otwórz nowy terminal.

3. Terminala. W macOS to aplikacja Terminal, w Windows – PowerShell. Jeśli chcesz zainstalować Skill tylko dla jednego projektu, uruchamiaj polecenia z folderu tego projektu.

4. Klucza API SpicyAPI, gdy zaczniesz wywoływać API. Do instalacji Skilla nie jest potrzebny. Utwórz klucz w konsoli; zaczyna się od sk-spicy- i jest pokazywany tylko raz. Zapisz go w zmiennej środowiskowej o nazwie SPICY_API_KEY i nigdy nie wklejaj samego klucza do rozmowy z asystentem. Zobacz Uwierzytelnianie.

Instalacja

Są dwa sposoby instalacji. Oba umieszczają na dysku te same pliki. Wybierz pierwszy, chyba że masz powód, żeby tego nie robić.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, tylko ten projekt
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, wszystkie projekty
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code i Codex, wszystkie projekty, bez pytań
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Sprawdź, czy działa

npx skills list      # Skille zainstalowane w bieżącym projekcie
npx skills list -g   # Skille zainstalowane dla wszystkich projektów

Przykładowe prośby

Wklej do asystenta dowolną z nich i dostosuj szczegóły. Wspomnij w prośbie o SpicyAPI, żeby asystent wiedział, że Skill ma zastosowanie.

Jeśli wiesz już, którego modelu chcesz użyć, skopiuj jego dokładny identyfikator z karty API na stronie modelu albo z uwierzytelnionego katalogu na żywo (live catalog) i wstaw go do prośby. Przykłady mają MODEL_ID_FROM_CATALOG w miejscu, gdzie powinien stać ten identyfikator; to symbol zastępczy, a nie prawdziwy identyfikator. Jeśli go nie masz, poproś asystenta, żeby wybrał model z katalogu na żywo. Zobacz Katalog modeli.

Dodaj endpoint obrazów do aplikacji Next.js

Dodaj do mojej aplikacji Next.js trasę API po stronie serwera, która przyjmuje prompt tekstowy, generuje obraz w SpicyAPI modelem MODEL_ID_FROM_CATALOG, czeka na wynik i zwraca link do obrazu. Klucz API odczytuj z SPICY_API_KEY.

Na co Skill każe asystentowi uważać:

• Klucz zostaje na twoim serwerze w SPICY_API_KEY. Twoja strona wywołuje twoją trasę; nigdy nie wywołuje SpicyAPI z kluczem.
• Przed zbudowaniem żądania asystent odczytuje aktualne pola wejściowe tego modelu z katalogu na żywo.
• Najpierw pobiera dokładną wycenę i pokazuje ci szacowany koszt oraz maksymalną opłatę. Płatne żądanie zawiera tę potwierdzoną wycenę.
• Tworzy jeden klucz idempotentności dla generacji i używa go ponownie, jeśli żądanie przekroczy czas.
• Czeka z ustalonym terminem, a potem sprawdza state zadania: czekanie, które się skończyło, to nie to samo co generacja, która się powiodła.

Odbieraj wyniki webhookiem w Express

Dodaj do mojego serwera Express endpoint webhooka, który odbiera wyniki zadań SpicyAPI, weryfikuje podpis za pomocą SPICY_WEBHOOK_SECRET i zapisuje link do wyniku w mojej bazie danych.

• Weryfikuje podpis względem dokładnej, surowej treści żądania, zanim sparsuje ją jako JSON.
• Na podstawie request_id dostarczenia ignoruje duplikaty, bo to samo zdarzenie może przyjść więcej niż raz.
• Odczytuje wynik prosto z kompletnego, zweryfikowanego webhooka, bez dodatkowego zapytania.

Kopiuj gotowe wideo do własnego magazynu

Gdy zadanie wideo w SpicyAPI się powiedzie, pobierz wideo i prześlij je do mojego bucketu S3, a potem zapisz mój własny link zamiast linku SpicyAPI.

• Linki do wyników są tymczasowe, a wygenerowane pliki są przechowywane przez około 14 dni, więc asystent zapisuje trwałą kopię, nad którą masz kontrolę.
• Nie wysyła twojego klucza API przy pobieraniu z linku do wyniku.
• Jeśli link wygasł, prosi SpicyAPI ponownie o to samo zadanie, żeby dostać świeży link. Nigdy nie tworzy nowego zadania tylko po to, żeby zdobyć link.

Zamień zdjęcie użytkownika w wideo

Pozwól użytkownikom przesłać zdjęcie w mojej aplikacji i zamienić je w krótkie wideo za pomocą SpicyAPI.

• Najpierw przesyła plik do SpicyAPI i wpisuje w żądanie zwrócony adres spicy://, zamiast wklejać plik jako base64.
• Przestrzega limitów przesyłania: 10 MiB dla obrazów, 90 MiB dla wideo MP4 lub WebM i dźwięku MP3 lub WAV.
• Zdjęcie, które jest już dostępne pod publicznym linkiem HTTPS, można przekazać bezpośrednio, bez przesyłania.

Obsłuż ponowienia i niskie saldo

Spraw, żeby moja integracja ze SpicyAPI obsługiwała błędy: ponawiała żądania po przekroczeniu czasu sieci bez podwójnej zapłaty, pokazywała czytelny komunikat, gdy saldo konta jest za niskie, i zwalniała, gdy trafi na limit żądań.

• Po przekroczeniu czasu ponawia żądanie z tym samym kluczem idempotentności, więc ponowienie nie może utworzyć drugiego płatnego zadania.
• Nie ponawia żądania przy niewystarczającym saldzie (kod 40201); twój użytkownik widzi czytelny komunikat, a ty doładowujesz konto w konsoli.
• Przed kolejną próbą czeka tak długo, jak każe Retry-After.
• Jeśli wycena wygasła albo cena się zmieniła (kod 40901), pobiera świeżą wycenę i ponownie cię pyta, zamiast pomijać sprawdzenie ceny.
• Wie, że ponowienie nieudanego zadania tworzy nowe zadanie, za które znów może zostać pobrana opłata, więc robi to tylko wtedy, gdy chcesz nowej próby.

Wygeneruj partię

Wygeneruj w SpicyAPI zdjęcia produktowe dla 20 pozycji z products.csv, najwyżej 3 naraz, i zapisz w logu identyfikator każdego zadania.

• SpicyAPI nie ma endpointu wsadowego, więc asystent uruchamia naraz ograniczoną liczbę żądań.
• Każda pozycja dostaje własny klucz idempotentności i własną cenę.
• Zapisuje identyfikator każdego zadania, gdy tylko zadanie zostanie przyjęte.
• Jeśli jedna pozycja przekroczy czas, odzyskuje tylko tę pozycję i nigdy nie wysyła ponownie całej partii.

Co jest w środku

Zainstalowany folder wygląda tak:

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

Asystent otwiera oba pliki referencyjne tylko wtedy, gdy dana praca ich wymaga, dzięki czemu jego pamięć robocza zostaje wolna dla twojego projektu. Żeby przeczytać pliki przed instalacją, uruchom npx @spicyapi/skill path: polecenie wypisze folder, w którym pakiet je trzyma.

Skill każe asystentowi konfigurować twój kod i narzędzia za pomocą tych zmiennych środowiskowych. Sam Skill nie odczytuje żadnej z nich.

Aktualizacja i usuwanie

Aktualizacja

Skill zmienia się, gdy zmienia się zalecany przez SpicyAPI sposób pracy, a zainstalowane kopie same się nie aktualizują. Zainstalowany folder nie ma numeru wersji, więc ponowna instalacja to najprostszy sposób, żeby mieć pewność, że korzystasz z aktualnej wersji.

• Instalacja przez npx skills add: uruchom to samo polecenie ponownie, z tym samym zakresem i tymi samymi asystentami. Zastąpi ono zainstalowane pliki tym, co repozytorium zawiera w tej chwili, więc zmiana trafia do ciebie od razu po opublikowaniu — na nic nie trzeba czekać.

• Instalacja instalatorem pakietu: uruchom go ponownie z --force i tym samym --target. Dodanie @latest sprawia, że npx pobiera najnowszy pakiet, zamiast używać kopii z pamięci podręcznej:

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

Usuwanie

Usunięcie Skilla nie wpływa na twoje konto SpicyAPI, klucze API ani kod, który asystent już napisał.

• Instalacja przez npx skills add: uruchom to polecenie z tego samego folderu projektu, dodając -g, jeśli instalacja była globalna. Potem sprawdź, czy folderu spicyapi już nie ma.

  npx skills remove spicyapi

• Instalacja instalatorem pakietu: usuń folder spicyapi – w Finderze albo Eksploratorze plików albo z terminala:

  # macOS i Linux: podaj folder, do którego instalowano Skill
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Zanim naciśniesz Enter, dwa razy sprawdź ścieżkę: musi kończyć się na spicyapi.

Potem rozpocznij nową sesję, żeby asystent przestał korzystać ze Skilla.

Rozwiązywanie problemów

Kod źródłowy

Pakiet jest na licencji MIT i powstaje otwarcie pod adresem github.com/spicyapi-ai/spicy-skill. Tam przeczytasz instrukcje, które Skill naprawdę instaluje, zgłosisz zachowanie inne niż opisane i zaproponujesz zmianę.

Co dalej