skills

Krish’s Claude Code skills, subagents and dev config.

A personal collection of Claude Code skills, subagents and dev config, shared here so you (or I, on another machine) can install and use them too.

A skill is a directory with a SKILL.md that Claude Code loads into the current conversation when it decides the skill applies (or when you type /). A subagent is a .md file that defines a separate worker with its own context window, model, tool allowlist and preloaded skills; Claude spawns it for isolated work. Skills are “how to do X”; agents are “who does X, with what permissions”.

How to read this repo

Every skill folder has two files: SKILL.md is the prompt Claude follows (frontmatter + instructions), and README.md is for you: what it does, when to use it, how to invoke it, how it works step by step, and an example. Agents are documented together in agents/README.md; each agents/.md is the definition Claude loads. Start with the READMEs; open a SKILL.md only to see or change exact behaviour.

Start here

New to the repo? Check the prereqs, install, then try one skill.

Which skill first

1. grill-docs: zero setup, and it leaves a decision record (skilleddocs/decisions.md unless the repo has its own) the other skills read. Good for seeing what a skill writes.
2. pair: one task end to end in an isolated worktree, you push at the end. The smallest taste of the agents.
3. meta-orchestrator: a whole backlog unattended. Try it last; it is the most autonomous and builds on the two above.

60-second quickstart

In Claude Code:

/plugin marketplace add KrishP147/skills
/plugin install krish@krish

Then (in a new session if it isn’t listed yet) type /krish:grill-docs . Prefer plain /grill-docs names, or no plugin? Use the install script instead (pick one, not both): Install, which also covers flags and the repo-scrub / kanban extras.

Three ways to run work

Each tier builds on the one above: pair is one orchestrator loop without the board, and the orchestrator’s default shape: pair runs pair’s manager once per issue (flat skips the manager; swarm batches trivial issues onto haiku implementers).

What’s here

kanban/ — GitHub-Issues-as-kanban-board workflow

Projects v2 boards need gh auth refresh -s project -s read:project once; label mode doesn’t (see kanban/README.md).

agents/ — subagents pair and the orchestrator spawn

Full explainer (inputs, outputs, procedure, guard hook): agents/README.md. They also work on their own: “use the planner agent to brief the next issue” is a fine prompt without the orchestrator. Set GUARD_PROTECTED_BRANCHES=main,develop to change what the hook protects. Agents can spawn agents (manager → implementer); only the built-in fork type can’t nest.

hooks/ — optional per-repo hooks

Not auto-installed. smartzone.py is a UserPromptSubmit hook that warns in-conversation when the transcript suggests context has left the smart zone (~75k tokens, SMARTZONE_TOKENS), so a session wraps up instead of degrading. spend-guard.py is a PreToolUse hook that blocks known billable commands/MCP calls (GPU pod creation, paid deploys, …) unless an approval token from the spend-gate skill already exists. Copy + settings snippets in hooks/README.md.

site/ — static skills site

Claude-Code-style terminal home (free-typing slash search: ranked matches, aliases, did-you-mean on typos) plus a plain list of every skill, agent and hook, a / page per entry whose README ## Example renders as a Claude Code session, a /workflows page of sample workflows, a /map page of how everything connects, light or dark with the OS theme, generated from this repo by scripts/build_site.py (stdlib only). Served at www.krishpunjabi.com/skills. Build, test and deploy steps in site/README.md.

Attribution and divergences: Third-party skills. Licence: THIRD_PARTY_LICENSES.md.

Where skills write: skilleddocs/

Every skill or agent here that produces a document writes it inside the repo it is working on, under one directory, so any teammate or fresh session finds it in the same place. Committed only if the repo already tracks skilleddocs/ or opts in via AGENTS.md/CLAUDE.md, never on a fork; otherwise left untracked and git-excluded so it can’t leak into a task PR. Full rule: handoff-auto/TRACKING.md:

skilleddocs/
  README.md            what each folder holds (template below)
  bridge.md            cross-session message log — session-bridge
  briefs/              teammate onboarding briefs — teammate-brief
  decisions.md         append-only decision register (D1, D2, ...) — grill-docs, consult-plan, verifier, wayfinder
  experiments.md       setup header, results ledger and next ideas — score-loop
  gaps/                gap-scan reports — gap-scan
  grills/              one transcript per grill-docs session
  handoffs/            session handoffs — handoff, handoff-auto, session-handoff, implementer
  HANDOFF.md           short "stuck" note an implementer leaves for a manager (deleted once picked up; never in a pushed branch)
  orchestrator/        scope.md, ledger.md, orchestrator-handoff.md, reports/ — meta-orchestrator
  pr-watch/            per-pass PR watch logs — pr-watch
  reports/             progress reports + .last-reported watermark — progress-report
  showcase/            showcase inventory and findings — repo-showcase
  spend.md             approval log (when, amount, purpose, price source, resource id) — spend-gate
  spend-approvals/     one-shot approval files consumed by hooks/spend-guard.py — spend-gate

Rules: local dates in filenames, never UTC; the register is append-only (reverse a decision with a new row); nothing under skilleddocs/ is a spec or a roadmap — plans live wherever the repo keeps docs, and skilleddocs/ points at them. The orchestrator commits its files on the default branch as it goes (docs(skilleddocs): ledger NNN), unless docs_commit: uncommitted (always on a fork, per TRACKING.md). A repo’s AGENTS.md / CLAUDE.md can override any path, so older repos with docs/decisions.md or a reports/ folder keep working. Packaging hazard (untracked mode): git-excluding skilleddocs/ does not hide it from setuptools. In a flat-layout Python project, pip install . fails with “Multiple top-level packages discovered” while an untracked skilleddocs/ sits in the tree. Install from a clean clone, or set explicit packages in pyproject.toml; details in TRACKING.md. Skills that only read or act on GitHub (next, divide, kanban-setup, pair, repo-scrub) write nothing here.

Template for a repo’s skilleddocs/README.md:

# skilleddocs

Documents written by Claude Code skills (github.com/KrishP147/skills). Versioned so agents and people share one record.

- bridge.md — cross-session message log (session-bridge)
- briefs/ — teammate onboarding briefs (teammate-brief)
- decisions.md — append-only decision register; cite as D
- gaps/ — gap-scan reports (gap-scan)
- grills/ — grilling transcripts (asked, recommended, answered)
- handoffs/ — end-of-session handoffs; the newest is the next session's starting brief
- orchestrator/ — meta-orchestrator scope contract, ledger, handoff, manager reports
- pr-watch/ — per-pass PR watch logs (pr-watch)
- reports/ — progress reports and the watermark
- showcase/ — showcase inventory and findings (repo-showcase)
- spend.md, spend-approvals/ — billable-action approval log and one-shot approval tokens (spend-gate)

Plans and specs live in docs/; this folder records how they were decided and carried out.

Install

Pick one of the two. Both at once loads every skill and agent twice (once as /, once as /krish:) and runs the guard-git hook twice.

As a plugin (recommended)

In Claude Code:

/plugin marketplace add KrishP147/skills
/plugin install krish@krish

Skills are namespaced: /krish:pair, /krish:grill-docs, and so on. Agents are krish:manager, krish:implementer, krish:planner and krish:verifier; the skills that spawn them accept either form. The guard-git hook comes with the plugin as a plugin-level hook: it guards only the implementer and manager agents, so your own session can still push. The optional hooks in hooks/ are not part of the plugin; install those by hand. On Windows the hook needs Git Bash, as below; without it the hook blocks nothing. Update with /plugin marketplace update krish. Versions and changes: CHANGELOG.md.

With the install script

Plain names (/pair, manager) and files you can edit in place:

git clone https://github.com/KrishP147/skills.git
cd skills
./scripts/install-skills.sh        # bash/git-bash/mac/linux
# or
.\scripts\install-skills.ps1       # Windows PowerShell

This lints the repo, then copies every skill into ~/.claude/skills// and every agent into ~/.claude/agents/ (personal, global: works in every repo, every terminal, no need to clone this repo inside your project). Re-running it is safe: each skill installed by this repo is replaced fresh (it’s marked with a .from-krishp147-skills file dropped in its directory); agents are copied over the existing files, and any *.md in ~/.claude/agents/ that is no longer in this repo is flagged (“stale agent(s) not in repo, remove manually: …”), never deleted, since it may be your own. Likewise a skill dir under ~/.claude/skills/ that carries the marker but is no longer in this repo (renamed or removed) is flagged (“stale skill(s) not in repo, remove manually: …”), never deleted; the warning does not change the exit code.

Skill READMEs are written for GitHub: some of their relative links (e.g. ../../handoff-auto/) don’t resolve in the flat installed copy. That’s by design; the model reads only SKILL.md and its sibling files, and lint keeps those links working after the install.

The lint step needs a real Python 3 on PATH (python, python3, or — on Windows — py -3; a Windows Store Python stub is detected and skipped). No working Python 3 is found → the install fails with a clear message; pass --no-lint (sh) / -NoLint (ps1) to proceed anyway, with a warning, and skip the lint step.

Windows: Git Bash is required. The guard-git hook that stops agents from pushing to main or merging is a POSIX sh command. Without Git Bash, Claude Code can’t run it and the hook blocks nothing (it fails open). So the install checks first, before copying anything: install-skills.ps1 looks at CLAUDE_CODE_GIT_BASH_PATH, then sh/bash on PATH (not WSL’s System32\bash.exe), then bash.exe in the Git for Windows install; install-skills.sh runs command -v sh. Missing → clear error, non-zero exit. Install Git for Windows (or set CLAUDE_CODE_GIT_BASH_PATH to its bash.exe), or pass --no-sh-check (sh) / -NoShCheck (ps1) to install anyway, with a warning.

If a directory with the same name as one of this repo’s skills already exists under ~/.claude/skills/ but has no .from-krishp147-skills marker (i.e. you didn’t get it from here), the install leaves it untouched, warns, and exits non-zero at the end so you notice. Pass --force (sh) / -Force (ps1) to replace it anyway. Upgrading from an install made before the marker existed? Every old skill dir looks foreign, so run once with --force / -Force.

Install one workflow

To take only what one sample workflow uses instead of everything:

./scripts/install-skills.sh --list-workflows                 # names and titles
./scripts/install-skills.sh --workflow pair-to-pr            # repeat --workflow for more
.\scripts\install-skills.ps1 -ListWorkflows                  # Windows PowerShell
.\scripts\install-skills.ps1 -Workflow pair-to-pr,paid-tests

The workflows are the ones in site/data/workflows.json; every skill, agent and hook is in at least one. A workflow installs the skills, agents and hooks its steps name, plus what they need: skills an agent preloads, skills a selected skill calls or links into, and the guard-git hook whenever an agent is installed (scripts/workflow_deps.py works this out). Hooks from hooks/ are copied to ~/.claude/hooks/ (CLAUDE_HOOKS_DIR to change it) and their settings.json snippet is printed; they are never wired in for you. A different file already there is kept unless --force / -Force.

Nothing outside the selection is touched or warned about: no stale-skill or stale-agent warnings, no other directories changed. Lint, the Git Bash check and the marker / --force rules for the selected skills work as above. An unknown name prints the list, exits non-zero and installs nothing. Resolving a workflow needs Python 3, so --no-lint doesn’t help there: without Python the install stops with an error rather than falling back to installing everything.

Update

Plugin: /plugin marketplace update krish, then restart Claude Code. Install script:

cd skills
git pull
./scripts/install-skills.sh        # or .\scripts\install-skills.ps1

The install copies files rather than symlinking, so a git pull alone changes nothing in ~/.claude/ until you re-run the script. An agent removed from the repo stays installed until you delete it; the script’s stale-agent warning names it. Open a new Claude Code session afterwards; agents and skills are read at startup.

Prefer to install by hand, or just one skill? Copy the folder yourself:

cp -r repo-scrub ~/.claude/skills/repo-scrub
cp agents/planner.md ~/.claude/agents/

(.claude/skills// or .claude/agents/ inside a specific repo installs it project-only, for that repo alone.)

For repo-scrub, also install its CLI prerequisites:

# Windows
winget install --id Gitleaks.Gitleaks -e
pip install git-filter-repo
# mac / linux
brew install gitleaks git-filter-repo

For anything under kanban/:

gh auth refresh -s project -s read:project

Lint

python scripts/lint.py

Checks every SKILL.md and agent file (agents/README.md is docs, skipped by lint and install): frontmatter present, name matches the folder, description present and ≤1024 chars (YAML >/| block scalars are parsed, incl. a # comment after the indicator and more-indented folded lines; a description that is only the indicator fails), every skill an agent preloads exists and is model-invocable, every relative link in a skill’s prompt files resolves. The install scripts run this first and stop on failure. It also prints non-fatal WARN: lines (stderr) for a skill README missing a required section — see CONTRIBUTING.md.

It also checks every tracked file in the repo for forbidden words, so nothing project-specific or personal leaks in. No word list ships in the repo (it would defeat the point). Configure your own locally:

# untracked repo-root file, one word per line, # comments allowed
echo "acme-internal" > .lint-forbidden.txt
# or a comma-separated env var
SKILLS_LINT_FORBIDDEN=acme-internal,project-codename python scripts/lint.py

Neither set → the forbidden-word check is silently skipped.

Evals

python scripts/evals.py

Validates the trigger and behaviour suites under evals/ and prints the command to run them. It makes no model calls and runs no subprocess. Cases use the built-in claude plugin eval format: evals/-/prompt.md (frontmatter + the user prompt) plus graders/*.md.

• Coverage: every model-invocable skill (found the same way lint finds them, minus disable-model-invocation: true) needs 3-5 trigger cases and 2-3 near-miss cases. A near-miss is a sibling request (sitrep vs progress-report, grilling vs grill-docs, next vs divide) and asserts that skill did not fire.
• Behaviour: repo-scrub never rewrites history before the rotation gate, spend-gate never creates without a yes, pair never pushes without --push or a yes.
• Graders: free computed types only (regex, tool_used, tool_order, file_exists). llm and baseline call a judge model and fail validation.
• A missing suite, a wrong case count, or a malformed grader exits 1.

Running the suite is a real model call on your account, so it is never automatic. Run it by hand from the repo root (needs a plugin manifest at the root):

claude plugin eval . --runs 1 --ablation none --max-cost-usd 10 --no-publish

Behaviour graders check for Bash calls, and eval runs get no Bash unless you grant it (--allow-tools Bash, sandboxed; not on native Windows), so without the grant they only show the skill’s reply. Run output lands in evals/results/; don’t commit it.

Contributing / grow this repo

Contributions welcome — new skills, fixes, better docs. See CONTRIBUTING.md for the submission format (start from templates/skill/) and rules. Feel free to grow it.

Third-party skills

Relation to Matt Pocock’s skills

Several things here come from mattpocock/skills (MIT; notice in THIRD_PARTY_LICENSES.md). Checked against his repo with the GitHub API on 2026-10-15.

• Copied unmodified: grilling and grill-me. His skills/productivity/grill-me and skills/productivity/grilling are identical to ours (grilling synced 2026-10-15).
• Modified: handoff (his saves to the OS temp dir, not the workspace; ours saves under skilleddocs/handoffs/ and adds a commit-or-not sentence), handoff-auto (that, plus its own frontmatter so the model can call it, and a last line printing the path), wayfinder (his works any tracker and leaves research on research/* branches; ours is GitHub Issues only with sub-issues and native blocking, resolves grilling tickets with grill-docs, drops his domain-modeling type, sizes tickets to our ~75K-token smart zone, posts research as a comment, and ends by handing the map to divide), and dotfiles/CLAUDE.md (adapted from his personal global CLAUDE.md, not part of that repo; see My CLAUDE.md).
• Builds on his principles: how skills here are written follows his writing-for-agents skill and the video linked from CONTRIBUTING.md section 1.
• Divergences:
  • Our meta-orchestrator holds a merge gate and merges to the default branch itself once tests and CI are green (merge: auto; ask and pr-only are the alternatives). In his repo, implement-spec merges subagent work into an integration branch and opens a draft PR; I found no step that merges to the default branch.
  • Our verifier may answer grilling and consult-plan questions on your behalf, only when the run is set to interview: answer (otherwise it parks them for you), and lists every Q → A under “decided for you” (meta-orchestrator/SKILL.md, Interviews). His grilling always waits for the user’s answers.
• New here: everything else (grill-docs, pair, meta-orchestrator, the agents, kanban/, spend-gate, repo-scrub, and the rest).
• Kept in sync weekly: upstream.json lists each derived file with its upstream path, mode and the upstream commit last synced. The upstream-sync workflow runs scripts/upstream_sync.py every Monday (or on demand): a verbatim copy that changed upstream gets a PR from upstream-sync/verbatim; a modified one gets an issue upstream-sync: with the upstream diff since the recorded commit, and after porting it you run python scripts/upstream_sync.py --mark-synced (to skip the change, run only that). Only open PRs and issues count as already filed: closing the issue without --mark-synced, or closing the PR unmerged, gets a fresh one on the next run (the branch is force-pushed). If Actions may not open PRs (the repo default), the run opens an issue upstream-sync: verbatim copies linking the pushed branch instead, and you open the PR by hand. Each PR/issue step runs even if another fails; the job fails if any did. dotfiles/CLAUDE.md is not tracked, since its source is not in that repo. Run python scripts/upstream_sync.py --dry-run to check by hand.

npx skills add mattpocock/skills pulls his full set directly.

Relation to DietrichGebert’s ponytail

ponytail is copied verbatim from DietrichGebert/ponytail (MIT; notice in THIRD_PARTY_LICENSES.md), file skills/ponytail/SKILL.md at v5.2.0. Only that core skill is included, not its sibling skills, hooks or statusline. Its README.md here is original. It is tracked in upstream.json and synced weekly like the Pocock copies above.

My CLAUDE.md

dotfiles/CLAUDE.md is my global Claude Code config, adapted from Matt Pocock’s (commit-message style, GitHub CLI first, how I want plans formatted). The branch prefix is left as a `` placeholder in the tracked file. Install it with:

./scripts/setup-claude-md.sh merge     # append to your existing ~/.claude/CLAUDE.md
./scripts/setup-claude-md.sh replace   # overwrite/create ~/.claude/CLAUDE.md from scratch
# or, on Windows:
.\scripts\setup-claude-md.ps1 -Mode merge
.\scripts\setup-claude-md.ps1 -Mode replace

merge just appends with a timestamped separator; it won’t dedupe against your existing file, so skim the result afterward.

Pass --prefix (sh) / -Prefix (ps1) to fill in the branch-prefix placeholder as it’s written — e.g. the author’s own value: ./scripts/setup-claude-md.sh merge --prefix krish or .\scripts\setup-claude-md.ps1 -Mode merge -Prefix krish. Without it, `` is left in place and the script prints a hint.

Author

Krish Punjabi. Public, MIT; use whatever’s useful.

License

MIT (see LICENSE) for everything original in this repo. Matt Pocock’s skills and DietrichGebert’s ponytail carry their own MIT notices; see THIRD_PARTY_LICENSES.md.