skills

Portable SKILL.md workflows for AI-assisted engineering: planning, debugging, TDD, review, documentation, handoff, and release prep.

These skills are plain Markdown instructions. Use them with any agent harness, editor, or chat workflow that can load files, install packages, or accept custom instructions. The npm packages include Pi metadata, but the skills are not Pi-only.

Start here

If you want to...	Read this
Install or load the skills	Setup guide
Decide which skill to use	Workflow guide
Look up every skill quickly	Usage reference
Browse all documentation	Docs index
Release or maintain this package	Maintainer release process

Quick start

1. Install the bundle.

   npm install @barlevalon/skills
   

2. Use the skills.

   Tools with npm skill-package support can load the bundle by package name:

   @barlevalon/skills
   

   Tools that work from files can use the installed SKILL.md files under:

   node_modules/@barlevalon/skills/skills/
   

3. Ask for the workflow by name:

   Use TDD to implement this change.
   

   Diagnose this failure before fixing it.
   

   Prepare the next release and recommend the SemVer bump.
   

See Setup guide for single-skill installs, Pi, Git checkout, copy/paste, and editor-rule options.

Workflow map

Situation	Skills to reach for
New feature, fuzzy idea	write-a-prd, grill-with-docs, prd-to-plan, prototype
Bug or regression	diagnose, then tdd
Behavior change	tdd
Architecture feels tangled	improve-codebase-architecture, zoom-out
Strict review	thermo-nuclear-code-quality-review
Visual explanation or plan review	plannotator-visual-explainer, plannotator-setup-goal, plannotator-compound
Docs work	documentation-system
Release prep	release-prep
Commit message or concise communication	caveman-commit, caveman, caveman-help
Session handoff	handoff
Find more capabilities	find-skills

Skills

Communication

• caveman — concise communication mode.
• caveman-commit — compact, release-aware commit messages.
• caveman-help — quick reference for caveman modes.

Discovery

• find-skills — find installable skills for a task.

Documentation

• documentation-system — write, classify, audit, and restructure docs using the Divio model.

Engineering

• diagnose — disciplined bug/performance diagnosis loop.
• grill-with-docs — stress-test a plan against domain docs and ADRs.
• improve-codebase-architecture — find deeper modules and better seams.
• prd-to-plan — turn a PRD into tracer-bullet implementation phases.
• prototype — build a throwaway prototype to test a design.
• tdd — red/green/refactor implementation loop.
• worktrunk — branch and worktree workflow using Worktrunk.
• write-a-prd — interview, explore, and write a PRD.
• zoom-out — ask for broader context before changing code.

Evaluation

• thermo-nuclear-code-quality-review — strict maintainability review.

Handoff

• handoff — compact a session for another agent.

Release

• release-prep — plan and validate a release without pushing/publishing by accident.

Review

• plannotator-compound — analyze rejected planning feedback and improve future prompts.
• plannotator-setup-goal — turn an objective into a reviewed goal package.
• plannotator-visual-explainer — create self-contained HTML visual explanations.

Package layout

skills/
  <category>/
    <skill>/
      SKILL.md
      package.json
      README.md
      LICENSE

New skills should use skills/<category>/<skill>/SKILL.md, include a local package.json, and keep skill names globally unique. Skill packages version independently from the root bundle.

Credits

• caveman, caveman-commit, caveman-help: based on JuliusBrussee/caveman by Julius Brussee.
• diagnose, grill-with-docs, handoff, improve-codebase-architecture, prd-to-plan, prototype, write-a-prd, zoom-out: based on mattpocock/skills by Matt Pocock.
• find-skills: based on vercel-labs/skills by Vercel.
• worktrunk: based on max-sixty/worktrunk by Maximilian Roos.
• thermo-nuclear-code-quality-review: based on cursor/plugins by Cursor.
• plannotator-*: based on backnotprop/plannotator by backnotprop.

Validate

npm ci
npm run ci

License

MIT