josecabralf-skills

Skills

Agent skills for practical engineering work: disciplined debugging, test-driven development, planning, documentation, and codebase design. They are intentionally small and hackable. Read them and edit them to fit your workflow.

Quick Setup

Install with the skills CLI:

npx skills@latest add josecabralf/skills

Or clone the repo and symlink every skill into ~/.claude/skills/ for Claude Code. Symlinks keep the installed skills in sync with the working copy:

./scripts/link-skills.sh

Or copy a single skill directory by hand:

cp -r skills/diagnosing-bugs ~/.claude/skills/

scripts/list-skills.sh prints every SKILL.md in the repo. .claude-plugin/plugin.json declares the skills for installs through the Claude Code plugin system.

What These Skills Are For

Closing the gap between what you meant and what the agent built

• grill-me — get interviewed about a plan until every branch of the decision tree is resolved, before any code is written.
• grill-with-docs — grilling session that challenges your plan against the existing domain model, sharpening terminology and updating docs inline.
• grilling — a relentless interview that walks down every decision branch, with recommended answers per question.
• handoff — compress a long conversation into a document the next session can pick up.
• prototype — build a throwaway prototype (terminal app or toggleable UI variations) to flesh out a design before committing.

Keeping code correct through feedback loops

• tdd — red-green-refactor, enforced.
• diagnosing-bugs — disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
• write-unit-tests / assess-unit-tests — author tests worth keeping, and audit the ones you already have.

Designing and modelling code

• codebase-design — design "deep modules" (lots of behaviour behind a small interface placed at a clean seam) for testability and leverage.
• domain-modeling — build and sharpen your project's domain model by challenging terms, inventing edge-case scenarios, and writing a glossary.
• improve-codebase-architecture — scan a codebase for "deepening opportunities" (refactors that turn shallow modules into deep ones) surfaced as an HTML report.

Turning plans into work and decisions into prose

• to-issues — break a plan or PRD into independently-grabbable issues using tracer-bullet vertical slices.
• to-prd — synthesise the current conversation and codebase understanding into a PRD and publish it to the issue tracker.
• document — write docs classified by Diátaxis type, gated behind technical review and command testing.
• write-agents-md / write-for-human — write high-signal agent instructions and human-facing prose that follow removal-test and style guidelines.
• writing-great-skills — reference for writing and editing skills well, centred on predictability and determinism.
• teach — teach the user a new skill or concept across multiple sessions with a structured workspace and lesson plans.

Skills Reference

Engineering

• diagnosing-bugs — Disciplined diagnosis loop for hard bugs and performance regressions.
• tdd — Test-driven development with a red-green-refactor loop.
• to-issues — Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker.
• to-prd — Turn conversation context into a PRD and publish it to the issue tracker.
• codebase-design — Design deep, testable modules using a shared vocabulary for code structure.
• improve-codebase-architecture — Surface architectural friction and propose deepening opportunities.
• domain-modeling — Build a project's domain model with a glossary and ADRs.
• prototype — Build throwaway prototypes to flesh out a design before committing.
• teach — Teach a new skill or concept across multiple sessions.

Testing