Skip to content
amagdy46Public

About

Agent skills that ask once, then get out of your way.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

amagdy-skills

Agent skills that ask once, then get out of your way.

validate Startup cost: about 669 tokens

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.

One task, with and without

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 skillWith brainstorm

Fun one. Here's a first pass to react to.

The core loop […]
Ideas worth considering […]
The big decision: what form should it take? […]

My recommendation: if this is a personal tool, a PWA with local storage is the best balance. […]

Questions for you

  1. Roughly how many plants? 5 and 50 lead to different designs.
  2. Just you, or shared with others?
  3. Is this mainly about getting the tool, or also a project you want to enjoy building (e.g. trying out a framework)?
  4. Where do you want reminders to show up: phone notifications, calendar, chat, or email?

[…]

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.

Install

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.

What the evals show

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:

  • brainstorm asks 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.

The flow for a new project

brainstorm (writes design.md), then writing-plans (writes plan.md), then to-issues (GitHub, Linear or Markdown), then implement. brainstorm draws on research, and converges with grilling. implement ends in impact-review.

  1. brainstorm asks what you want, one question at a time, researches in the background, and writes design.md once you approve.
  2. writing-plans turns the design into plan.md: small tasks with exact files, interfaces and checks.
  3. 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.
  4. 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".

Quick start

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

Skills

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.

Why these skills

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.md of 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.

Where the files go

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), markdown

Fork it and make it yours

To 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.mjs

It 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.

For agents and contributors

Credits and license

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.

About

Agent skills that ask once, then get out of your way.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages