zskills
Z Skills
20 skills that plan, build, test, fix, and ship — so one developer can run a full engineering team.
Z Skills encode hard-won lessons from real agent failures into reusable
prompt files. Each skill is a .claude/skills/SKILL.md file that teaches
Claude Code how to perform a specific workflow with the discipline that
prevents the most common AI agent failure modes: skipping verification,
weakening tests, deferring hard parts, and shipping broken code.
View the full presentation for the architecture, workflow stages, enforcement model, and war stories.
The Skills
Quick Install
# Clone into your project
git clone https://github.com/zeveck/zskills.git zskills
# Tell Claude Code to set up
/setup-zskills install
This installs the 17 core skills, safety hooks, helper scripts, and CLAUDE.md guardrail rules. It prompts for project-specific values (test commands, dev server, source paths).
To update later: /setup-zskills update (pulls latest and syncs).
Skill Catalog
17 Core Skills (skills/)
These work on any software project — web app, CLI tool, API service, game, data pipeline.
Plan
| Skill | Purpose |
|---|---|
/draft-plan |
Adversarial plan drafting: research, draft, devil’s advocate review, refine until converged |
/research-and-plan |
Decompose broad goals into focused sub-plans with dependency ordering |
/research-and-go |
Full autonomous pipeline: decompose, plan, execute — one command, walk away |
/plans |
Plan dashboard: index, status tracking, priority ranking, batch execution |
Build
| Skill | Purpose |
|---|---|
/run-plan |
Phase-by-phase plan execution with worktree isolation, verification gates, and auto-landing |
/do |
Lightweight task dispatcher for ad-hoc work with optional worktree/push/scheduling |
Verify
| Skill | Purpose |
|---|---|
/verify-changes |
7-phase verification: diff review, test coverage audit, test run, manual UI check, fix, re-verify |
/qe-audit |
Quality audit of recent commits — find test gaps, edge cases, file issues |
/investigate |
Root-cause debugging: reproduce, trace, prove the cause with evidence, regression test, fix |
Fix
| Skill | Purpose |
|---|---|
/fix-issues |
Batch bug-fixing sprints: prioritize N issues, dispatch parallel agents, verify, land |
/fix-report |
Interactive sprint review — walk through results, gate landing on user approval |
/review-feedback |
Triage user feedback into GitHub issues: deduplicate, evaluate, file |
Ship
| Skill | Purpose |
|---|---|
/commit |
Safe commit: scope classification, import tracing, fresh review agent, dependency verification |
/briefing |
Project status dashboard: recent commits, worktree status, pending sign-offs |
Support
| Skill | Purpose |
|---|---|
/doc |
Documentation audit, gap-filling, and changelog/newsletter entries |
/manual-testing |
Playwright-cli recipes: real mouse/keyboard events, not eval — test as a user would |
/setup-zskills |
Install, audit, or update Z Skills infrastructure in any project |
Block Diagram Add-on (block-diagram/)
3 additional skills for block-diagram editors. Not part of the core 17 —
install if your project involves visual block diagrams.
See block-diagram/README.md.
What Gets Installed
13 CLAUDE.md Rules
Agent guardrails that prevent the most common failure modes:
- Never weaken tests — fix the code, not the test
- Capture test output to file — never pipe through grep/tail
- Max 2 fix attempts — stop and report, don’t thrash
- Pre-existing failure protocol — verify with git log, skip + file issue
- Never discard others’ changes — ask before touching uncommitted work
- Protect untracked files —
git stash -u, notgit stash - Feature-complete commits — trace imports, verify before staging
- Always write
.landedmarker — so worktrees can be safely cleaned up - Verify worktrees before removing — never batch-remove
- Never defer hard parts — finish the plan, don’t stop after the easy phase
- Correctness over speed — follow instructions exactly, never stub
- Enumerate before guessing — ls/grep first, build from scratch second
- Never skip pre-commit hooks — fix the issue, don’t bypass with –no-verify
Safety Hooks
block-unsafe-generic.sh blocks destructive operations for all agents:
git stash drop/clear,git checkout --,git restore,git clean -fgit reset --hard,kill -9/killall/pkill,fuser -kgit push(all forms — user pushes manually)rm -rf,git add ./git add -A,git commit --no-verify
block-unsafe-project.sh.template adds project-specific enforcement
(configure during install): test-before-commit, UI file verification.
Session Logging
Hooks that convert Claude Code JSONL transcripts to readable markdown
after every session and subagent run. Logs go to .claude/logs/.
Helper Scripts
port.js— deterministic dev server port per worktreetest-all.js— meta test runner (unit + E2E + build tests)briefing.cjs— project status data gathering for/briefing
Extending Z Skills
Add your own skills by creating .claude/skills/<name>/SKILL.md files.
A skill is just a markdown file with YAML frontmatter:
---
name: my-skill
description: What this skill does (used for discovery)
disable-model-invocation: true # only user can invoke
---
# /my-skill — Title
Instructions for the agent...
See any skill in skills/ for the full pattern.
Session Logging
The hooks include a session logging system that converts Claude Code JSONL transcripts to readable markdown after every session. Available as a standalone package: cc-session-logger.
License
MIT