skillbrief

Generate Agent Skills (SKILL.md) from a real repository. Zero npm dependencies.

codebrief tells an agent what the repo is.
skillbrief tells the agent how to work in it — on demand, without stuffing always-on rules.

Why

Cursor, Claude Code, Codex, and other agents now load Agent Skills: a folder with SKILL.md whose description decides when to activate. Blank scaffolds (npx skills init) do not know your stack. skillbrief scans the project and writes procedures that match what is actually there.

What it generates (only if detected):

| Skill | When it appears | | --- | --- | | working-in-<project> | Always. Package manager, scripts, folders, verify steps | | nextjs-in-this-repo | Next.js | | database-changes | Prisma, Drizzle, Supabase, … | | running-tests | Vitest, Jest, Playwright, … | | styling-ui | Tailwind, shadcn/ui, other UI kits | | api-changes | tRPC, Express, Hono, Nest, Fastify | | auth-changes | NextAuth, Clerk, … |

Each skill is a valid Agent Skill: YAML frontmatter (name + description), “when to use / when not to use”, and a short references/ file on the core skill so the body stays small.

Quick start

npx skillbrief

Writes:

• .agents/skills/<name>/SKILL.md — portable (Cursor, Codex, and other clients that read the open layout)
• .cursor/skills/<name>/SKILL.md — Cursor

npx skillbrief --for claude          # also .claude/skills
npx skillbrief --for all             # agents + cursor + claude
npx skillbrief --list                # preview, no writes
npx skillbrief --dry-run
npx skillbrief --force               # overwrite
npx skillbrief --update              # add missing, keep existing
npx skillbrief --only running-tests,database-changes

Global install:

npm install -g skillbrief
skillbrief

Node.js 16+. No extra packages.

Pair with codebrief

| Tool | Job | Loads | | --- | --- | --- | | codebrief | Stack, tree, CONTEXT.md, Cursor rules, AGENTS.md | Always / every chat | | skillbrief | Procedures: how to add a page, migrate, test | Only when the task matches |

Keep always-on rules short. Put workflows in skills so context stays cheap.

Options

| Flag | Description | Default | | --- | --- | --- | | --depth <n> | Max scan depth | 4 | | --output <dir> | Project root to write into | cwd | | --for <ids> | agents, cursor, claude, all | agents,cursor | | --only <ids> | Emit a subset of skill ids | all planned | | --list | Print planned skills | | | --dry-run | Show paths, write nothing | | | --force | Overwrite existing skills | | | --update | Write only missing skills | | | -h / --help | Help | | | -v / --version | Version | |

Ignore extra paths with .skillbriefignore or .gitignore.

Spec

Output follows the Agent Skills specification:

• name is lowercase, hyphenated, and matches the folder name
• description includes what and when (max 1024 characters)
• Optional references/ for stack details (progressive disclosure)

License

MIT © Murat Hüdavendigâr Öncü