⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.0

eval-skills

dzhng@dzhng⭐ 1.5k stars· last commit 4d ago· 0 open issues

Eval and improve a skill against golden cases — run the target skill blind in a fresh, context-free subagent on each example input, grade the artifact against the expected outcome, and let the gaps drive the edits. Use when the user wants to test/eval/improve/harden a skill, says "this skill keeps producing X / keeps missing Y", or hands a skill plus example input→expected-output pairs. Pairs with [write-skills](../write-skills/SKILL.md) (the authoring principles every fix obeys).

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.5k on GitHubGitHub ↗

Very popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Skills

skills.sh

AI skills for building software factories

AI skills for building software factories. My personal library of domain-agnostic agent skills, reused across every project. Small, composable, and hackable — works with any harness that supports skills: Claude Code, Codex, opencode, Cursor, duet, and 70+ others.

npx skills add dzhng/skills

Add --list to pick individual skills, or copy any skills/<category>/<name>/ folder into your harness's skills directory (e.g. .claude/skills/).

From a clone, npm run install-skills does the same without the registry:

npm run install-skills              # into ~/.agents/skills, linked from ~/.claude/skills
npm run install-skills -- ../my-app # into a repo instead of the home directory
npm run install-skills -- --only write-spec,review ../my-app
npm run list-skills                 # names and categories

.agents/skills/<name>/ holds the real files (flat, category-free, with cross-category links rewritten to match); .claude/skills/<name> is a relative symlink into it, so both harnesses read one copy. Re-running overwrites the installed copies — a .claude/skills/<name> you keep as a real directory is left alone, and a .claude/skills that is already a symlink is left as is. Add --dry-run to see the plan first.

Why

Software is moving from tasks to factories: agents that pursue a goal autonomously until the output can be trusted. The hard part isn't breaking the goal into tasks — it's breaking it into independently verifiable pieces, and knowing where the pieces even are.

These skills run that loop. Treat the unknown as fog of war: map the terrain, carve it into territories that build and verify in isolation, and recursively re-slice whatever hides more map. And re-planning doesn't stop when planning ends — the spec is a living document, updated and re-sliced mid-implementation whenever the work teaches the agent that the plan is stale. Every piece must prove itself — architecture review, code review, and visual review against a baseline — before the loop moves on. Each iteration gets less wrong, until the goal is done.

A single autonomous run — 3 days, 18 minutes pursuing one goal

Proof: one unattended Codex run pursuing a single goal for 3d 18m on top of these skills, slicing and iterating until done.

How to use

Use a chained pipeline to build a feature, a research loop to discover what works, or individual skills as needed. Every skill stands alone.

The full loop — a big feature, start to finish

The full loop — explore, spec, build unattended, review the decisions

  1. Map the fog. /explore-unknowns on the idea. It interviews you quadrant by quadrant and hands you rendered options, mocks, and decision tables to react to instead of asking you to imagine. By the end you know what the feature does.

  2. Codify. /write-spec on that map. Most decisions were already made upstream, so this pass is transcription — I don't read the spec. Anything genuinely new it hits, it asks about instead of deciding.

  3. Build. Kick off the loop:

    /goal /implement-spec specs/<feature>
    

    /goal is what puts the harness in loop mode — same move in Claude Code or Codex — and the spec drives it from there. A couple of hours for a small feature, two or three days for a large one. Add whatever framing fits: on the xyz branch, or using /codex as the implementer while you stay the parent orchestrator and reviewer.

  4. Review the decisions, not the diff. The run ends by consolidating specs/<feature>/decisions.md — every decision the agent made where the spec was silent, ranked least-confident first. That's the review surface. Send changes back and the next pass re-audits: every time the AI writes code, you audit what it decided.

    The rest fires on its own: a /review pass at the end of every slice, /screenshot-critique and /compare-screenshots on anything visual, /close-spec when the last slice lands, and a re-slice of the plan whenever implementation proves it stale.

Budget: 30 minutes to a few hours on steps 1–2, 30 minutes to a few hours on step 4. A run that goes two days is more like 2–3 hours on each end. Your time is in the bookends; the middle is unattended.

Research — learn through fast experiments

Use Auto Research when the next decision needs experimental evidence. It starts with one fast, revealing task, tests a short batch of hypotheses, checks combinations, and expands coverage as the approach improves. New failures become the focus; earlier tasks become regression checks.

/auto-research Reduce cost per task by at least 15% relative to the saved
baseline, without reducing task success. Start with one fast development task.

If the evaluator, metric, baseline, or required improvement is unclear, the skill asks before experimenting. Passing an evaluation and meeting an improvement target are separate requirements. The output includes the best verified artifact and a parameter-effect map: what was tested, where it helps or hurts, and how changes interact. Use that evidence to inform a spec when the research is ready for implementation.

À la carte — the spontaneous path

  • A brainstorm turns out to be a feature. /explore-unknowns works at the end of a discussion as well as at the start — run it to sweep for the angles neither of you thought of, then pick the loop up at step 2.

  • Any code change that didn't come from a spec. An ad hoc fix that touched more than expected: /review first (refactor-change → code-review → write-docs), then /audit-decisions. When the diff is too big to read, the decisions ledger is how you still understand what is now in your codebase.

Skills

Plan — map the fog, then slice it

SkillWhat it does
explore-unknownsWalk the user through mapping a task's unknowns quadrant by quadrant — known knowns first, then interviews, reactable artifacts, and blindspot passes — ending with a complete four-quadrant map.
auto-researchOptimize through fast, progressive experiments, producing a verified candidate and a map of parameter effects and tradeoffs.
write-specBreak a large feature into independently verifiable, human-reviewable slices with API seams and playable checkpoints.

Implement — build every slice to completion

SkillWhat it does
implement-specBuild an existing spec to completion, one reviewable pass at a time, delegating independent slices in parallel.
implement-spec-with-goalUse the harness's goal feature, then follow implement-spec to completion.
implement-spec-with-codexRun implement-spec with Codex writing the code — you orchestrate, integrate, and review every pass.
handoff-specHand a spec that is mid-implementation to another machine or agent: capture what the session knows in the spec, then push. User-invoked.
close-specArchive a shipped spec and rewrite it from a build plan into a durable rationale record that points back at the code.
port-featuresPort a feature by copying its exact upstream code and editing the copy instead of rewriting it, with git history explaining each odd line before it changes.
[write-tests](skills/i

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/authoring/eval-skills/SKILL.md7.5 KBupstream ↗
    ---
    name: eval-skills
    description: Eval and improve a skill against golden cases — run the target skill blind in a fresh, context-free subagent on each example input, grade the artifact against the expected outcome, and let the gaps drive the edits. Use when the user wants to test/eval/improve/harden a skill, says "this skill keeps producing X / keeps missing Y", or hands a skill plus example input→expected-output pairs. Pairs with [write-skills](../write-skills/SKILL.md) (the authoring principles every fix obeys).
    ---
    
    # Eval Skills
    
    Treat a skill like a function under test. Feed it example inputs in a clean
    room, check the artifacts against what good looks like, and let the failures
    drive the edits. The eval is only honest if the run is **blind**: the agent
    executing the skill must carry none of this conversation's context and must
    never see the expected output. Leak either and you are teaching to the test.
    
    ## Inputs you need — refuse without them
    
    Confirm all three before spawning anything. If any is missing or
    unresolvable, stop and tell the user *exactly which one* and what a good
    version looks like. Do not invent cases, guess intent, or eval against a
    fuzzy wish.
    
    - **Target skill** — must resolve to a real `SKILL.md`. If you can't find it,
      list the skills you can see and ask which one they mean.
    - **At least one golden case** — a concrete input the skill will actually
      receive: a screenshot, a prompt, a file, a scene. "Improve write-spec"
      with no input attached is not a case.
    - **The bar per case** — the outcome a good artifact achieves and the smells
      that would make it bad, *not* an exhaustive parts list. The skill's
      **judgment** is what's under test, so do not pre-enumerate every
      requirement — that turns the eval into a conformance check and stops testing
      whether the skill decides well. "Sliced so each piece is independently
      buildable and verifiable, at the granularity a competent practitioner would
      pick — a lazy mega-slice and pointless over-splitting are both failures" is
      a bar a judge can hold the work to; "slices it well" is too thin to grade
      and a fixed list of expected slices is too prescriptive. State the bar and
      the smells; let the judge apply them. The exception is a **conformance-style**
      skill that genuinely wants an exact task hit exactly — then the explicit
      criteria *are* the bar; match the bar's shape to the skill's nature, and if
      you can't tell which it is, ask. If the user gives only a fuzzy wish with no
      bar, draw the bar out of them and echo it back before spending agents.
    
    ## Workflow
    
    1. **Validate inputs and surface first principles.** Resolve the skill and
       read its **first principles** — what it's for and the standard it holds
       itself to; this is what the judge grades against, so if the skill doesn't
       make them clear, clarify with the user rather than inventing them. Settle
       the eval mode here too: judgment (a bar the judge applies) vs conformance
       (an exact task hit exactly) — ask the user if it's ambiguous. Then sharpen
       each case's bar — the outcome plus the smells, kept at the altitude the
       user cares about, never widened into a prescribed parts list unless the
       skill is conformance-style. Done when you can state the skill's first
       principles in a sentence and every case has a concrete input and a bar a
       competent judge could hold an artifact to.
    
    2. **Blind run, one fresh agent per case.** Isolate every run so a misbehaving
       skill can't touch the live checkout and each case starts clean. Prefer
       capturing the artifact from the runner's final message — if the skill's
       output is a plan or text, ask for it inline and nothing hits disk to leak.
       When the skill must write files, give the runner a throwaway sandbox dir as
       its only writable root, not a worktree of the live repo (worktree isolation
       guards git state, not absolute-path or escaped writes). After every run,
       sweep the live checkout (`git status`) and clean anything the run leaked —
       isolation is best-effort, the sweep is the guarantee. Give the runner
       **only** the input and the instruction to use the target skill — never the
       bar, the smells, the other cases, or why you're asking. Done when you hold
       one artifact per case, each from a context-free run, and the checkout is
       clean.
    
    3. **Grade with a separate judge that applies judgment.** Hand a fresh judge
       the artifact, the bar, and the skill's **first principles** — so it grades
       against the skill's own intent, not its personal taste — but never the
       expected output and never "make this pass." Grounded in those principles
       the judge is a competent practitioner: it decides whether the work clears
       the bar with *defensible* choices, and is explicitly free to fault both
       too-coarse and too-fine work. It must cite specific evidence for each
       verdict — a quote or pointer, not a number. Done when every part of the bar
       has a verdict grounded in the artifact.
    
    4. **Account for nondeterminism.** Agents flicker. A single green is not
       proof. For any case that matters or any verdict that looks borderline,
       re-run the blind run 2–3× and report the pass *rate*. A skill that passes
       1 of 3 is not fixed.
    
    5. **Diagnose each failure as skill-defect vs bad-case.** A miss means either
       the skill failed to drive the behavior (fixable here) **or** the bar was
       wrong — it asked for something the skill should not do, can't express, or
       it punished a defensible judgment call the skill was right to make (tell
       the user; do not edit the skill to chase a wrong bar — that just encodes
       the wrong reality). Name the defect against the `write-skills` failure
       modes:
       premature completion, vague completion criterion, missing rule, no leading
       word, duplication, sediment, war story, no-op.
    
    6. **Revise via write-skills.** Fix the named defect — and obey those
       authoring rules while you do it: sharpen the completion criterion before
       adding bulk, prefer one leading word over more sentences, add no no-ops.
       The failure is the spec for the edit; change only what the failure points
       at.
    
    7. **Re-eval all cases, not just the failed one.** A fix can regress a case
       that was passing. Loop until every case clears its rate bar, or until you
       can show the skill structurally can't express a case — then report that
       instead of forcing it.
    
    ## Output
    
    A short report: per case, pass rate and the cited gap; the defect each
    failure mapped to; the edits you made (or, if the user asked to approve
    first, the diff you propose); and the re-eval result. Make the before/after
    movement legible — this is the evidence the skill actually improved.
    
    ## Rules
    
    - **Blind is non-negotiable.** The runner sees input only. The judge sees
      artifact + bar + the skill's first principles. The moment either sees the
      expected output, the eval is worthless.
    - **Test judgment, not conformance.** The bar is a standard the work must
      clear, never a checklist of the answer. If you find yourself listing the
      exact pieces you expect, you've stopped evaluating the skill.
    - **Isolation is best-effort; the sweep is the guarantee.** Always check the
      live checkout after a run and clean leaks, no matter how the run was
      sandboxed.
    - One fresh agent per case per run — no shared context, so no cross-case
      learning inflates a later case.
    - Grade against the bar, not against the other artifacts, and not on a
      numeric score that hides which part of the bar failed.
    - Don't bend the skill to pass a case you can't defend. A failing case that
      exposes a bad bar is a finding, not a bug.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/dzhng-skills-skills-authoring-eval-skills.md

// REPO STATS

1.5k stars
0 open issues
Last commit: 4d ago