agentleFS
linjiejimlinjiejim/greenhouse/.claude/skills/add-api-route/SKILL.md

add-api-route

Skill3 starsChanged 21 days agoMITView on GitHub

Add a Hono API route to Greenhouse: core route under apps/api/src/routes (endpoint comment block, chained new Hono<AppEnv>(), guards, db services, one line in mountRoutes) or a plugin route under plugins/<id>/api (defineExtension routes on /api/ext/<id>, or a dataSource instead of hand-written CRUD), then tests. Use for: add an endpoint / API / route, 加个接口, 新增 API, 加条路由, 写个 endpoint. Red lines: chain the definition (statement-style drops it from AppType), no any in a response, never reorder mountRoutes, plugins import only @greenhouse/api/extension-kit.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. vaultys/VaultysClaw★ 85same name
    2. bmarshall511/forexflow★ 14same name
    3. skillist-io/skillist★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Import from ../auth/middleware.js: requireSuper(), requireInternal(), requireRole('team', 'super'), requireFeature('<flag>').

    line 52
  2. Very specific:

    Import only @greenhouse/api/extension-kit (getDb, getExtensionServices, getAuthUser, guards, AppEnv, humanActor, recordWrite, notify, …

    line 59
  3. Very specific:

    Never fetch a model-supplied URL directly: fetchPublicImage() / fetchPublicPage() (security/network.ts).

    line 72

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add an API route

Source of truth: apps/api/src/AGENTS.md (routes, security, uploads) and EXTENDING.md (plugin routes and data sources). This skill is the order of work; on conflict those files win.

Decide first

  • Core or plugin: core owns identity, conversations, models, tools/runs, MCP/connectors, automations, Files, notifications, settings, plugin host and admin; everything else is a plugin under plugins/<id>/.
  • Table-backed plugin entity: declare a dataSource instead of hand-written CRUD; the host generates guarded /api/ext/<plugin>/entities/<entity> REST with scopes, field policy and audit.
  • Missing db service: do add-db-table first.
  • Access level: internal (team + super), super only, or a feature flag; core feature flags are empty, flags come from plugins.

Core route

  • One resource per file: apps/api/src/routes/<resource>.ts, starting with an endpoint comment block (method, path, purpose per line).
  • Chain the definition; statement-style x.get(...) drops endpoints from AppType, and factories never declare a : Hono return type.
/**
 * Widgets — /api/widgets
 * GET  /api/widgets      list the caller's widgets
 * POST /api/widgets      create one
 */
import { Hono } from 'hono';
import { getDb } from '@greenhouse/db';
import { getAuthUser } from '../auth/middleware.js';
import type { AppEnv } from '../app-env.js';

const widgetRoutes = new Hono<AppEnv>()
  .get('/', async (c) => {
    const user = getAuthUser(c);
    return c.json({ widgets: await getDb().widgets.listByUser(user.id) });
  })
  .post('/', async (c) => {
    /* validate with zod, write through the service */
  });
export default widgetRoutes;
  • Responses never contain any: one any field collapses the inferred response to never; give raw SQL rows a shape first.
  • Mount it with one .route('/api/<resource>', routes) in mountRoutes() (apps/api/src/index.ts); its order has security meaning (OAuth first, public callbacks before wildcard role guards). Never reorder.
  • export type AppType in index.ts is the typed route contract; keep it compiling instead of adding parallel types.
  • Public paths go only through PUBLIC_PATHS / isPublicPath (auth/middleware.ts), each with a reason; /api/mcp… and /api/gateway… are owned prefixes.

Guards

  • Import from ../auth/middleware.js: requireSuper(), requireInternal(), requireRole('team', 'super'), requireFeature('<flag>'); read the caller with getAuthUser(c).
  • /api/x/* does not match the bare /api/x: guard both, mount writes on a sub-path, or put .use('*', requireInternal()) inside the router (search, refs, people, activity do).
  • Feature checks in code use userHasFeature, never a raw user_features read; UI hiding never replaces a route check.

Plugin route

  • In plugins/<id>/api: routes: [{ path: '/api/ext/<id>', app, guards: [requireFeature('<id>')] }] inside defineExtension; the host applies guards to the path and its /* (mountExtensionRoutes in apps/api/src/plugin-host/boot.ts).
  • Reference: plugins/example/api/routes.ts and plugins/example/api/index.ts.
  • Import only @greenhouse/api/extension-kit (getDb, getExtensionServices, getAuthUser, guards, AppEnv, humanActor, recordWrite, notify, logger …), shared types and own files.
  • New routes use /api/ext/<id>; official packages keep their legacy prefixes; aliases cannot replace core routes.
  • Protected writes go through the platform runtime (runtime.dispatch) or recordWrite; do not build a parallel permission or audit path.
  • Writes reject unknown, immutable or forbidden fields atomically, even for super; ids and storage timestamps are never caller input.
  • Callback or webhook exceptions go in publicPaths with a reason; throttling in rateLimits.
  • Plugin routes are not part of AppType.

Implementation rules

  • Data only through getDb().<domain>.<method>() (plugins: their service bag); no SQL in routes.
  • Log with logger.info/warn/error (@greenhouse/utils/logger); console.* only in cli/.
  • Model-bound user input passes sanitizeForPrompt() (security/security.ts).
  • Rate limits use checkRateLimit (security/security.ts); client IPs come only from security/request-ip.ts.
  • Uploads verify MIME with validateMagicBytes() and store only through storage/uploads.ts.
  • Never fetch a model-supplied URL directly: fetchPublicImage() / fetchPublicPage() (security/network.ts).
  • Errors are { error: '<words>' }, name the next step and quote interpolated values: (ID: "${id}").
  • Writes record the acting user; paid calls go through usage/metering.ts.
  • A client that starts calling the new endpoint raises MOBILE_API_LEVEL (routes/bootstrap.ts) with the client's MOBILE_API.

Tests

  • Route and permission tests: tests/api/ or apps/api/src/routes/tests/; real-DB cases are *.db.test.ts (transaction rolled back per test).
  • Plugin route tests sit beside the plugin (plugins/<id>/api/tests/); cover enabled and disabled, denials and field rejection.
  • Auth, isolation and escalation cases go to tests/e2e/*.e2e.test.ts (pnpm test:e2e:ci, real HTTP against a dead LLM endpoint).
  • Build fixtures from returned ids; never assume fixed ids.

Gate

pnpm typecheck
pnpm lint
TEST_DATABASE_URL=<loopback test db> pnpm test
DATABASE_URL=<loopback e2e db> pnpm test:e2e:ci   # when auth, permissions or isolation changed

Checklist

  • Core vs plugin decided; data source considered for plugin CRUD
  • Endpoint comment block; chained definition; no : Hono annotation; no any in responses
  • Guards right, bare path covered; public path registered with a reason if any
  • Mounted in mountRoutes() without reordering (core) or via defineExtension routes (plugin)
  • Services, logger, sanitizeForPrompt, rate limit and network helpers used
  • Error text names the next step and quotes values
  • Tests at the right layer; gate green

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.