Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

add-operation

/add-operation

Dodaje operację API w projekcie TurbineKit jednocześnie jako endpoint REST, narzędzie MCP i wpis OpenAPI, z usługą dla zasobu.

Repozytorium
turbinekit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
04.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Dodaje operację API w projekcie TurbineKit jednocześnie jako endpoint REST, narzędzie MCP i wpis OpenAPI, z usługą dla zasobu.

Oryginalny opis (EN)

Add an API operation to a TurbineKit project. One operation is a REST endpoint, an MCP tool and an OpenAPI entry at once, backed by a service function that server actions reuse. Use for any new endpoint, tool, or action on a resource, including a whole new resource.

Jak działa

  1. Steps
  2. Check
Sekcje z nagłówków SKILL.md, w oryginale · 137 linii, 750 słów
Podgląd SKILL.md
---
name: add-operation
description: Add an API operation to a TurbineKit project. One operation is a REST endpoint, an MCP tool and an OpenAPI entry at once, backed by a service function that server actions reuse. Use for any new endpoint, tool, or action on a resource, including a whole new resource.
---

# Add an API operation

An operation (`defineOperation` in `packages/api`) is the single definition
behind a REST route, an MCP tool and an OpenAPI entry. The query lives in a
service function; server actions in the web app call the same function.

Read `packages/api/src/operations/projects.ts` and
`packages/api/src/services/projects.ts` first: they are the reference. Copy
their shape.

## Steps

1. **Table.** If the resource needs a new table, follow the `add-table` skill
   first, then come back.

2. **Permissions.** A new resource gets its own permissions in
   `packages/auth/src/permissions.ts`:

   ```ts
   export const PERMISSIONS = {
   	projects: ["read", "write"],
   	notes: ["read", "write"],
   } as const;
   ```

   - Add a line per new scope under `Auth.consent.scope` in every
     `apps/web/messages/<locale>.json`: the OAuth consent screen shows it.
   - Nothing else to change: API keys ("Read only" = every `…:read`
     permission, "Read and write" = all of them), OAuth scopes and the MCP
     server all read this list.

3. **Service**, `packages/api/src/services/<resource>.ts`: one exported
   function per action, `(db: AnyDb, caller: Caller, input) => Promise<…>`.
   - Scope every query to the caller. Copy `visibleTo(caller)` from
     `services/projects.ts`: with teams, a team's rows follow the active team.
   - Lists are newest first, a page at a time. Use `afterCursor` and
     `toPage` from `../pagination.ts`, exactly as `listProjects` does.
   - Return plain records with ISO date strings (`toRecord` in the
     reference).
   - A missing row: `throw ApiError.notFound("note")`. Other refusals:
     `new ApiError(status, type, code, message, param?)` (`../errors.ts`).
     Codes are snake_case and stable: clients branch on them.
   - If the project has the payments module and the plan should cap the
     resource, copy `assertRoomForProject` and add a limit to `PLANS` in
     `packages/billing/src/plans.ts`.

4. **Operations**, `packages/api/src/operations/<resource>.ts`. A list:

   ```ts
   export const listNotes = defineOperation({
   	id: "notes.list", // resource.verb
   	method: "GET",
   	path: "/v1/notes", // `/v1/notes/{id}` for one item
   	summary: "List notes",
   	description: "Returns the caller's notes, newest first, a page at a time.",
   	tags: ["Notes"],
   	scope: "notes:read",
   	input: z.object({
   		limit: z.coerce.number().int().min(1).max(100).default(20),
   		cursor: z.string().optional().describe("The `nextCursor` of the previous page."),
   	}),
   	output: z.object({ data: z.array(Note), nextCursor: z.string().nullable() }),
   	mcp: {
   		name: "list_notes",
   		title: "List notes",
   		description:
   			"Lists the user's notes, newest first, 20 at a time. When nextCursor is not null, call again with it as cursor.",
   		annotations: { readOnlyHint: true },
   	},
   	run: ({ db, caller }, input) => notes.listNotes(db, caller, input),
   });
   ```

   - `input` is one object: path params, query and body fields together.
     Query values arrive as strings: use `z.coerce` for numbers.
   - Validate field limits here, in zod (`z.string().trim().min(1).max(5000)`).
     Add a database constraint only for an invariant the data must never
     break.
   - `.describe()` the fields a client may misread: OpenAPI and the MCP tool
     show it.
   - `status: 201` on a create. A delete returns `{ id, deleted: true }`.
   - `mcp`: write the description for a model, not a person: when to call
     it and what comes back. Destructive tools get
     `annotations: { destructiveHint: true }`. Leave `mcp` out for an
     endpoint assistants shouldn't use.

5. **Register them** in `packages/api/src/operations/index.ts` (`operations`).

6. **Route files.** `apps/web/src/app/(api)/api/v1/<path>/route.ts`, one line
   per method. `{id}` in the path is a `[id]` folder:

   ```ts
   import { operations } from "@repo/api";
   import { route } from "@repo/api/http";

   export const GET = route(operations.listNotes);
   export const POST = route(operations.createNote);
   ```

   `api/v1/routes.test.ts` fails until each operation has its line and each
   line has its operation.

7. **Server actions**, if the web app needs the resource: an `actions.ts`
   next to the page calls the service with `sessionCaller(await
   requireSession())`, and returns `{ data }` or `{ error }` (see
   `app/[locale]/(app)/projects/actions.ts`).

8. **Tests**, in `packages/api/src/api.test.ts`. The shared keys
   (`writeKey`, `readKey`, `otherKey`) already carry every permission, new
   ones included. Add the resource's fields to the `Body` type at the top.
   Then a `describe` block like `REST`:
   - create, read, update, delete, and a page of a list;
   - a refusal: a write with `readKey` gets 403 `insufficient_scope`;
   - another user's rows stay hidden (`otherKey`);
   - if the project has teams, a team key sees the team's rows (copy the
     `Teams` block);
   - the MCP tool list for a read key and a write key (copy the `MCP` block).

9. **Docs**, in `apps/docs/docs/` and each translation in
   `apps/docs/docs/<locale>/`: add the tools to the table in `mcp.mdx`, and
   a sentence about the resource in `index.mdx` if it is new. The API
   reference updates itself from the operations.

## Check

```sh
pnpm typecheck && pnpm test && pnpm lint
pnpm --filter docs spec    # with apps/docs: writes openapi.json; check it lists them
```

With a database and `pnpm dev` running, and an API key:

```sh
curl localhost:3000/api/v1/notes -H "Authorization: Bearer <key>"
```

Wersje

RepozytoriumWynikLicencja
Ta strona · TurbineKit/turbinekit100MIT
mthines/lorekit100MIT
kavo-labs/kavo100MIT

Migawka bazy z 13.11.2026 · wersja paczki 64d34ebbcb1e (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100add-locale
    Dodaje nowy język do projektu TurbineKit: stronę, e-maile, strony prawne, dokumentację API i baner zgody.
  • 86add-resource
    Dodaje zasób REST do API Django REST Framework: model, migrację, admina, serializer, widoki, trasy i testy.
  • 100api-first
    Tworzy i implementuje endpointy REST lub zasoby w projekcie Spring Boot, zwłaszcza z fragmentu lub specyfikacji OpenAPI: kontrolery, CRUD oraz operacje POST, GET, PUT, PATCH i DELETE.
  • 86add-resource
    Dodaje zasób lub endpoint REST do API Hono, wraz ze schematami zod, handlerami i testami kontraktowymi.
  • 100add-module
    Dokłada do istniejącego projektu TurbineKit brakujące moduły, np. zespoły, panel administracyjny, płatności, analitykę lub zgody.
  • 100api-design
    Projektuje kontrakty REST, GraphQL i OpenAPI przed implementacją w podejściu API-first.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.