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".
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-authSkill
- add-capabilitiesSkill
- add-contentSkill
- add-dbSkill
- add-i18nSkill
- add-imagesSkill
- add-observabilitySkill
- add-openapiSkill
- audit-a11ySkill
- audit-agent-surfaceSkill
- audit-authSkill
- audit-bundlesSkill
- audit-csrfSkill
- audit-depsSkill
- audit-headersSkill
- audit-islandsSkill
- audit-loadersSkill
- audit-redirectsSkill
- audit-secretsSkill
- audit-seoSkill
- audit-shellsSkill
- configure-isgSkill
- migrate-nextjsSkill
- pracht-debugSkill
- pracht-deploySkill
- pracht-test-apiSkill
- pre-deploySkill
- scaffold-e2eSkill
- scaffold-testsSkill
- tune-render-modeSkill
- typed-routesSkill
- upgrade-prachtSkill
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
- Very specific: line 37
If the CLI can express the request, do not reimplement the scaffold by hand.
- Distinctive: line 101
Before and after scaffolding:
- Very specific: line 103
Read pracht inspect routes --json / pracht inspect api --json to confirm current wiring when the existing graph matters.
- Very specific: line 106
If src/routes.ts declares constraints:, respect them — e.g.
- Very specific: line 110
Run pracht typegen after adding or renaming routes in a typed-routes app (src/pracht-routes.ts / .d.ts), and include the generated files.
- Very specific: line 112
Run pracht plan --write if the app commits .pracht/app-graph.json — pracht verify fails on a stale snapshot.
- Very specific: line 118
Only for shapes the CLI cannot express.
≈ “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.
Files
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:
| Flag | Meaning |
--path (required) | Route path, e.g. /dashboard or /blog/:slug |
--render | ssr (default), spa, ssg, or isg |
--shell | Registered shell name (manifest apps only) |
--middleware | Registered middleware names, comma-separated (manifest apps only) |
--loader | Include a loader export |
--error-boundary | Include an ErrorBoundary export |
--static-paths | Include getStaticPaths (automatic for dynamic ssg/isg paths) |
--title | Page title for the head() export |
--revalidate | ISG window in seconds (isg only, default 3600) |
--json | Machine-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/--middlewarenames 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 _middlewarescaffolds the rootsrc/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, andgenerate shellstays manifest-only — pages apps add an_app.tsxto the directory they want it to wrap (src/pages/blog/_app.tsxregisterspages:blog). generate capabilityworks in both modes. Manifest apps get acapabilitiesregistry entry; pages apps auto-discoversrc/capabilities/, so the module declares its ownnameand no manifest is written. Pagesagentsandconstraintsare named exports insrc/pages/_app.config.ts.generate routealso emits a Playwright smoke test ine2e/when the app has a Playwright setup (playwright.config.*or ane2e/directory);--no-testskips it,--testforces 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 routeinserts theroute(...)call intosrc/routes.ts(addingroute/timeRevalidateimports as needed) andgenerate shell/generate middlewareupsert their registry entries. Do not re-edit the manifest after a successful run.
Project conventions
| Kind | Directory | Key exports |
| Route | src/routes/ | loader, head, Component, ErrorBoundary, getStaticPaths, search |
| Shell | src/shells/ | Shell, loader (read with useShellData()), head, headers, Loading, ErrorBoundary |
| Middleware | src/middleware/ | middleware |
| API route | src/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 --jsonto confirm current wiring when the existing graph matters.pracht inspectneeds the pracht plugin in the vite config. - If
src/routes.tsdeclaresconstraints:, respect them — e.g. put new/app/**routes behind the required middleware. Never delete or weaken a constraint to makepracht verifypass; that is a policy change only the user can approve. - Run
pracht typegenafter adding or renaming routes in a typed-routes app (src/pracht-routes.ts/.d.ts), and include the generated files. - Run
pracht plan --writeif the app commits.pracht/app-graph.json—pracht verifyfails 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 theshellsrecord. - Middleware —
mwName: () => import("./middleware/file.ts")in themiddlewarerecord.
Plain "./routes/file.tsx" strings work in place of the import functions.
$ARGUMENTS
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
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.

