Budowanie i publikowanie wlasnych Skills

Twoj zespol ma wzorzec komponentow, ktorego musi przestrzegac kazdy plik React: najpierw interfejs, hooki na gorze, handlery w srodku, JSX na dole. Konwencja nazewnictwa tras API. Format wiadomosci commitow. Checklista wdrozeniowa. Wyjasniasz te wzorce AI na poczatku kazdej sesji. Co gorsza, kazdy deweloper w zespole wyjasnial je nieco inaczej, wiec AI generuje niespojne wyniki w zaleznosci od tego, kto pisze prompt.

Wlasny skill przechwytuje te konwencje w ustrukturyzowanym, udostepnialnym formacie. Zainstaluj go raz, a kazda sesja AI — dla kazdego dewelopera w zespole — bedzie postepowac wedlug tych samych regul. Gdy konwencja sie zmieni, aktualizujesz skill w jednym miejscu i kazdy deweloper otrzymuje aktualizacje.

Co wyniesiesz z tego rozdzialu

• Kompletna struktura plikow skilla: SKILL.md, rules/ i install.md
• Jak pisac skuteczne instrukcje SKILL.md, ktorych AI konsekwentnie przestrzega
• Lokalny workflow testowania przed publikacja
• Publikowanie skilla na GitHub i umieszczanie na skills.sh
• Strategie utrzymania i wersjonowania dla dlugozyciowych skills

Dlaczego warto budowac wlasny Skill

Skills frameworkowe z marketplace (React best practices, wzorce Next.js) obejmuja wiedze ogolna. Nie znaja specyfiki twojego projektu:

• Twoje konwencje nazewnictwa plikow
• Twoj stos middleware do obslugi bledow
• Twoj proces wdrazania i zmienne srodowiskowe
• Twoje wzorce testowania i wymagania pokrycia
• Twoj szablon PR i oczekiwania przy przegladzaie kodu

Wlasny skill wypelnia te luke. Koduje wiedze specyficzna dla projektu, ktora istnieje w zbiorowej pamieci twojego zespolu, i udostepnia ja AI automatycznie.

Struktura plikow Skilla

Skill to repozytorium GitHub o okreslonej strukturze katalogow. CLI skills odczytuje te strukture podczas instalacji.

my-team-skill/
  SKILL.md              # Glowne instrukcje odczytywane przez AI
  rules/                # Dodatkowe pliki regul (opcjonalne)
    architecture.md     # Reguly dotyczace architektury
    testing.md          # Reguly dotyczace testowania
    deployment.md       # Reguly dotyczace wdrazania
  install.md            # Instrukcje po instalacji dla dewelopera
  README.md             # Opis na marketplace i dokumentacja

SKILL.md — Glowne instrukcje

SKILL.md to glowny plik odczytywany przez AI. Wszystko w tym pliku staje sie czescia kontekstu agenta. Pisz go jako bezposrednie instrukcje dla AI.

# Acme Corp Development Conventions

## Component Structure

When creating React components, use this exact structure:

```tsx
// src/components/FeatureName/FeatureName.tsx
interface FeatureNameProps {
  id: string;
  onAction?: () => void;
}

export function FeatureName({ id, onAction }: FeatureNameProps) {
  // 1. Hooks
  const [state, setState] = useState(false);
  const data = useQuery(['feature', id]);

  // 2. Handlers
  const handleClick = () => onAction?.();

  // 3. Early returns for loading/error states
  if (data.isLoading) return <FeatureNameSkeleton />;
  if (data.error) return <ErrorBoundary error={data.error} />;

  // 4. Main render
  return (
    <div data-testid="feature-name">
      {/* component JSX */}
    </div>
  );
}
```

Rules:
- One component per file
- Directory name matches component name (PascalCase)
- Props interface in same file, named `ComponentNameProps`
- Named exports only, never default exports
- Always include data-testid for testing

## API Routes

```typescript
// src/pages/api/resource-name.ts
import { withAuth } from '~/lib/middleware';
import { validate } from '~/lib/validation';
import { ResourceSchema } from '~/lib/schemas';

export const POST = withAuth(async ({ request, locals }) => {
  const body = await validate(request, ResourceSchema);
  const result = await createResource(locals.runtime.env.DB, body);
  return Response.json(result, { status: 201 });
});
```

Rules:
- Always validate with Zod schemas before processing
- Always wrap authenticated endpoints with `withAuth`
- Use `Response.json()` not `new Response(JSON.stringify(...))`
- Return appropriate HTTP status codes (201 for creation, 204 for deletion)

## Error Handling

- Use `AppError` from `~/lib/errors` for all error responses
- Never throw plain strings or generic Error objects
- Log with structured context: `logger.error('message', { userId, action, error })`
- Never expose stack traces or internal details in API responses

rules/ — Dodatkowe pliki regul

Katalog rules/ zawiera dodatkowe pliki instrukcji dotyczace konkretnych zagadnien. Sa one dolaczane razem z SKILL.md podczas instalacji skilla.

rules/testing.md

## Testing Conventions

Every component gets a colocated test file: `FeatureName.test.tsx`

Use this test structure:

```tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { FeatureName } from './FeatureName';

describe('FeatureName', () => {
  it('renders without crashing', () => {
    render(<FeatureName id="test-1" />);
    expect(screen.getByTestId('feature-name')).toBeInTheDocument();
  });

  it('calls onAction when clicked', () => {
    const onAction = vi.fn();
    render(<FeatureName id="test-1" onAction={onAction} />);
    fireEvent.click(screen.getByRole('button'));
    expect(onAction).toHaveBeenCalledOnce();
  });
});
```

Rules:
- Test behavior, not implementation details
- Use `data-testid` selectors, not CSS class selectors
- Mock external dependencies, not internal functions
- Each test file must pass independently (no shared state between tests)

install.md — Instrukcje po instalacji

install.md informuje dewelopera co zrobic po zainstalowaniu skilla. Jest wyswietlany przez CLI skills po zakonczeniu instalacji.

# Post-Install Setup

This skill requires the following project dependencies:

```bash
npm install -D @testing-library/react vitest
```

## Configuration

Add to your `vitest.config.ts`:

```typescript
export default defineConfig({
  test: {
    environment: 'happy-dom',
    setupFiles: ['./tests/setup.ts'],
  },
});
```

## Verification

Run this command to verify the skill is working:

```bash
npx skills list
```

Then ask the AI: "Create a sample component following all project conventions."
Review the output to confirm it matches the patterns defined in the skill.

Wskazówka

Prompt do skopiowania do wyodrębniania konwencji z codebase:

“Analyze the codebase and identify patterns that appear in at least 5 files: component structure, import ordering, error handling approach, naming conventions, test organization, and API route patterns. For each pattern, extract a concrete example with the actual file path. Generate a SKILL.md file that documents each pattern as an instruction the AI should follow.”

Tworzenie Skilla krok po kroku

1. Utworz repozytorium GitHub. Nazwij je opisowo: acme/coding-conventions, acme/react-patterns lub acme/deployment-workflow.

2. Utworz strukture plikow.

   mkdir -p my-skill/rules
   touch my-skill/SKILL.md my-skill/install.md my-skill/README.md

3. Napisz SKILL.md. Postepuj wedlug powyzszych wskazowek. Badz konkretny, uzywaj prawdziwych przykladow z twojego codebase i priorytetyzuj konwencje, ktore AI najczesciej pomija.

4. Dodaj dodatkowe reguly. Jesli twoj skill obejmuje wiele zagadnien (architektura, testowanie, wdrazanie), podziel je na pliki w katalogu rules/ dla lepszej organizacji.

5. Napisz install.md. Wymien wszystkie zaleznosci, ktore deweloper musi zainstalowac, oraz konfiguracje wymagana do poprawnego dzialania skilla.

6. Napisz README.md. To publiczna twarz twojego skilla na marketplace. Zawrzyj:

   • Co skill uczy AI
   • Do jakiego stosu technologicznego sie stosuje
   • Polecenie instalacji
   • Przykladowe prompty demonstrujace skill w akcji

7. Wypchnij na GitHub.

   cd my-skill
   git init && git add . && git commit -m "Initial skill release"
   git remote add origin https://github.com/acme/coding-conventions.git
   git push -u origin main

8. Przetestuj lokalnie przed publikacja.

Testowanie Skilla lokalnie

Przed opublikowaniem zweryfikuj, czy skill dziala poprawnie w kazdym narzedziu.

Cursor

# Install from your repo (even before publishing to marketplace)
npx skills add acme/coding-conventions

# Verify files were created
ls .cursor/rules/

# Open Cursor and test with a prompt
# "Create a new API endpoint for user profile updates
#  following all project conventions."

Sprawdz, czy AI:

• Uzywa struktury komponentow z twojego SKILL.md
• Przestrzega wzorca obslugi bledow, ktory okreslilem
• Tworzy pliki testowe w zdefiniowanym formacie
• Uzywa kolejnosci importow, ktora udokumentowales

Claude Code

# Install from your repo
npx skills add acme/coding-conventions

# Verify files were created
ls .claude/skills/

# Test in a Claude Code session
claude "Create a new API endpoint for user profile updates
following all project conventions."

Zweryfikuj ta sama checkliste. Sprawdz rowniez, czy Claude Code odkrywa i stosuje reguly z podkatalogu rules/.

Codex

# Install from your repo
npx skills add acme/coding-conventions

# Verify instructions were updated
cat .codex/instructions.md

# Test with a Codex task
codex "Create a new API endpoint for user profile updates
following all project conventions."

Poniewaz Codex dziala autonomicznie, zwroc szczegolna uwage na to, czy wynik jest zgodny z twoimi konwencjami bez jakiejkolwiek interaktywnej korekty.

Checklista testowania

Po wygenerowaniu kodu z zainstalowanym skillem zweryfikuj:

• Nazewnictwo plikow odpowiada twojej konwencji
• Struktura komponentu odpowiada szablonowi w SKILL.md
• Kolejnosc importow jest prawidlowa
• Obsluga bledow postepuje wedlug twojego wzorca
• Pliki testowe sa tworzone z odpowiednia struktura
• Trasy API uzywaja twojego wzorca middleware
• Zadna konwencja z SKILL.md nie zostala zignorowana

Wskazówka

Prompt do skopiowania do automatycznego testowania skilla:

“Read the installed skill instructions and then generate one of each: a React component, an API route, and a test file. After generating each, compare the output against the conventions in the skill and list any deviations. This helps me identify which instructions need to be more explicit.”

Pisanie skutecznych instrukcji

Badz konkretny, nie aspiracyjny

AI nie moze postepowac wedlug “pisz czysty, latwi w utrzymaniu kod.” Moze postepowac wedlug “uzywaj named exports, dodawaj JSDoc do publicznych funkcji i prefiksuj prywatne metody podkresleniem.”

Zle: “Przestrzegaj najlepszych praktyk obslugi bledow.”

Dobrze: “Opakowuj wszystkie wywolania bazy danych w try/catch. W przypadku bledu rzuc new AppError('RESOURCE_NOT_FOUND', 404) z odpowiednim kodem bledu i statusem HTTP. Nigdy nie rzucaj prostych stringow.”

Priorytetyzuj to co nieoczywiste

AI juz wie jak pisac TypeScript. Nie wie, ze twoj zespol preferuje interface nad type dla ksztaltow obiektow, ani ze trasy API musza zawsze wywolywac validateRequest przed przetwarzaniem. Skup sie na tym, co wyroznia twoj projekt.

Pokazuj, nie tylko opowiadaj

Kazda instrukcja powinna miec konkretny przyklad kodu. AI przestrzega przykladow bardziej niezawodnie niz opisow prozatorskich.

Nie przekraczaj 2000 slow

Dlugie skills sa rozwadniane. AI przetwarza poczatek skilla uwaznie niez koniec. Umiesc konwencje o najwyzszym wplyweu na poczatku.

Uzywaj jawnego jezyka nadpisywania

Jesli twoj skill jest sprzeczny z ogolnymi wzorcami frameworka, powiedz to wprost:

## Exports
Always use named exports. Never use default exports.
(This overrides the common React pattern of default-exporting components.)

Publikowanie na skills.sh

Marketplace skills.sh indeksuje publiczne repozytoria GitHub, ktore przestrzegaja formatu skills.

1. Dodaj tematy GitHub. Przejdz do ustawien repozytorium i dodaj tematy: agent-skills, ai-skills oraz odpowiednie tagi technologiczne (react, typescript, nextjs).

2. Upewnij sie, ze README jest kompletne. Marketplace wyswietla twoje README. Zawrzyj:

   • Opis skilla
   • Stos technologiczny, do ktorego sie stosuje
   • Polecenie instalacji: npx skills add your-org/your-skill
   • Przykladowe prompty
   • Zrzut ekranu lub przyklad kodu pokazujacy skill w dzialaniu

3. Zglos na skills.sh. Postepuj wedlug procesu zglaszania na stronie skills.sh. Po weryfikacji twoj skill pojawi sie w wynikach wyszukiwania.

4. Promuj swoj skill. Udostepnij go w spolecznosciach deweloperskich, wlacz do wpisow na blogu i odwolaj sie w dokumentacji projektu.

Dla wewnetrznych (prywatnych) Skills

Jesli twoje konwencje sa zastrzezone:

• Prywatne repozytorium GitHub. CLI skills instaluje z prywatnych repozytoriow, jesli deweloper ma skonfigurowany dostep do GitHub.
• Bezposredni commit plikow. Pomin CLI skills i commituj pliki instrukcji bezposrednio do .cursor/rules/, .claude/skills/ lub CLAUDE.md w swoim projekcie.
• Prywatny pakiet npm. Zapakuj skill jako pakiet npm w prywatnym rejestrze twojej firmy.

Utrzymanie Skills w czasie

Wersjonowanie

Taguj releasy, gdy wprowadzasz istotne zmiany:

git tag v1.0.0
git push origin v1.0.0

Deweloperzy moga przypiac konkretna wersje:

npx skills add acme/coding-conventions@v1.0.0

Aktualizacja przy zmianie konwencji

Gdy twoj zespol zmienia konwencje, aktualizuj skill w tym samym PR. To utrzymuje synchronizacje miedzy skillem a codebase:

# Update the skill files
vim SKILL.md

# Commit alongside the code change
git add SKILL.md src/lib/errors.ts
git commit -m "refactor: switch error handling to Result type

Updated SKILL.md to reflect the new error handling pattern."

Wycofywanie starych wzorcow

Gdy wzorzec sie zmienia, dokumentuj zarowno stary, jak i nowy wzorzec, aby AI prawidlowo obslugiwal migracje:

## Error Handling

Use the `Result` type pattern for all service functions:

```typescript
type Result<T> = { ok: true; data: T } | { ok: false; error: AppError };
```

**Deprecated:** The previous pattern used thrown `AppError` exceptions. If you
encounter this in existing code, refactor to the Result pattern when modifying
the file.

Wskazówka

Prompt do skopiowania do audytu skutecznosci skilla:

“Generate three code samples following the installed skill conventions: a React component, an API route handler, and a test file. For each, list which skill conventions were applied and which were missed. Use this to identify which instructions need to be clearer or more prominent in the skill file.”

Gdy cos nie dziala

Skill jest zainstalowany, ale AI ignoruje pewne konwencje. Instrukcja jest prawdopodobnie zbyt niejasna. Zapytaj AI wprost: “What does my skill say about error handling?” Jesli nie potrafi jasno sformulowac reguly, przepisz instrukcje z konkretnym przykladem.

Skill dziala w jednym narzedziu, ale nie w innym. CLI skills instaluje do roznych katalogow dla kazdego narzedzia. Sprawdz, czy pliki istnieja we wlasciwej lokalizacji: .cursor/rules/ dla Cursor, .claude/skills/ dla Claude Code, .codex/instructions.md dla Codex.

Przykladowy kod w skillu ma bledy skladniowe. AI kopiuje przyklady kodu doslownie. Jesli przyklad ma literowke lub odwoluje sie do nieistniejacego importu, AI powieli blad. Przetestuj kazdy przyklad kodu wklejajac go do swojego projektu.

Skill jest za dlugi i AI ignoruje dolna polowe. Przenies najwazniejsze konwencje na poczatek SKILL.md. Jesli skill przekracza 2000 slow, podziel go na skupiony SKILL.md i dodatkowe pliki w rules/.

Czlonkowie zespolu otrzymuja rozne zachowanie AI pomimo tego samego skilla. Jeden deweloper moze miec osobiste reguly, ktore nadpisuja skill zespolowy. Sprawdz konflikty miedzy konfiguracja osobista (globalne reguly) a konfiguracja projektu (zacommitowane skills).

Zgloszenie na marketplace zostalo odrzucone. Upewnij sie, ze README jest kompletne, repozytorium jest publiczne, struktura plikow jest prawidlowa i skill dostarcza naprawde przydatne instrukcje (nie tylko “pisz dobry kod”).

Co dalej

Optymalizacja Skills i udostepnianie w zespole Najlepsze praktyki zarzadzania skills w zespole i unikanie typowych pulapek.

Instalacja i zarzadzanie Skills Pelna dokumentacja CLI do wyszukiwania, instalacji, aktualizacji i usuwania skills.

Skills vs MCP Kiedy uzywac skilla, a kiedy serwera MCP.