Agent skills that ask once, then get out of your way.
A skill is a short instruction file that a coding agent (an AI that writes and runs code for you, such as Claude Code or Codex) loads when a task needs it. These skills cover a project from first idea to reviewed change. They tell the agent to ask you only what it cannot find out itself, then do the work and say what it decided.
Asked to brainstorm a small app, Claude Opus with no skills wrote a design.
With the brainstorm skill it asked one question.
| You: let's brainstorm a little app for keeping track of when to water my houseplants | |
| Without the skill | With brainstorm |
|---|---|
|
Fun one. Here's a first pass to react to. The core loop […] My recommendation: if this is a personal tool, a PWA with local storage is the best balance. […] Questions for you
[…] |
Fun one. If you'd rather skip the questions, just say so and I'll take a concrete guess and run with it. To start: think of the last time a plant suffered because you got the watering wrong. What happened? |
One run of three from the eval case
brainstorm-opening, Claude Code 2.1.327,
2026-11-18. Cuts are marked […]; nothing is reworded. Full replies:
without,
with.
Paste this to your agent:
Install https://github.com/amagdy46/skills by following its INSTALL.md
Or run it yourself:
# Claude Code
claude plugin install amagdy-skills --marketplace amagdy46/skills
# Codex
codex plugin marketplace add amagdy46/skills
codex plugin add amagdy-skills@amagdy-skills
# Cursor, OpenCode, Pi and others
npx -y skills add amagdy46/skills -g -y --agent <agent>For <agent>, put cursor, opencode, pi or your agent's name. Install
the whole set, because the skills hand off to each other by name. Do not
install it next to Superpowers, Matt Pocock's skills or pstack, or twice by
two paths; two copies of the same job give the agent conflicting
instructions. Updates, removal and checks are in INSTALL.md.
| Skill | With the skill | Without |
|---|---|---|
| brainstorm | 100% | 33% |
| grilling | 33% | 0% |
| implement | 100% | 56% |
| working-style | 96% | 89% |
| systematic-debugging | 67% | 50% |
Share of runs in which every check passed (on sonnet, runs up to 2026-11-19, 3 runs per case and arm). With so few runs, read a difference under 20 points as noise.
Five skills were tested on 19 cases, each run with the skill and with no skills at all. Three showed a clear effect:
brainstormasks one question where a stock agent writes a design.systematic-debugging: on a bug with a copy in another file, every run fixed the bug it was shown; only with the skill did the agent fix the copy too.implement: on a six-task plan, every run finished the work; only with the skill did the agent keep the plan ticked off as it went.
grilling asks three questions where a stock agent asks about ten, though
it passes every check in only one run in three. working-style showed no
clear difference, and on most short cases neither did anything else:
current models pass them with no skill. All rows, including the ones with
no difference, are in evals/RESULTS.md.
- brainstorm asks what you want, one question at a time, researches in
the background, and writes
design.mdonce you approve. - writing-plans turns the design into
plan.md: small tasks with exact files, interfaces and checks. - to-issues splits the work into tickets that can each be tested alone, links which blocks which, and publishes them to GitHub, Linear or Markdown.
- implement works the ready tickets test-first, verifies and reviews each, and pushes only when you ask.
You can start at any step. If you already know what you want, say "write a plan" or "break this into issues".
You rarely name a skill. Describe the task and the agent picks the one that fits.
let's brainstorm a CLI that syncs my Kindle highlights into Obsidian
plan it and put the work in GitHub issues
work the issues
Other things to say:
debug this: the export hangs on files over 2 GB
grill me on this migration plan
review this branch: what could it break?
is this PR ready? push it and watch CI
| Stage | Skill | For you | Startup bytes | Evals: with / without |
|---|---|---|---|---|
| Think | brainstorm | find out what you actually want, with research, before any code exists | 179 | 100% / 33% |
| grilling | stress-test a plan in rounds of questions, each with a recommended answer | 171 | 33% / 0% | |
| research | answer a question from primary sources, cited and dated | 183 | - | |
| Plan | writing-plans | turn a design into small tasks with exact files, interfaces and tests | 170 | - |
| to-issues | break work into tickets in GitHub, Linear or Markdown, each naming what blocks it | 179 | - | |
| Build | implement | execute a plan or tickets to the end, yourself or with subagents | 171 | 100% / 56% |
| working-style | let the agent decide and do reversible work, and ask you only before steps it cannot undo | 290 | 96% / 89% | |
| orchestrate | coordinate many implementer and reviewer agents under your standing orders | 169 | - | |
| systematic-debugging | reproduce, isolate and fix the root cause | 205 | 67% / 50% | |
| Check | create-verification-skill | write a project's verify skill so agents can prove changes in the real app | 207 | - |
| impact-review | review a change and trace what it could break beyond its own diff | 206 | - | |
| ci-pr-lifecycle | drive a PR through CI to a finished state; it never merges unasked | 170 | - | |
| Improve | reflect | turn a session's lessons into edits to skills, AGENTS.md or enforcement |
205 | - |
| Write | unslop | strip AI tells from prose | 170 | - |
Evals: the share of eval runs in which every check passed, with the skill alone loaded / with no skills loaded (on sonnet, runs up to 2026-11-19, 3 runs per case and arm); - means the skill has no cases. With so few runs, read a gap under 20 points as noise. The cases, and the ones too easy to show a difference, are in evals/RESULTS.md.
At session start an agent loads only each skill's name and description: 14 skills, 2,675 bytes, about 669 tokens.
Each skill names the failure it targets and where that failure is recorded, in FAILURES.md. Ten of the fourteen have a record; the rest say "inherited" and claim nothing more. Three with a record:
- implement: upstream, Claude Code cut a long skill
file when it compacted the session, the limit on fix rounds was lost, and
one task ran 18 rounds. Here the loop stops at three rounds, and the
validator fails any
SKILL.mdof 20,000 bytes or more. - writing-plans: upstream, a 1,894-line spec became a 19,393-line plan after more than five hours, and no program was written. This skill's plans record only decisions.
- systematic-debugging: measured here. Asked to fix one bug, a stock agent fixed it and left the copy of the same mistake in another file, in 3 of 3 runs. With the skill it fixed both.
One piece of work keeps design.md, plan.md and issues/ in one planning
folder, by default docs/plans/YYYY-MM-DD-<slug>/. The files use
frontmatter and [[wikilinks]], so an Obsidian vault shows them as linked
notes. To change the folder or the tracker, add these lines to the
project's AGENTS.md:
Planning folder: ~/notes/projects/<project>
Issue tracker: github # or: linear (team: X), markdownTo edit the skills and have every agent on your machine use your copy, fork
the repo and run scripts/link.mjs from your clone:
git clone git@github.com:<you>/skills.git
node skills/scripts/link.mjs --dry-run # see what it will do
node skills/scripts/link.mjsIt links every skill into ~/.agents/skills and into each installed agent's
skills folder, so git pull or a local edit reaches every agent at once. It
also links global/ over ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and
~/AGENTS.md; those hold the author's personal rules, so edit global/
first. It deletes nothing it did not create: anything in the way is moved to
~/.agents/agent-config/backups/, and every link it makes is recorded in
~/.agents/agent-config/links.json. A later run removes only recorded links
that are no longer needed, such as a deleted skill's. Rerun it after you add,
remove or rename a skill, or move the clone.
- Installing: INSTALL.md. Every skill with its description and startup cost: skills.json and llms.txt.
- Changing a skill in this repo: AGENTS.md.
- The bar for new text, for people and agents: CONTRIBUTING.md. A new line must fix a failure someone saw.
MIT. The skills started from Jesse Vincent's Superpowers, Matt Pocock's skills and poteto's pstack; the parts that fixed real problems were kept, overlaps merged, the rest cut. Credits and pinned upstream versions are in THIRD_PARTY_NOTICES.md.