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