Budowanie i publikowanie własnych Skills

Twój zespół ma wzorzec komponentów, którego musi przestrzegać każdy plik React: najpierw interfejs, hooki na górze, handlery w środku, JSX na dole. Konwencja nazewnictwa tras API. Format wiadomości commitów. Checklista wdrożeniowa. Wyjaśniasz te wzorce AI na początku każdej sesji. Co gorsza, każdy deweloper w zespole wyjaśniał je nieco inaczej, więc AI generuje niespójne wyniki w zależności od tego, kto pisze prompt.

Własny skill przechwytuje te konwencje w ustrukturyzowanym, udostępnialnym formacie. Zainstaluj go raz, a każda sesja AI — dla każdego dewelopera w zespole — będzie postępować według tych samych reguł. Gdy konwencja się zmieni, aktualizujesz skill w jednym miejscu i każdy deweloper otrzymuje aktualizację.

Co wyniesiesz z tego rozdziału

• Kompletną strukturę plików skilla: SKILL.md, rules/ i install.md
• Jak pisać skuteczne instrukcje SKILL.md, których AI konsekwentnie przestrzega
• Lokalny workflow testowania przed publikacją
• Publikowanie skilla na GitHub i umieszczanie na skills.sh
• Strategie utrzymania i wersjonowania dla długożyciowych skills

Dlaczego warto budować własny Skill

Skills frameworkowe z marketplace (React best practices, wzorce Next.js) obejmują wiedzę ogólną. Nie znają specyfiki twojego projektu:

• Twoje konwencje nazewnictwa plików
• Twój stos middleware do obsługi błędów
• Twój proces wdrażania i zmienne środowiskowe
• Twoje wzorce testowania i wymagania pokrycia
• Twój szablon PR i oczekiwania przy przeglądaniu kodu

Własny skill wypełnia tę lukę. Koduje wiedzę specyficzną dla projektu, która istnieje w zbiorowej pamięci twojego zespołu, i udostępnia ją AI automatycznie.

Struktura plików Skilla

Skill to repozytorium GitHub o określonej strukturze katalogów. CLI skills odczytuje tę strukturę podczas instalacji.

my-team-skill/
  SKILL.md              # Główne instrukcje odczytywane przez AI
  rules/                # Dodatkowe pliki reguł (opcjonalne)
    architecture.md     # Reguły dotyczące architektury
    testing.md          # Reguły dotyczące testowania
    deployment.md       # Reguły dotyczące wdrażania
  install.md            # Instrukcje po instalacji dla dewelopera
  README.md             # Opis na marketplace i dokumentacja

SKILL.md — Główne instrukcje

SKILL.md to główny plik odczytywany przez AI. Wszystko w tym pliku staje się częścią kontekstu agenta. Pisz go jako bezpośrednie 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 reguł

Katalog rules/ zawiera dodatkowe pliki instrukcji dotyczące konkretnych zagadnień. Są one dołączane 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 zrobić po zainstalowaniu skilla. Jest wyświetlany przez CLI skills po zakończeniu 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. Utwórz repozytorium GitHub. Nazwij je opisowo: acme/coding-conventions, acme/react-patterns lub acme/deployment-workflow.

2. Utwórz strukturę plików.

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

3. Napisz SKILL.md. Postępuj według powyższych wskazówek. Bądź konkretny, używaj prawdziwych przykładów z twojego codebase i priorytetyzuj konwencje, które AI najczęściej pomija.

4. Dodaj dodatkowe reguły. Jeśli twój skill obejmuje wiele zagadnień (architektura, testowanie, wdrażanie), podziel je na pliki w katalogu rules/ dla lepszej organizacji.

5. Napisz install.md. Wymień wszystkie zależności, które deweloper musi zainstalować, oraz konfigurację wymaganą do poprawnego działania skilla.

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

   • Co skill uczy AI
   • Do jakiego stosu technologicznego się stosuje
   • Polecenie instalacji
   • Przykładowe prompty demonstrujące 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 publikacją.

Testowanie Skilla lokalnie

Przed opublikowaniem zweryfikuj, czy skill działa poprawnie w każdym narzędziu.

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."

Sprawdź, czy AI:

• Używa struktury komponentów z twojego SKILL.md
• Przestrzega wzorca obsługi błędów, który określiłeś
• Tworzy pliki testowe w zdefiniowanym formacie
• Używa kolejności importów, którą udokumentowałeś

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 tę samą checklistę. Sprawdź również, czy Claude Code odkrywa i stosuje reguły 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."

Ponieważ Codex działa autonomicznie, zwróć szczególną uwagę na to, czy wynik jest zgodny z twoimi konwencjami bez jakiejkolwiek interaktywnej korekty.

Checklista testowania

Po wygenerowaniu kodu z zainstalowanym skillem zweryfikuj:

• ☐ Nazewnictwo plików odpowiada twojej konwencji
• ☐ Struktura komponentu odpowiada szablonowi w SKILL.md
• ☐ Kolejność importów jest prawidłowa
• ☐ Obsługa błędów postępuje według twojego wzorca
• ☐ Pliki testowe są tworzone z odpowiednią strukturą
• ☐ Trasy API używają twojego wzorca middleware
• ☐ Żadna konwencja z SKILL.md nie została 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

Bądź konkretny, nie aspiracyjny

AI nie może postępować według “pisz czysty, łatwy w utrzymaniu kod.” Może postępować według “używaj named exports, dodawaj JSDoc do publicznych funkcji i prefiksuj prywatne metody podkreśleniem.”

Źle: “Przestrzegaj najlepszych praktyk obsługi błędów.”

Dobrze: “Opakowuj wszystkie wywołania bazy danych w try/catch. W przypadku błędu rzuć new AppError('RESOURCE_NOT_FOUND', 404) z odpowiednim kodem błędu i statusem HTTP. Nigdy nie rzucaj prostych stringów.”

Priorytetyzuj to co nieoczywiste

AI już wie jak pisać TypeScript. Nie wie, że twój zespół preferuje interface nad type dla kształtów obiektów, ani że trasy API muszą zawsze wywoływać validateRequest przed przetwarzaniem. Skup się na tym, co wyróżnia twój projekt.

Pokazuj, nie tylko opowiadaj

Każda instrukcja powinna mieć konkretny przykład kodu. AI przestrzega przykładów bardziej niezawodnie niż opisów prozatorskich.

Nie przekraczaj 2000 słów

Długie skills są rozwadniane. AI przetwarza początek skilla uważniej niż koniec. Umieść konwencje o najwyższym wpływie na początku.

Używaj jawnego języka nadpisywania

Jeśli twój skill jest sprzeczny z ogólnymi 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, które przestrzegają formatu skills.

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

2. Upewnij się, że README jest kompletne. Marketplace wyświetla twoje README. Zawrzyj:

   • Opis skilla
   • Stos technologiczny, do którego się stosuje
   • Polecenie instalacji: npx skills add your-org/your-skill
   • Przykładowe prompty
   • Zrzut ekranu lub przykład kodu pokazujący skill w działaniu

3. Zgłoś na skills.sh. Postępuj według procesu zgłaszania na stronie skills.sh. Po weryfikacji twój skill pojawi się w wynikach wyszukiwania.

4. Promuj swój skill. Udostępnij go w społecznościach deweloperskich, włącz do wpisów na blogu i odwołaj się w dokumentacji projektu.

Dla wewnętrznych (prywatnych) Skills

Jeśli twoje konwencje są zastrzeżone:

• Prywatne repozytorium GitHub. CLI skills instaluje z prywatnych repozytoriów, jeśli deweloper ma skonfigurowany dostęp do GitHub.
• Bezpośredni commit plików. Pomiń CLI skills i commituj pliki instrukcji bezpośrednio 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 mogą przypiąć konkretną wersję:

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

Aktualizacja przy zmianie konwencji

Gdy twój zespół zmienia konwencje, aktualizuj skill w tym samym PR. To utrzymuje synchronizację między 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 wzorców

Gdy wzorzec się zmienia, dokumentuj zarówno stary, jak i nowy wzorzec, aby AI prawidłowo obsługiwał 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 skuteczności 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 coś nie działa

Skill jest zainstalowany, ale AI ignoruje pewne konwencje. Instrukcja jest prawdopodobnie zbyt niejasna. Zapytaj AI wprost: “What does my skill say about error handling?” Jeśli nie potrafi jasno sformułować reguły, przepisz instrukcję z konkretnym przykładem.

Skill działa w jednym narzędziu, ale nie w innym. CLI skills instaluje do różnych katalogów dla każdego narzędzia. Sprawdź, czy pliki istnieją we właściwej lokalizacji: .cursor/rules/ dla Cursor, .claude/skills/ dla Claude Code, .codex/instructions.md dla Codex.

Przykładowy kod w skillu ma błędy składniowe. AI kopiuje przykłady kodu dosłownie. Jeśli przykład ma literówkę lub odwołuje się do nieistniejącego importu, AI powieli błąd. Przetestuj każdy przykład kodu wklejając go do swojego projektu.

Skill jest za długi i AI ignoruje dolną połowę. Przenieś najważniejsze konwencje na początek SKILL.md. Jeśli skill przekracza 2000 słów, podziel go na skupiony SKILL.md i dodatkowe pliki w rules/.

Członkowie zespołu otrzymują różne zachowanie AI pomimo tego samego skilla. Jeden deweloper może mieć osobiste reguły, które nadpisują skill zespołowy. Sprawdź konflikty między konfiguracją osobistą (globalne reguły) a konfiguracją projektu (zacommitowane skills).

Zgłoszenie na marketplace zostało odrzucone. Upewnij się, że README jest kompletne, repozytorium jest publiczne, struktura plików jest prawidłowa i skill dostarcza naprawdę przydatne instrukcje (nie tylko “pisz dobry kod”).

Co dalej

Optymalizacja Skills i udostępnianie w zespole Najlepsze praktyki zarządzania skills w zespole i unikanie typowych pułapek.

Instalacja i zarządzanie Skills Pełna dokumentacja CLI do wyszukiwania, instalacji, aktualizacji i usuwania skills.

Skills vs MCP Kiedy używać skilla, a kiedy serwera MCP.