agentleFS
JoviDeCroockJoviDeCroock/pracht/skills/pracht-scaffold/SKILL.md

pracht-scaffold

Skill113 starsChanged 7 months agoMITView on GitHub

Generate pracht routes, shells, middleware, API routes, and capabilities with `pracht generate`, editing by hand only when the flags cannot express the shape. Use for "scaffold", "generate a route", "create a new page", "add middleware", "add an API route", "create a shell", "generate a capability".

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    If the CLI can express the request, do not reimplement the scaffold by hand.

    line 37
  2. Distinctive:

    Before and after scaffolding:

    line 101
  3. Very specific:

    Read pracht inspect routes --json / pracht inspect api --json to confirm current wiring when the existing graph matters.

    line 103
  4. Very specific:

    If src/routes.ts declares constraints:, respect them — e.g.

    line 106
  5. Very specific:

    Run pracht typegen after adding or renaming routes in a typed-routes app (src/pracht-routes.ts / .d.ts), and include the generated files.

    line 110
  6. Very specific:

    Run pracht plan --write if the app commits .pracht/app-graph.json — pracht verify fails on a stale snapshot.

    line 112
  7. Very specific:

    Only for shapes the CLI cannot express.

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

Pracht Scaffold

Parse what the user wants to create and generate it with the CLI. Ask when something is ambiguous (render mode, shell assignment). Keep generated code minimal — only the exports they actually need — and finish by summarizing what was created and how it was wired.

Always try the CLI first

pracht generate route --path /dashboard --render ssr
pracht generate shell --name app
pracht generate middleware --name auth
pracht generate api --path /health --methods GET,POST
pracht generate capability --name notes.search --effect read --expose http,mcp --description "Search notes"

If the CLI can express the request, do not reimplement the scaffold by hand. pracht generate route covers this flag matrix:

FlagMeaning
--path (required)Route path, e.g. /dashboard or /blog/:slug
--renderssr (default), spa, ssg, or isg
--shellRegistered shell name (manifest apps only)
--middlewareRegistered middleware names, comma-separated (manifest apps only)
--loaderInclude a loader export
--error-boundaryInclude an ErrorBoundary export
--static-pathsInclude getStaticPaths (automatic for dynamic ssg/isg paths)
--titlePage title for the head() export
--revalidateISG window in seconds (isg only, default 3600)
--jsonMachine-readable output

generate shell and generate middleware take --name; generate shell --loader adds a shell loader export read in the shell with useShellData() (layout-level data such as the signed-in user). generate api takes --path and --methods. generate capability takes --name (dot-separated), --effect (read default, write, destructive), --expose (http,webmcp,mcp; omit to keep it private), --title, and --description (required when exposed). All subcommands accept --json — use it when another agent or tool consumes the output. When the pracht MCP server is registered (pracht dev-mcp), call the matching generate_* MCP tool instead of Bash.

  • --shell/--middleware names must already be registered or the CLI errors. Generate the shell or middleware first, then the route referencing it.
  • Pages-router apps have one middleware seam: pracht generate middleware --name _middleware scaffolds the root src/pages/_middleware.ts, which runs on every page route (API routes are not wrapped). Other names error in pages mode, pure static exports cannot use request middleware, and generate shell stays manifest-only — pages apps add an _app.tsx to the directory they want it to wrap (src/pages/blog/_app.tsx registers pages:blog).
  • generate capability works in both modes. Manifest apps get a capabilities registry entry; pages apps auto-discover src/capabilities/, so the module declares its own name and no manifest is written. Pages agents and constraints are named exports in src/pages/_app.config.ts.
  • generate route also emits a Playwright smoke test in e2e/ when the app has a Playwright setup (playwright.config.* or an e2e/ directory); --no-test skips it, --test forces it. The test imports @playwright/test — if that dependency is missing, follow the generator's install note before typechecking. Keep the test: it is the output-level proof the route works.
  • The generators wire the manifest themselves. generate route inserts the route(...) call into src/routes.ts (adding route/timeRevalidate imports as needed) and generate shell/generate middleware upsert their registry entries. Do not re-edit the manifest after a successful run.

Project conventions

KindDirectoryKey exports
Routesrc/routes/loader, head, Component, ErrorBoundary, getStaticPaths, search
Shellsrc/shells/Shell, loader (read with useShellData()), head, headers, Loading, ErrorBoundary
Middlewaresrc/middleware/middleware
API routesrc/api/Named method handlers (GET, POST, PUT, PATCH, DELETE) or one default dispatcher

Render modes: "ssr" (default), "ssg" (static at build), "isg" (incremental static, revalidate: timeRevalidate(seconds) — import timeRevalidate from @pracht/core), "spa" (client-only). Use Preact idioms: class not className, functional components, import type for type-only imports.

Before and after scaffolding:

  • Read pracht inspect routes --json / pracht inspect api --json to confirm current wiring when the existing graph matters. pracht inspect needs the pracht plugin in the vite config.
  • If src/routes.ts declares constraints:, respect them — e.g. put new /app/** routes behind the required middleware. Never delete or weaken a constraint to make pracht verify pass; that is a policy change only the user can approve.
  • Run pracht typegen after adding or renaming routes in a typed-routes app (src/pracht-routes.ts / .d.ts), and include the generated files.
  • Run pracht plan --write if the app commits .pracht/app-graph.json — pracht verify fails on a stale snapshot.
  • Finish with pracht verify.

Manual fallback

Only for shapes the CLI cannot express. Read the existing src/routes.ts first to pick up current shells, middleware, and structure.

Route — head() plus Component; add loader whenever the page needs data to render (the CLI omits it unless --loader is passed) rather than fetching it in a useEffect, ErrorBoundary only if requested, and getStaticPaths only for SSG/ISG routes with dynamic segments:

import type { LoaderArgs, RouteComponentProps } from "@pracht/core";

export async function loader(_args: LoaderArgs) {
  return {/* loader data */};
}

export function head() {
  return { title: "Page Title" };
}

export function Component({ data }: RouteComponentProps<typeof loader>) {
  return <section>{/* route UI */}</section>;
}

Shell — Shell({ children }: ShellProps) rendering {children}, plus an optional head(). Never render <html>, <head>, or <body>.

Middleware — wrap-around via next():

import { redirect, type MiddlewareFn } from "@pracht/core";

export const middleware: MiddlewareFn = async ({ context, request }, next) => {
  // `return next()` continues; returning any Response short-circuits, e.g.
  // `redirect("/path", { request })`. Wrap `await next()` in try/catch/finally
  // for tracing.
  return next();
};

API route — one export per method the user needs (or a default export only when they want to branch on request.method manually), parsing bodies with request.json() / request.formData() and always returning a Response:

import type { ApiRouteArgs } from "@pracht/core";

export function GET({ params, url }: ApiRouteArgs) {
  return Response.json({/* response data */});
}

Dynamic segments use bracket filenames: [id].ts, [...slug].ts. API routes are auto-discovered — no manifest entry.

For live server→client updates, use Server-Sent Events: createEventStream(request, { keepAlive: 15 }) from @pracht/core/server returns { response, send, close } — return response, push with send({ data, event?, id? }), and stop producing when send() returns false (client disconnected). Consume with useEventSource(url, { json: true }) from @pracht/core. Works on every adapter. For WebSockets use isUpgradeRequest(request) plus the per-adapter recipes (Cloudflare: API route + Durable Object, https://pracht.resynapse.dev/docs/adapters/cloudflare#websockets; Node: nodeAdapter({ configureServerFrom }), https://pracht.resynapse.dev/docs/adapters/node#websockets; Vercel: unsupported — use SSE).

Manifest wiring, only for hand-created files:

  • Route — a route("/path", () => import("./routes/file.tsx"), { id: "name", render: "ssr" }) call in the right group or at the top level.
  • Shell — shellName: () => import("./shells/file.tsx") in the shells record.
  • Middleware — mwName: () => import("./middleware/file.ts") in the middleware record.

Plain "./routes/file.tsx" strings work in place of the import functions.

$ARGUMENTS

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.