Agent skill

defineRoute Route Builder

Creates new API endpoints, and converts older ones, with the defineRoute() pattern used in cod-server, including auth strategies, scopes and OpenAPI output.

Apache-2.0Auto-check passedBackend & APIs

Install defineRoute Route Builder

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/route-builder .claude/skills/route-builder && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .claude/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/route-builder .agents/skills/route-builder && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .agents/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/route-builder .cursor/skills/route-builder && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .cursor/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/bighadj22/codflow.git --path .agents/skills/route-builder

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/route-builder .gemini/skills/route-builder && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .gemini/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/route-builder .github/skills/route-builder && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .github/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add bighadj22/codflow --skill route-builder -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install bighadj22/codflow route-builder --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bighadj22/codflow.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/route-builder .opencode/skills/route-builder && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "route-builder" agent skill from https://github.com/bighadj22/codflow/tree/main/.agents/skills/route-builder into .opencode/skills/route-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "route-builder", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: route-builder
GitHub stars: 346
Token cost: ~924 tokens
SKILL.md length: 205 words
Files: 4
Skills in repo: 11
Repo updated: Oct 6, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

Creates new API endpoints, and converts older ones, with the defineRoute() pattern used in cod-server, including auth strategies, scopes and OpenAPI output.

Works in 2 steps: Creating new endpoints — see… → Migrating existing endpoints — see…
Adding a new endpoint to cod-server
SKILL.md covers Quick Reference, Auth Strategies, What defineRoute() generates… and Key Rules, plus 1 more section
Calls npm

What it does

In cod-server every endpoint is meant to use `defineRoute()`, and all existing domains are already migrated, so any leftover raw `createRoute()` route should be converted. The skill splits the work into two guides, `NEW-ENDPOINTS.md` for creating endpoints and `MIGRATION.md` for converting old ones, with real examples in `EXAMPLES.md`.

An `auth` setting picks the strategy, for example `public` for webhook receivers, `api-key` for any signed-in dashboard user, `admin` for admin-only routes, or a scope object built from `SCOPES` constants. `defineRoute()` generates the middleware, the security entry, standard 400, 401, 403, 404 and 500 responses, tags from the path and an operationId from the handler name. Rules: no magic scope strings, specific paths registered before parameter paths, shared schemas imported from `@/openapi/schemas`, and typecheck plus tests run after every migration.

When your agent uses it

Adding a new endpoint to cod-server
Converting a leftover createRoute() handler to defineRoute()
Choosing an auth strategy or scope for a route
Handling a multipart upload or webhook headers in a route definition

Example prompts

“Add an endpoint that lists orders, protected by the orders read scope.”
“Migrate the raw createRoute() routes in the orders domain to defineRoute().”
“Create a public webhook receiver route that validates svix headers.”

Requirements

The cod-server codebase with its `@/lib/route-builder` module
npm to run typecheck and tests

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

Creating new endpoints — see NEW-ENDPOINTS.md
Migrating existing endpoints — see MIGRATION.md

What it can do on your machine

Read from SKILL.md and the folder at commit ed79aa9. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- npm
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

defineRoute Route Builder loads about 924 tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 205 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~44
When it runs · the whole SKILL.md, loaded when a task matches: ~924

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from bighadj22/codflow at commit ed79aa9, republished under its Apache-2.0 licence (© bighadj22). 205 words, ~924 tokens.

Download SKILL.mdSave it as .claude/skills/route-builder/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.

name: route-builder
description: Build and migrate API routes using the defineRoute() pattern. Use when creating new endpoints OR migrating existing endpoints to the standard route-builder syntax.

Route Builder Pattern

defineRoute() is the standard pattern for all endpoints in cod-server. Every new endpoint must use it. All existing domains are already migrated — if you encounter a raw createRoute() route, convert it using the migration workflow.

Two workflows:

Creating new endpoints — see NEW-ENDPOINTS.md
Migrating existing endpoints — see MIGRATION.md

Real-world examples from the codebase: EXAMPLES.md

Quick Reference

typescript

import { defineRoute } from "@/lib/route-builder";
import { SCOPES } from "../../../../cod-shared/rbac/scopes";

const myRoute = defineRoute({
  method: "get",           // "get" | "post" | "patch" | "delete" | "put"
  path: "/my-resource",
  auth: { scope: SCOPES.RESOURCE_READ },
  tags: ["MyTag"],
  summary: "List resources",
  operationId: "listResources",
  query: MyFiltersSchema,  // optional
  params: MyParamsSchema,  // optional
  body: MyBodySchema,      // optional
  responses: {             // optional: only when default responses are not enough
    200: { description: "...", content: { "application/json": { schema: MySchema }}},
    422: { description: "Business rule violation" },
  },
  handler: handlers.myHandler,
});

router.openapi(myRoute.route, myRoute.handler);

Auth Strategies

typescript

auth: "public"                            // No auth — no middleware, security omitted from spec (webhook receivers)
auth: "api-key"                           // Any authenticated dashboard user
auth: "admin"                             // Admin role only (stores, users)
auth: "store"                             // Store API key (X-Store-API-Key) — store/*, abandoned-orders storefront
auth: { scope: SCOPES.ORDERS_READ }       // Specific scope (most common)
auth: { anyOf: [SCOPES.READ, SCOPES.ALL] }   // Any of multiple scopes
auth: { allOf: [SCOPES.READ, SCOPES.ADMIN] } // All scopes required

Non-JSON request bodies use bodyContent (raw content map):

typescript

bodyContent: {
  "multipart/form-data": {
    schema: z.object({ file: z.instanceof(File).openapi({ type: "string", format: "binary" }) }),
  },
}

Header schemas (e.g. svix webhook receivers): headers: MyHeadersSchema.

What `defineRoute()` generates automatically

middleware — from auth strategy
security — ApiKeyAuth or StoreAuth
Standard error responses: 400, 401, 403, 404, 500
tags — inferred from path if not provided
operationId — from handler name if not provided

Override only what you need to customize via responses: {...}.

Key Rules

Always use SCOPES constants — never magic strings
- ✅ auth: { scope: SCOPES.ORDERS_READ }
- ❌ auth: { scope: "orders:read" }
Register specific paths before param paths
- ✅ POST /bulk-dispatch before GET /{id}
- ✅ GET /default/rules before GET /{id}
Schemas come from domain files in @/openapi/schemas
- ✅ import { OrderListItemSchema } from "@/openapi/schemas"
- ❌ Inline anonymous schemas for entities that have domain schemas
Always run typecheck + tests after migrating
bash
```
cd cod-server && npm run typecheck && npm test
```

Files

SKILL.md — this file
MIGRATION.md — how to migrate existing endpoints
NEW-ENDPOINTS.md — how to create new endpoints
EXAMPLES.md — real examples from wilayas and orders

Files

SKILL.md and 3 other files in .agents/skills/route-builder of bighadj22/codflow.

SKILL.md
EXAMPLES.md
MIGRATION.md
NEW-ENDPOINTS.md

Open the folder on GitHubat commit ed79aa9

Compare with similar skills

defineRoute Route Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

defineRoute Route Builder compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
defineRoute Route Builder this skillbighadj22/codflow	346	—	~924	Automated safety check: Pass	Apache-2.0	2 days ago
API ContractChenyCHENYU/Robot_Admin	1k	—	~1.9k	Automated safety check: Pass	MIT	today
API And Namespace Designiflytek/skillhub	5.2k	—	~1.3k	Automated safety check: Pass	Apache-2.0	today
API Designeraiskillstore/marketplace	430	1 repos	~3.6k	Automated safety check: Pass	None	yesterday
API DesignerJeffallan/claude-skills	12k	2 repos	~2k	Automated safety check: Pass	MIT	5 days ago
OpenAPI to MCP Servermcp-use/mcp-use	11k	—	~5.2k	Automated safety check: Pass	Apache-2.0	today

Similar skills

API Contract
ChenyCHENYU/Robot_Admin
A skill your agent uses when: generating TypeScript API layer (type definitions + request functions) from page-spec JSON or Swagger/OpenAPI docs.
1k GitHub stars~1.9k tokensUpdated today
Backend & APIsAuto-check passed
API And Namespace Design
iflytek/skillhub
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
5.2k GitHub stars~1.3k tokensUpdated today
Backend & APIsAuto-check passed
API Designer
aiskillstore/marketplace
Design and document RESTful and GraphQL APIs with OpenAPI/Swagger specifications, authentication patterns, versioning strategies, and best practices.
430 GitHub starsUsed in 1 repo~3.6k tokens
Backend & APIsAuto-check passed
API Designer
Jeffallan/claude-skills
Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.
12k GitHub starsUsed in 2 repos~2k tokens
Backend & APIsAuto-check passed
OpenAPI to MCP Server
mcp-use/mcp-use
Turns an OpenAPI or Swagger spec into an MCP server with the mcp-use TypeScript SDK, mapping each operation to a tool, wiring auth, testing and deploying.
11k GitHub stars~5.2k tokensUpdated today
Backend & APIsAuto-check passed
Old Coder API Design
AmazingAng/old-coder
Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers.
749 GitHub starsUsed in 1 repo~3.4k tokens
Backend & APIsAuto-check passed

Questions about defineRoute Route Builder

What does defineRoute Route Builder do?

Creates new API endpoints, and converts older ones, with the defineRoute() pattern used in cod-server, including auth strategies, scopes and OpenAPI output. In cod-server every endpoint is meant to use `defineRoute()`, and all existing domains are already migrated, so any leftover raw `createRoute()` route should be converted.md`.

When should I use defineRoute Route Builder?

defineRoute Route Builder fits situations like: adding a new endpoint to cod-server; converting a leftover createRoute() handler to defineRoute(); choosing an auth strategy or scope for a route; handling a multipart upload or webhook headers in a route definition.

How do I install defineRoute Route Builder in Claude Code?

Run `npx skills add bighadj22/codflow --skill route-builder -a claude-code`. Or copy the skill folder (.agents/skills/route-builder in bighadj22/codflow) into .claude/skills/route-builder in your project. Claude Code loads it when a task matches its description.

How do I install defineRoute Route Builder in Codex?

Run `npx skills add bighadj22/codflow --skill route-builder -a codex`. Or copy the skill folder (.agents/skills/route-builder in bighadj22/codflow) into .agents/skills/route-builder in your project. Codex loads it when a task matches its description.

Can I use defineRoute Route Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add bighadj22/codflow --skill route-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/route-builder, .gemini/skills/route-builder, .github/skills/route-builder and .opencode/skills/route-builder in your project.

What does defineRoute Route Builder need to run?

Going by SKILL.md and its folder, defineRoute Route Builder needs the command-line tools its instructions call (npm). Our summary lists: The cod-server codebase with its `@/lib/route-builder` module; npm to run typecheck and tests.

Does defineRoute Route Builder access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is defineRoute Route Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does defineRoute Route Builder use?

defineRoute Route Builder is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does defineRoute Route Builder use?

About 924 tokens (SKILL.md is roughly 3.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to defineRoute Route Builder?

Skills that share tags, products or a category with defineRoute Route Builder: API Contract (ChenyCHENYU/Robot_Admin, 1k stars), API And Namespace Design (iflytek/skillhub, 5.2k stars), API Designer (aiskillstore/marketplace, 430 stars) and API Designer (Jeffallan/claude-skills, 12k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains defineRoute Route Builder?

bighadj22 (a GitHub user) maintains it in bighadj22/codflow, which has 346 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 6, 2026.

Source: bighadj22/codflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

defineRoute Route Builder

Install defineRoute Route Builder

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Route Builder Pattern

Quick Reference

Auth Strategies

What `defineRoute()` generates automatically

Key Rules

Files

Files

Compare with similar skills

Similar skills

API Contract

API And Namespace Design

API Designer

API Designer

OpenAPI to MCP Server

Old Coder API Design

More from bighadj22/codflow

Yalidine Delivery Integration

Meta Pixel and Conversions API Reference

CodFlow Change Workflow

COD CRM Customer Management

EcoTrack Courier Integration

CodFlow Storefront Vercel Deploy

Questions about defineRoute Route Builder

Install defineRoute Route Builder

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Route Builder Pattern

Quick Reference

Auth Strategies

What defineRoute() generates automatically

Key Rules

Files

Files

Compare with similar skills

Similar skills

More from bighadj22/codflow

Related

Questions about defineRoute Route Builder

What `defineRoute()` generates automatically