skillbrief

codebrief tells an agent what a repo is. Agents still guess how to add a page, run tests, or touch the UI, because those procedures live in always-on rules or nowhere.

Stuffing every procedure into Cursor rules makes every chat pay for tokens it does not need. Skipping procedures makes the model invent npm scripts and folder layouts.

skillbrief scans a repository and writes Agent Skills — SKILL.md files that load only when the task matches. Next.js, tests, UI, database, API, and auth skills appear only if that stack is actually there. Zero npm runtime dependencies.

On this portfolio, `npx skillbrief` produced working-in-portfolio-nextjs skills plus more specific ones for tests, styling, and Next.js. The committed copy lives under `.agents/skills/` so agents and humans share the same source.

v1 is a safe skeleton, not a senior reading your source. It will omit project-specific paths and can miss a deploy target. Treat the files as a first draft, then add a few human rules.

A second CLI is more to explain than one “AI setup” button. The split is the product: always-on context stays short; skills stay optional and editable.

Published on npm and used on this site before I asked anyone else to try it. The human pass here was small and specific: theme inversion, catalog location in data/projects.json, and a note that Vercel is the host.

Skills are procedures. Always-on context is identity. If you only remember one thing from shipping both tools, keep those jobs apart.

Generate, then write the three rules a scan will never see. If you commit the skeleton unchanged, you taught the agent a generic Next.js app — not yours. Pair with the codebrief case study and the writing post that compares them.