Ervis Zyka's Skills

Agent skills I use day to day - engineering, productivity and research.

Runtime-neutral: plain SKILL.md files with no harness-specific tool names, so they work on Claude Code, Codex, and anything else that speaks Agent Skills. The exceptions are the qrspi/ and qrspi-lite/ buckets: those skills require specific subagents and skills, and stop if one is missing (see QRSPI).

Skills

Engineering

| Skill | What it does | |---|---| | commit | Groups the session's changes into focused commits with clear messages, shows the plan, and commits only after you approve. Adds no agent attribution. | | git-worktree | Opens a git worktree for a branch, at ~/wt/<repo>/<branch> unless you give a location, and runs the project setup there. Reuses the worktree if the branch has one. Removes it only when you ask. | | ticket-grooming | Challenges a ticket until a coding agent could build it with zero open questions. Verifies the ticket's claims against the real code, then writes ranked blocking questions plus a rewritten dev-ready ticket. |

Productivity

| Skill | What it does | |---|---| | brainstorm | Runs a structured brainstorm with a framework picked to fit: starbursting, QFT, question burst, pre-mortem, assumption mapping, 5 whys or six thinking hats. For scoping research it chains starbursting, pre-mortem and assumption mapping, then QFT. Saves the result to the vault under brainstorm/. | | caveman | Ultra-terse reply mode that cuts about 75% of tokens by dropping filler while keeping full technical accuracy. Stays on until you say "stop caveman" or "normal mode". | | daily-report | Reports what you worked on today as one table: your Claude Code and Codex sessions grouped by project, notes created or edited in the vault, and your GitHub PRs and issues, with links. Sources it cannot read are listed as skipped. Read-only, and the same format in any session. | | simple-english | Writes responses in ASD-STE100 Simplified Technical English: short sentences, active voice, one idea per sentence, simple words. |

Research

Nothing here yet.

QRSPI

The QRSPI workflow: nine skills, run one after the other on a task directory that holds all the files of one task.

task.md -> qrspi-question -> qrspi-research -> qrspi-research-resolve
        -> qrspi-design -> qrspi-structure -> qrspi-plan -> qrspi-test-plan
        -> qrspi-implement -> qrspi-pr

The flow only moves forward. Each skill takes the task directory as its first argument, for example qrspi-question ~/wiki/rate-limit, and names the next skill when it is done. You write task.md; the skills write the rest.

| Skill | What it does | |---|---| | qrspi-question | Turns task.md into neutral research questions with the clean room method: it knows the goal, the researcher must not. Finds the affected areas and blind spots (same-shape features, producers and consumers, cascades), asks a fixed set of facets per area, and leak-tests the result. The number of questions comes from coverage, not a quota. | | qrspi-research | Answers questions.md blind, with facts only: every finding cites file:line or a URL. Writes research-draft.md. You can add a missing question before it hands off. | | qrspi-research-resolve | Grades each answer. Only when an answer is weak, contradictory or open does it interview you; you answer or skip each gap. Writes the final research.md. Research is done after this step. | | qrspi-design | Interviews you on the design decisions with the research as evidence, and writes design.md. Prefers patterns the code already uses and marks each decision as existing (with the file:line that already does it) or new (with the reason). Groups the current state into invariants, assumptions, cascades, dependents and lifecycle. | | qrspi-structure | Breaks the design into vertical slices, each with its files, key signatures and a check, plus the invariants and dependents it touches. Writes structure.md. | | qrspi-plan | Expands each slice into exact changes, code snippets where they are not obvious, and checks with checkboxes. Writes plan.md, which an agent can work from alone. | | qrspi-test-plan | Writes the black-box test cases, in plain words, that guard the scope and the design: one goal case per slice, and exhaustive Given / When / Then cases at each public interface (anything a client depends on, behavior and data). Reads the design and the slices, not plan.md, so the tests check the code independently. Lists the expected contract changes, so implement can tell an expected failure from a bug. Writes test-plan.md; implement writes the tests from it. | | qrspi-implement | Works through plan.md one slice at a time, and writes the code and the tests for the test cases of test-plan.md: a slice is done when its checks and its tests pass. Ticks checkboxes, makes one commit per slice, and changes an existing test only for a listed contract change. Asks you only for the checks by hand. Works in a git worktree, and writes its path to plan.md, so a new session finds it. | | qrspi-pr | Pushes the branch of the worktree and opens a pull request, or updates the one that exists. The task directory is not in the repository, so the description in pr.md carries the rules with the tests that prove them, a code walkthrough with the invariants and assumptions at each stop, the rollout and the checks. It checks each permalink before the push. |

These skills require:

• simple-english and git-worktree from this package.
• The GitHub CLI (gh), for qrspi-pr.
• The subagents codebase-locator, codebase-analyzer, codebase-pattern-finder and web-search-researcher from agents/. They are Claude Code only. The npm install puts them in ~/.claude/agents (see Install).
• grilling from Matt Pocock's skills, for the interviews in qrspi-research-resolve and qrspi-design.

QRSPI lite

A copy of the QRSPI workflow that uses fewer tokens. It has the same steps, questions, facets, approvals and files. It changes only how the work is done:

task.md -> qrspi-lite-question -> qrspi-lite-research -> qrspi-lite-research-resolve
        -> qrspi-lite-design -> qrspi-lite-structure -> qrspi-lite-plan
        -> qrspi-lite-test-plan -> qrspi-lite-implement -> qrspi-lite-pr

• Research sends each area to one qrspi-researcher agent, with all the questions of the area. The agent writes its answers to research/<area>.md. The main session does not read the code or merge the answers.
• The leak test checks each area alone, because each researcher sees one area.
• qrspi-lite-research-resolve writes only the grades and your answers, to research-resolved.md. It does not copy the facts.
• The current state of design.md is the one copy of the facts. Structure, plan and test plan read design.md, not the research files.
• Each step runs in a new session. The hand-off line names the Claude model for the next step. The design interview writes each decision at once, so a long interview can continue in a new session.
• Search and guess agents run on Haiku, research on Sonnet, and each step that needs judgment on Opus.

It needs the same skills and subagents as the QRSPI skills, plus the qrspi-researcher subagent from agents/. The npm package does not ship qrspi-researcher yet: install it with ./scripts/link-skills.sh (see Local dev).

Install

For a new laptop. One command, no clone, no npm account.

Prerequisites

• Node.js 18 or newer and npm (node --version, npm --version). Any current Node install includes npx.
• No npm account or login: the package is public.

Install the skills

npx @ervis/skills@latest

@latest makes npx fetch the newest release instead of reusing an old cached one. The installer copies every skill into two places, and the subagents the QRSPI skills need into a third:

| Directory | What | Read by | |---|---|---| | ~/.claude/skills | Skills | Claude Code | | ~/.agents/skills | Skills | Codex and other Agent Skills harnesses | | ~/.claude/agents | Subagents codebase-locator, codebase-analyzer, codebase-pattern-finder, web-search-researcher | Claude Code |

Each skill lands as a plain directory named after the skill, for example ~/.claude/skills/ticket-grooming, with a .ervis-skills marker file inside. Each subagent lands as one file, for example ~/.claude/agents/codebase-locator.md, with the marker as a comment line in its frontmatter: # Managed by @ervis/skills; re-run the installer to update. The marker is how a later run knows the copy is its own.

To see what it would do first, without touching anything:

npx @ervis/skills@latest --dry-run

Complementary skills

Matt Pocock's skills cover engineering workflows this package does not - TDD, diagnosing bugs, resolving merge conflicts, domain modelling - and are worth installing alongside this package rather than instead of it:

npx skills@latest add mattpocock/skills

The installer lets you pick which skills to take and which agents to install them on. This writes them into your repo as plain files, the same way @ervis/skills does, so both sets stay editable and neither manages the other.

Flags

| Flag | Effect | |---|---| | --dry-run | Print what would be installed or updated, change nothing. | | --target <dir> | Install skills into <dir> instead of the two defaults. Repeatable. Installs no subagents unless --agents-target is also given, so a trial run into a scratch directory never touches ~/.claude. | | --agents-target <dir> | Install subagents into <dir> instead of ~/.claude/agents. Repeatable. | | --force | Also replace a skill or subagent that was not installed by this tool. | | -h, --help | Show usage. |

Overwrite behavior is deliberately conservative:

• A skill or subagent this tool installed earlier (it has the marker) is replaced in place. The new copy is built next to the old one and swapped in, so a failed update leaves the old one intact.
• A skill directory, subagent file or symlink that already exists without the marker - your own of the same name, or a link from the local dev path below - is skipped, with a message. Pass --force to replace it.
• Other skills and subagents in the target directories are never touched.

Verify it worked

ls ~/.claude/skills ~/.agents/skills ~/.claude/agents
find ~/.claude/skills ~/.agents/skills -maxdepth 2 -name .ervis-skills
grep -lx '# Managed by @ervis/skills; re-run the installer to update.' ~/.claude/agents/*.md

The first lists the installed skills and subagents, the second lists the marker of every skill managed by this tool, and the third every managed subagent. Then start a new agent session: skills and subagents are read at session start, so an already-running session will not see them. In Claude Code, /agents lists the subagents it loaded.

Update

Run the same command again:

npx @ervis/skills@latest

Managed copies are reported as updated. Nothing updates in the background.

Uninstall

There is no uninstall flag. Remove the managed copies, which are exactly the skill directories that contain the marker and the subagent files that carry it:

find ~/.claude/skills ~/.agents/skills -maxdepth 2 -name .ervis-skills -exec dirname {} \; | while read -r d; do rm -r "$d"; done
grep -lx '# Managed by @ervis/skills; re-run the installer to update.' ~/.claude/agents/*.md | while read -r f; do rm "$f"; done

Run them without rm (use echo) first if you want to review the list. Skills and subagents you installed some other way have no marker and are left alone.

Troubleshooting

• A skill or subagent says skipped ... not installed by ervis-skills. A directory, file or symlink with that name already exists and was not put there by this tool. Move it away, or re-run with --force to replace it.
• Permission denied. The target directory is not writable by your user. Check ownership with ls -ld ~/.claude/skills ~/.agents/skills ~/.claude/agents, fix it, or install somewhere you own with --target and --agents-target. Do not use sudo: it would leave root-owned files in your home directory.
• You keep getting an old version. npx caches packages. Always use @latest; if it still looks stale, clear the cache with npm cache clean --force and run again.
• Errors mentioning node:fs, cpSync or a syntax error. Your Node is too old. Upgrade to 18 or newer (node --version to check).
• Duplicate skill name error. Two skills in the package share a directory name. That is a packaging bug; report it rather than working around it.
• 404 or E404 for @ervis/skills. The package has not been published yet, or the name is mistyped.

Local dev

For working on this repo itself. Symlinks instead of copies, so git pull is all it takes to stay current:

./scripts/link-skills.sh

It links every skill into ~/.claude/skills and ~/.agents/skills, and every subagent (agents/<name>/AGENT.md) into ~/.claude/agents/<name>.md. Agents are Claude Code only, and the npm package ships only the four the QRSPI skills need. Do not combine it with the npm install for the same skills or subagents: the installer skips the links unless you pass --force, and --force replaces them with copies. To go back, delete the links (rm ~/.claude/skills/<skill-name>, rm ~/.claude/agents/<name>.md).

Layout

skills/<bucket>/<skill-name>/SKILL.md

Buckets are engineering/, productivity/, research/, qrspi/ and qrspi-lite/ - see skills/README.md for what belongs where. They are for humans reading the repo and appear nowhere in how a skill is addressed: the skill name comes from its own directory.

Subagents live beside skills/ at agents/<name>/AGENT.md.

Working on the skills

./scripts/list-skills.sh    # every SKILL.md in the repo
./scripts/check-skills.sh   # frontmatter and name/dir match
./scripts/link-skills.sh    # install locally as symlinks
./scripts/setup-skills.sh    # install Matt's and these skills with npm

setup-skills.sh installs Matt Pocock's published skills (with npx skills add mattpocock/skills) and the skills of this checkout (with bin/install.js, the @ervis/skills installer). --agent= picks where: claude (the default) installs into ~/.claude/skills and the subagents into ~/.claude/agents, codex (or chatgpt) into ~/.agents/skills, and --agent=claude,codex does both. For claude it first uninstalls the mattpocock-skills Claude Code plugin, so the same skills do not load twice. Matt's skills that are already there are left alone. The @ervis/skills installer updates its own earlier copies and skips anything else. --force installs everything again over what is there.

Run check-skills.sh before pushing. It catches the failures that are silent and annoying to debug later: a skill or published subagent whose frontmatter name drifted from its directory, or one with missing frontmatter. Claude Code ignores a subagent file without a name, so a missing one installs an agent nobody can call.

Adding a skill to the package

1. Create skills/<bucket>/<name>/SKILL.md (the name must match the directory, and be unique across buckets).
2. ./scripts/check-skills.sh
3. npm pack --dry-run and confirm the new SKILL.md is in the list. There is no manifest to edit: the package ships everything under skills/ except deprecated/, in-progress/ and draft/.
4. Add a row to the skills table above, then release (see Publish).

Publish

For the maintainer. The package is @ervis/skills, public, published to npmjs.com. Agents and CI never run npm login or npm publish.

Publishing is public and hard to undo. Every shipped skill becomes world-readable on the npm registry, even while the GitHub repo is private. npm restricts unpublishing (as a rule only a recent release with no dependents can be removed) and a published version number can never be reused. Treat every publish as permanent: inspect the tarball first.

One-time setup

1. Create or confirm the npm account ervis at npmjs.com and verify its email.

2. Turn on two-factor authentication in the account settings on npmjs.com. Use the "authorization and writes" level so publishing asks for a code.

3. Log in from your terminal and confirm who you are:

   npm login
   npm whoami    # should print: ervis

4. The scope @ervis is your username, so it is yours automatically. Access is already public via publishConfig in package.json; scoped packages default to private without it, and the first publish would otherwise fail.

Release a version

1. Merge the PRs for the release, then get on a clean master that matches origin/master.

2. Bump the version. npm refuses to republish a version, so every release needs a new one:

   ./scripts/bump-version.sh           # patch; or --minor / --major / --set <version>

   It runs only on a clean master that matches origin/master: PRs are squash-merged, so a tag on a feature branch would point at a commit that never lands on master. It commits package.json as Bump version to <version>, tags that commit v<version> and pushes master and the tag together. CHANGELOG.md is generated, so do not edit it by hand: the commit messages and PR title are the release note.

3. Inspect what will ship:

   npm pack --dry-run                         # file list and sizes
   npm pack && tar tzf ervis-skills-*.tgz     # the actual tarball contents

   It should hold only bin/, skills/ (no deprecated/, in-progress/ or draft/), the four published subagents under agents/, package.json, README.md and LICENSE. Delete the .tgz afterwards.

4. Try the tarball the way a new laptop would, in a throwaway home:

   HOME=$(mktemp -d) npx ./ervis-skills-<version>.tgz

5. Run the release script:

   ./scripts/release.sh --dry-run   # stops after the checks and pack
   ./scripts/release.sh             # same, then asks y/N before publishing

   It runs, in order: ./scripts/check-skills.sh, npm pack --dry-run, a Publish @ervis/skills@<version>? [y/N] prompt, then npm publish. Anything but y aborts.

Verify after publishing

npm view @ervis/skills version
HOME=$(mktemp -d) npx @ervis/skills@latest

The first should print the version you just released; the second installs into an empty home, exactly like a new laptop. Registry caches can lag by a minute or two, so retry before assuming it failed.

Publish a fix

A published version is frozen. Fix the problem on a branch, merge it, bump the version again on master (./scripts/bump-version.sh), and run the release script. If a release is actively harmful, npm deprecate @ervis/skills@<version> "<reason>" warns everyone who installs it without removing it.

Licence

MIT