skills

skills

Professional-grade skills for agentic software engineers who use coding agents to plan, implement, test, and review production software. These skills turn vague requests into spec files or GitHub issues, expose weak tests and brittle defenses, and prevent blind acceptance of automated review feedback. Compatible with GitHub Copilot, Gemini CLI, Claude Code, and 50+ other agents via the Agent Skills spec. Claude Code users can also install individual skills via the plugin marketplace.

Available Skills

Skill	Phase	Description
feature-to-plan	Planning	Converts feature requests and issues into an EARS spec file or one new GitHub issue
to-ears	Planning	Drafts, reviews, and test-maps EARS requirements without inventing behavior; owns the EARS Contract the planning skills share
issue-refine-loop	Planning	Rewrites a GitHub issue, then splits it into session-sized children with only real blockers
spec-auditor	Planning / Hardening	Adversarially audits specs, PRDs, issues, and plans before coding starts
plan-to-graph	Planning	Converts specs, master plans, and GitHub epics into GitHub sub-issue dependency graphs
designing-for-intent	Planning	Reviews a UX/onboarding/consent artifact for intent map, delegation boundary, and agency risks before implementation
customer-strategy-forge	Product Strategy	Turns customer evidence into auditable personas, journeys, progression hypotheses, and opportunity maps
go-testable-design	Implementation	Guides Go development with TDD: small tests first, public behavior, IO at the edges
code-tidy	Implementation / Hardening	Tidies the files a PR or branch changed against its base (all tracked source on the default branch or with whole-repo): autonomous coach-first Stage-B refactor by default, then SOLID with no further behavior change
rugged-evil-tester	Testing / Hardening	Generates adversarial, security, and chaos tests for TypeScript code
mutation-hunter	Testing / Hardening	Finds test coverage gaps by running mutation testing on TypeScript, Go, or Python
triaging-pr-reviews	Code Review	Triages PR review comments: verifies claims, classifies concerns, and decides what to act on
curate-release	Code Review / Release	Rewrites a PR's commits into a coherent release story semantic-release can publish
skill-reviewer	Tooling / Meta	Validates and lints SKILL.md files for quality, discoverability, and correctness
instruction-style	Tooling / Meta	Revises AGENTS.md, CLAUDE.md, Copilot, OpenCode, and Codex instruction files so priority, rationale, and scope survive the edit
optimize-prompt-loop	Tooling / Meta	Turns a fuzzy or overly broad request into a concise task prompt fitted to the current model, harness, and effort level

---

Workflows

Skills are designed to be composed. The sections below show two common patterns: a planning workflow that produces a spec file, a new GitHub issue, or a rewritten epic, and a map of where each skill belongs across the broader delivery lifecycle.

For agentic software engineers, the value is not simply "more prompts." Each skill gives your agent a specific harness-engineering role with explicit standards, evidence requirements, and failure modes:

• Before coding: convert intent into a spec file or one new GitHub issue, or rewrite an existing GitHub issue, before an agent implements it.
• Before product commitments: audit customer evidence, synthesize only supported personas or journeys, then map independently reviewed needs to product opportunities.
• Before scheduling: turn approved work into dependency-aware issues that preserve verification context.
• Before merge: generate hostile tests, find mutation survivors, and triage review comments by verifying claims against code.
• Before publishing skills: review skill instructions themselves so the agent behavior stays discoverable, portable, and robust.

Hi-Fi Planning

Hi-fi planning is writing acceptance criteria and tasks before implementation. The four planning skills share that bar — EARS criteria, personas, value assessment, Mermaid design — but they are stages with one destination (an executable GitHub issue graph), not a single pipeline:

• Author a spec file — feature-to-plan → spec-auditor → plan-to-graph
• Author one new GitHub issue — feature-to-plan (ask it to keep the plan on GitHub) → issue-refine-loop or plan-to-graph if the tasks are already session-sized
• Rewrite an issue that already exists — issue-refine-loop

feature-to-plan creates a new artifact. issue-refine-loop rewrites an existing issue in place. plan-to-graph fans out an approved task list. When both authoring skills are installed, issue-refine-loop uses feature-to-plan's format rules for task anatomy. All three skills that write or check criteria (feature-to-plan, issue-refine-loop, spec-auditor) share one EARS Contract owned by to-ears. issue-refine-loop does not read or write the spec file.

                        ┌─ spec file ──► spec-auditor ──► plan-to-graph ──┐
freeform idea ──► feature-to-plan                                          ├──► parallel-ready
                        └─ new GitHub issue ─┬─ issue-refine-loop ─────────┤     issue graph
                                             └─ plan-to-graph ─────────────┘
existing thin issue ─────────────────────────► issue-refine-loop ──────────┘

Rewrite an existing GitHub issue with issue-refine-loop

Requires an issue number or URL — it will not create the issue from a freeform idea. It snapshots the original body as a comment, adds acceptance criteria, design, and tasks to that issue, then splits those tasks into child issues on GitHub. Each child is sized for one coding-agent session (roughly one to three files). A child lists Depends on only when another child actually blocks it; independent children have no blocker and are labeled refined, so they can be picked up in parallel. It does not write files in your repo. If plan-to-graph is installed and authenticated gh can create native sub-issues, child creation uses it; otherwise the skill creates the children itself.

npx skills add lousy-agents/skills --skill issue-refine-loop --skill feature-to-plan

feature-to-plan is optional on this path. Install it if you want the shared format skill present (issue-refine-loop prefers it for task anatomy), or if you need it to create the starting issue from a freeform idea first. Add --skill to-ears to use the full EARS method for drafting and reviewing criteria. Without it, the contract copy inside issue-refine-loop applies.

"Refine issue #47" "Use issue-refine-loop on https://github.com/owner/repo/issues/162"

Write a spec file in the repo

Step 1: Draft the spec with feature-to-plan

Point the skill at a GitHub issue number, a freeform idea, or nothing (it will ask). Default output is a Markdown spec under .github/specs/ with personas, EARS acceptance criteria, Mermaid diagrams, and a task checklist. Ask it to keep the plan on GitHub and it creates one new issue with the same section set instead — a drafted plan, not a refined epic, and not a child graph. That is a new issue, not a rewrite of an issue you already have.

npx skills add lousy-agents/skills --skill feature-to-plan

Invoke it in your agent:

"Draft a spec for adding OAuth login to the API" "Use feature-to-plan on issue #47" "Draft this as a GitHub issue and keep it on GitHub"

Step 2: Audit the spec with spec-auditor

Before implementation, run the draft through an adversarial review. spec-auditor finds contradictions, missing edge cases, untestable acceptance criteria, ambiguous ownership, and handoff risks that cause coding agents to build the wrong thing or falsely report completion. It returns structured findings with severity, evidence, Socratic questions, suggested spec patches, verification implications, and downstream agent instructions.

npx skills add lousy-agents/skills --skill spec-auditor

Invoke it in your agent:

"Audit .github/specs/oauth-login.spec.md for coding-agent failure risks" "Use spec-auditor on issue #47 before implementation"

Step 3: Convert the approved spec to a dependency graph with plan-to-graph

Feed the approved spec or a GitHub epic to plan-to-graph. It parses the tasks, drafts a graph for your review, then creates native GitHub sub-issues with the full task content preserved in each body and explicit blocking dependencies.

npx skills add lousy-agents/skills --skill plan-to-graph

Invoke it in your agent:

"Convert .github/specs/oauth-login.spec.md into GitHub sub-issues in OWNER/REPO" "Create the task graph for GitHub epic #47"

Install all three at once:

npx skills add lousy-agents/skills --skill feature-to-plan --skill to-ears --skill spec-auditor --skill plan-to-graph

Prerequisite: plan-to-graph requires a resolvable target repository and a way to create native sub-issues and blocking relationships: authenticated gh with gh issue create --parent and gh issue edit --add-blocked-by, or GitHub MCP / the harness's built-in GitHub tools when gh is absent or lacks those flags. The skill checks this before it creates anything and stops if neither works.

---

Regular SDLC

The full set of skills spans the software delivery lifecycle. The table below shows the natural entry point for each skill as features move from idea to production.

┌────────────────────────────────────────────────────────────────────────────────────┐
│  Planning              │  Implementation  │  Testing     │  Review                 │
├────────────────────────────────────────────────────────────────────────────────────┤
│  feature-to-plan       │  go-testable-    │  rugged-     │  triaging-pr-reviews    │
│  issue-refine-loop     │  design          │  evil-tester │  curate-release         │
│  spec-auditor          │  code-tidy       │  mutation-   │                         │
│  plan-to-graph         │  (your agent or  │  hunter      │                         │
│  designing-for-intent  │  engineers)      │              │                         │
│  customer-strategy-    │                  │              │                         │
│  forge                 │                  │              │                         │
└────────────────────────────────────────────────────────────────────────────────────┘

Skill	When in the lifecycle
feature-to-plan	Before implementation begins: when you want a spec file or one new GitHub issue from an idea or seed
to-ears	Before implementation begins: converting, reviewing, or deriving tests from requirements or acceptance criteria — standalone, or called by the planning skills
issue-refine-loop	Before implementation begins: you have a GitHub issue to split into session-sized, parallel-ready children
spec-auditor	Before implementation begins: you have a draft spec or issue and want findings, not edits
plan-to-graph	After the spec is approved: to turn tasks into tracked work items
designing-for-intent	Before implementation, independent of whether a spec exists yet: reviewing a UX/onboarding/consent artifact for intent and agency risk
customer-strategy-forge	Before product commitments: auditing customer evidence, developing customer artifacts, or mapping passed needs and journeys to product opportunities
go-testable-design	During implementation: to write Go code test-first and design testable boundaries
code-tidy	During or after implementation, before review: tidy the files this branch changed against its base, or all tracked source when on the default branch or asked for whole-repo.
rugged-evil-tester	During or after implementation: to harden new code against adversarial inputs
mutation-hunter	During or after implementation: to audit whether your test suite would catch real regressions
triaging-pr-reviews	At review time: to process Copilot or human review comments without blindly applying them
curate-release	At merge time: to curate a PR's commits so the release notes tell a coherent story
skill-reviewer	When authoring or updating a SKILL.md: a contributor/meta tool, not part of the delivery flow
instruction-style	When authoring or revising AGENTS.md, CLAUDE.md, or another harness instruction file: a contributor/meta tool, not part of the delivery flow
optimize-prompt-loop	Before handing a fuzzy request to an agent, at any stage: to get a concise, runtime-fitted task prompt, optionally executed once

---

feature-to-plan

Install: npx skills add lousy-agents/skills --skill feature-to-plan

Converts feature requests — either freeform or seeded from a GitHub issue — into an EARS spec file by default, or into one new GitHub issue with that same plan when you ask to keep it on GitHub. It supports both single-shot generation and interactive, multi-turn drafting.

Use when you want to:

• Turn a freeform idea or a seed issue into a spec file before writing code
• File that same drafted plan as one new GitHub issue instead of a file
• Break down feature requirements into specific Personas, User Stories, and Tasks
• Automatically generate Mermaid diagrams (data-flow, sequence) for your proposed architecture

Do NOT use when:

• You want an existing GitHub issue rewritten into an epic. Use issue-refine-loop instead.
• You want an approved task list fanned into child issues. Use plan-to-graph instead.

Outputs a Markdown spec file (e.g., in .github/specs/) by default, or one new GitHub issue on request — unchecked task lists, no children, no blocking edges, no lifecycle label unless you opt in to needs-refine. issue-refine-loop rewrites an existing issue in place and splits it; plan-to-graph fans an already-approved task list into the graph.

Requires GitHub access (gh or the agent's GitHub tools) only for issue output or for seeding from / commenting on an issue. Spec-file output does not.

Works best with to-ears. When it is installed, this skill uses it to draft and review acceptance criteria. Without it, the EARS Contract copied into this skill applies.

---

to-ears

Install: npx skills add lousy-agents/skills --skill to-ears

Turns requirements into EARS (Easy Approach to Requirements Syntax) without inventing behavior, then reviews them for meaning and derives tests from the agreed ones.

• Every criterion carries an AC-<story>.<n> ID and a provenance tag: source-stated, inferred, or an inline [TBD] decision. Nothing undecided reads as settled.
• An omission sweep checks for invalid input, dependency failure, degraded states, boundaries, and concurrency. Each gap it finds gets a disposition, not an invented requirement.
• It is the canonical home of the EARS Contract. feature-to-plan and issue-refine-loop carry verbatim copies so each still works when installed alone. CI fails when a copy drifts. spec-auditor's lint enforces the same contract.

Use when you want to:

• Convert prose requirements, a PRD paragraph, or issue acceptance criteria into EARS
• Review existing criteria for pattern misuse, vague terms, bundled obligations, hidden preconditions, and unspecified deny paths
• Derive requirement-based tests, or task verification items, from agreed criteria, kept separate from coverage and exploratory evidence

Do NOT use when:

• You want a whole spec or a new GitHub issue. Use feature-to-plan, which calls this skill.
• You want a whole spec audited. Use spec-auditor.
• You want an existing issue rewritten in place. Use issue-refine-loop.

Outputs criteria, open questions with severity, review findings, an optional test mapping, and a statement of the evidence limits. When another skill calls it, it returns only the criterion lines, the open questions, and the omission-sweep lines.

Evaluated by a claude plugin eval suite in skills/to-ears/evals/. The suite has 4 cases, each run with and without the skill:

• an embedded draft with traps
• a review with planted defects and well-formed controls
• a test map with mixed provenance
• a natural-language trigger

To run it, keep the results directory outside the plugin folder:

claude plugin eval skills/to-ears --judge-model sonnet --output-dir /tmp/to-ears-evals

---

issue-refine-loop

Install: npx skills add lousy-agents/skills --skill issue-refine-loop

Rewrites an existing GitHub issue — title-only, one-sentence, or an epic missing acceptance criteria, design, or tasks — then splits the work into child issues. Each child is sized for one coding-agent session (roughly one to three files). Dependencies are recorded only when one child actually blocks another; independent children have no blocker and are labeled refined, so agents can take them in parallel instead of walking a serial task list. The original body is snapshotted as a comment first. No files are added to your git repo; the issue body, labels, comments, and new child issues change on GitHub.

Use when you want to:

• Fill in a GitHub issue that is too thin to implement (title-only, one sentence, or missing acceptance criteria, design, or tasks)
• Break a large issue into session-sized children that can proceed in parallel except where one truly blocks another
• Keep the plan on an issue that already exists, instead of authoring a new spec file or a new issue

Uses the same persona and task format as feature-to-plan, and the same EARS Contract as to-ears. When those skills are installed, this skill uses them instead of its fallback copies. It does not read or write a spec file.

Do NOT use when:

• You want a new spec file, or one new GitHub issue from a freeform idea. Use feature-to-plan instead.
• The epic is already approved and you only need child issues. Use plan-to-graph instead.
• You want a findings list and nothing changed. Use spec-auditor instead.
• The target is a pull request, discussion, or project card. Only issues.

Requires GitHub access (gh or the agent's GitHub tools) and write permission on the issue.

---

spec-auditor

Install: npx skills add lousy-agents/skills --skill spec-auditor

Adversarially reviews feature specifications, implementation plans, GitHub issues, PRDs, and EARS-format specs before coding starts. It looks for the gaps that make coding agents fail: contradictions, vague acceptance criteria, missing edge cases, unclear ownership, unverifiable outcomes, and scope that spans multiple unrelated changes.

When run from a repository, it reads AGENTS.md, CLAUDE.md, README.md, and other instruction files to anchor findings in real project constraints rather than generic advice.

Use when you want to:

• Stress-test a spec before handing it to Codex, GitHub Copilot, Claude, or another coding agent
• Find ambiguity, missing critical paths, and untestable requirements while they are still cheap to fix
• Produce structured findings (SA-001, SA-002, …) with stable IDs that can feed a spec-improvement loop or downstream agent handoff

Do NOT use when:

• You want to draft a spec file or one new GitHub issue from a feature idea. Use feature-to-plan instead.
• You want to refine a GitHub issue in place into an epic. Use issue-refine-loop instead.
• You want to convert an approved spec into GitHub sub-issues. Use plan-to-graph instead.
• You want to triage PR review comments or Copilot feedback. Use triaging-pr-reviews instead.

Outputs an audit report with severity (Blocker / High / Medium / Low), confidence, evidence, Socratic questions, recommended spec patches, verification implications, and downstream agent instructions. Ask for JSON output to get a machine-readable findings object, useful when piping findings into a spec-improvement loop or another agent. Includes an optional Python lint script that checks a draft against the feature-to-plan template — required sections at the levels the template uses, acceptance criteria per story, the fields each task must carry, and both mandated Mermaid diagram types — while treating fenced blocks as illustrations rather than spec content. It exits 1 when it produced a High finding, 0 when it did not (Medium and Low findings can still be present, so read the output rather than the exit code alone), and 2 when the spec could not be read. The skill's primary value is still adversarial, evidence-grounded review.

---

plan-to-graph

Install: npx skills add lousy-agents/skills --skill plan-to-graph

Converts Lousy Agents specs, master plans, roadmaps, and GitHub epics into native GitHub sub-issues with explicit blocking dependencies. It drafts the graph for confirmation before creating any issue.

Use when you want to:

• Convert a *.spec.md file or master plan into GitHub Issues
• Break a plan's tasks into one epic and a single level of sub-issues with explicit blocking dependencies
• Preserve each task's complete structured content in its child-issue body

Requires a target GitHub repository and authenticated gh with native sub-issue and blocking-relationship support, or GitHub MCP / the harness's built-in GitHub tools when gh is absent or lacks those flags. Re-running against an epic that already has sub-issues will not duplicate them — the skill detects the collision and stops.

---

designing-for-intent

Install: npx skills add lousy-agents/skills --skill designing-for-intent

Reviews a UX flow, agentic handoff point, or delegation-boundary decision for the user's intent map — desired outcome, constraints, and delegation boundary — rather than for the screen or user experience sitting in front of you. Runs in one of two depth modes (strategic for a full cross-surface journey, tactical for a single screen or decision point) and works through a nine-mode adversarial agency pass (silent auto-action, no undo, dead-end on wrong inference, hidden reasoning, intent debt, coherence breaks across surfaces or agents, over-inference from behavior, ignored capacity or deadlines, multi-party action without approval), setting a confidence-to-response policy where even high confidence only proposes, never silently acts.

This is the first skill in this repository to also ship a subagent — ux-advocate, a peer pairing partner that studies how a customer actually encounters a product (onboarding, screens, CLI, docs, consent moments, multi-actor handoffs) from outside the repository. The skill runs the intent/agency method inline in your main conversation; the agent is a separate, complementary customer-reading voice. Neither substitutes for the other: the agent never runs the skill's method or fills its schema. Coach appears only as a labeled worked example in references/; it is not a runtime dependency.

Install path	Skill	Agent
/plugin install designing-for-intent@lousy-agents	yes	yes, as designing-for-intent:ux-advocate
npx skills add lousy-agents/skills --skill designing-for-intent	yes	copied but inert (Claude Code only discovers subagents at .claude/agents/ or a plugin root)

Use when you want to:

• Review a screen, flow, journey, or report for whether it faithfully carries the user's intent, or quietly substitutes a system's convenient interpretation of it
• Audit an onboarding or consent moment (an install step, a permission grant, a data-sharing choice) for whether the person understands and controls what they are agreeing to
• Check the delegation boundary, confidence-to-response policy, and undo path at a point where a feature or agent proposes to act on a user's behalf
• Audit a multi-agent handoff for coherence — does the user's intent survive the trip from one surface or agent to the next, or does it drift?

Do NOT use when:

• You want a release-readiness, adoption risk, or ship/no-ship verdict — hand that to your project's product-strategy peer (or dedicated go/no-go evaluation flow); this skill only feeds that peer the evidence question, it never answers it
• You want infrastructure, security model, or platform-foundation questions answered — hand that to your project's system-design peer
• You want implementation work done — hand that to whatever implementation workflow your project uses, once a design decision has actually been made

Outputs a two-to-three sentence verdict naming the sharpest finding, then an Intent map, Interaction model, Orchestration surface, severity-ranked Agency risks with stable IDs, Open questions, and Out of scope — plus an editable YAML intent/constraint object the human keeps evolving as their own understanding of the request evolves. Ships a pilot worked example (references/github-app-install.md, Coach-shaped and fenced so it does not leak into the host) and a pattern library (references/pattern-library.md) with a trust-posture fence: when a host project states no explicit trust posture, both the skill and the ux-advocate agent default to propose-and-confirm, no silent irreversible action, and coverage honesty over anticipatory automation, recording that default as an Open Question rather than assuming a posture was found and read.

---

customer-strategy-forge

Install: npx skills add lousy-agents/skills --skill customer-strategy-forge

Turns versioned customer evidence into claim-level, auditable strategy artifacts without reverse-engineering customer needs from an existing product. It can stop after a Grounding Brief and Evidence Audit, develop a persona, situation, journey, or progression hypothesis when the evidence permits it, and introduce product or portfolio capabilities only after an independent critic passes the customer model.

The same skill supports two execution styles:

• Paired — works with a human at material scope, evidence, privacy, and authorization gates.
• Autonomous — lets a delegated subagent complete the authorized run without questions, ending with either a supported artifact or a terminal stop artifact when evidence, isolation, authority, or an independent critic is unavailable.

Use when you want to:

• Audit what an interview, observation, support, telemetry, founder, or social Signal Pack can safely support
• Develop or revise an evidence-backed persona, behavioral segment, situation card, customer journey, or progression hypothesis
• Map independently reviewed customer jobs and transitions to products, modules, alternatives, partnerships, or intentional non-action
• Preserve contradictions, claim-level validation, decision limits, and rerun history across strategy work

Do NOT use when:

• You want a feature specification or implementation plan — use feature-to-plan after the customer decision is bounded
• You want market-size or willingness-to-pay claims from qualitative or social evidence
• You want an agent to scrape live sources silently or generate a persona from a product README

Outputs a versioned Grounding Brief and Evidence Audit by default. Additional customer artifacts are explicit opt-ins and require an independent critic. Failed gates publish only a stop artifact for that run; “no product action” is a valid outcome. The skill keeps product-aware coordination and opportunity mapping separate from product-blind synthesis and criticism, and it does not treat tool metadata as proof of context isolation.

---

go-testable-design

Install: npx skills add lousy-agents/skills --skill go-testable-design

Guides Go development with tests: smallest failing test first, start from public behavior, keep IO out of decision packages, and match the repo's existing acceptance tests. Informed by patterns from learn-go-with-tests.

Use when you want to:

• Build or change Go code using TDD, tests-first, red-green-refactor, or outside-in / acceptance-first starts
• Design testable boundaries around interfaces, io.Reader/io.Writer, fs.FS, http.Handler, context.Context, goroutines, or channels
• Refactor Go code while preserving behavior, or review Go code for testability gaps

Standard-library-first. Covers table tests, subtests, t.Helper(), constructor injection, httptest, goroutine/concurrency tests, property tests, and acceptance suites that follow the repository's existing test harness.

---

code-tidy

Install: npx skills add lousy-agents/skills --skill code-tidy

Tidies the files a PR or branch changed against its base (the PR's base, or the default branch when no PR exists), or all tracked source when run on the default branch or asked for whole-repo: an autonomous coach CodeSignal loop first (Stage-B defect fixes on by default; may change behavior), then a SOLID tidy with no further behavior change. Tests become the documentation, production code is extracted and renamed until it reads as prose, comments are deleted unless they earn their place. The suite and linter stay no worse than the post-coach pass-1 baseline.

Requires: a usable coach on PATH, or mise to fetch one. Mise is only needed when no usable PATH coach exists — a preprovisioned coach is used as-is. Otherwise mise fetches the pinned coach version (github:lousy-agents/coach@v0.6.0, or the repository's mise.toml / mise.lock pin), falling back to the go: backend at cmd/coach@v0.6.0 or a source build of that tag where the GitHub API is refused. No coach and no mise after one install attempt is a blocker.

Acquisition is fail-closed. Only a PATH coach and a cosign-verified release archive run unquestioned; every fetch rank below them resolves a mutable tag and is refused unless the invocation says allow-unverified-coach. So in an environment with no preinstalled coach and no cosign — the default in Claude Code Remote — the coach phase is skipped with a reason and SOLID still runs; pass allow-unverified-coach to let the mise ladder fetch one. Claude Code Remote needs no gh either: GitHub MCP tools stand in for PR lookup, and coach resolves through the Go module proxy.

Stage-B default: coach Stage-B production edits are on by default (may change behavior; prefer fixing production code over silencing; regression guard + holding test before each Stage-B commit). Opt out with solid-only / no-behavior-change / prune-comments-only — then classify Stage-B, list under questions, and run SOLID/comments only. Legacy allow-behavior-fix / allow-behavior-change is a redundant alias for the default. The SOLID pass is behavior-preserving either way. Reports lead with Stage-B fixed/remaining/SHAs; DONE — thorough is forbidden from comment deletes while Stage-B remains, and after a Stage-B commit must disclose that behavior may have changed and name those SHAs. Prepare blockers report status BLOCKED, never PASS 0/5.

Use when you want to:

• Tidy a PR or a feature branch's diff, or hunt all tracked source with whole-repo
• Prune comments to the ones that cite a real constraint, spec, or inexpressible invariant
• Make tests document behavior with the repository's existing test runner
• Extract and rename until functions read as prose, without speculative abstractions

Do NOT use to: write new features, author new Go tests (go-testable-design; Stage-B holding/characterization tests on the default coach-loop are the exception), rewrite history (curate-release), triage review comments (triaging-pr-reviews), or edit instruction-file prose (instruction-style).

Outputs: commits on the current branch with a Cleanup-Loop: pass=N trailer, a .cleanup-loop.md state file that ships with the PR and is committed at the end of every pass, and a fixed report block. One invocation does one pass and stops.

Where it is catalogued: Implementation / Hardening in the table above, category: development in the Claude plugin marketplace, and the Implementation & Quality group in skills.sh.json.

---

rugged-evil-tester

Install: npx skills add lousy-agents/skills --skill rugged-evil-tester

Generates adversarial tests that prove your defenses actually work. Instead of happy-path coverage, this skill targets security weaknesses, boundary conditions, and chaos scenarios.

Use when you want to:

• Test whether input validation rejects SQL injection, XSS, prototype pollution, and similar payloads
• Verify that failures in external dependencies (auth services, databases, caches) cause the system to fail closed
• Add security regression tests to CI that prove defensive layers can't be bypassed

TypeScript-focused. Uses Vitest and MSW. Places test files as <target>.evil.test.ts alongside source files.

---

mutation-hunter

Install: npx skills add lousy-agents/skills --skill mutation-hunter

Applies semantic mutations to TypeScript, Go, or Python source code — swapping operators, removing null guards, inverting conditions — and identifies mutations that survive without causing any tests to fail. Each surviving mutation is a concrete test gap with actionable advice on how to close it.

Use when you want to:

• Audit whether your test suite would catch real behavioral regressions
• Get a coverage grade (A–F) based on mutation survival rate
• Identify exactly which boundary conditions, operator assumptions, and null-handling paths are untested

Works on TypeScript, Go, and Python — language is detected from the repo. Outputs a JSON report with killed/survived mutations, coverage grade, and per-gap advice. Reverts all mutations before finishing — the codebase is always left clean.

---

triaging-pr-reviews

Install: npx skills add lousy-agents/skills --skill triaging-pr-reviews

Processes PR review comments — from humans or automated reviewers like GitHub Copilot — by verifying each claim against the actual code before acting on it. Automated reviewers frequently cite the wrong lines, describe behavior that can't occur, or suggest fixes that introduce the vulnerability they claim to prevent.

Use when you want to:

• Work through Copilot or CodeRabbit suggestions without blindly implementing them
• Catch review direction left as a plain conversation comment, not only as inline comments
• Skip threads an earlier round already resolved, instead of re-verifying them
• Classify comments by root concern (security, correctness, style) and prioritize fixes
• Automatically reply to review threads and resolve them after fixes land

It triages every comment whose thread is still unresolved, plus conversation-tab comments and review summaries — not the most recent batch. One submitted review's comments do not share a timestamp, so grouping by time splits a single review and leaves part of it untriaged.

Requires an authenticated gh CLI and jq locally, or GitHub MCP / the harness's built-in GitHub tools when gh is absent — including Claude Code cloud sessions, which do not pre-install gh. The bound surface must also be able to read review threads and their resolution state. A surface that cannot is rejected during the probe, with the missing capability named, rather than binding and then re-triaging threads that were already closed.

---

curate-release

Install: npx skills add lousy-agents/skills --skill curate-release

Rewrites the commits on a pull request's head branch so the release notes semantic-release generates read as a coherent story. Types each commit by customer impact rather than by which files moved — a real fix typed chore does not merely go unmentioned, it can leave the entire release unpublished. The tree at HEAD stays byte-identical to the tree it started from; only commit boundaries and messages change.

Use when you want to:

• Turn wip / address review / fix typo commits into Conventional Commits before merge
• Run curation unattended from a gate label, with preflight gates that abort on drafts, forks, squash-only repos, and already-curated branches
• Know what release type and publish channel a PR will actually produce, including pre-release and maintenance branches

Requires a repository that merges by merge commit or rebase — squash-only repositories get a proposed squash title instead of a rewrite.

---

skill-reviewer

Install: npx skills add lousy-agents/skills --skill skill-reviewer

Audits SKILL.md files for correctness, discoverability, and structure. Checks frontmatter validity, description quality (the primary discovery surface), body structure, progressive loading budget, and common anti-patterns.

Use when you want to:

• Validate a new or updated skill before merging
• Debug why an agent isn't discovering or invoking a skill
• Ensure a skill follows the Agent Skills spec and will work across supported agents

---

instruction-style

Install: npx skills add lousy-agents/skills --skill instruction-style

Authors or revises durable agent-facing instruction prose — AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, path-scoped *.instructions.md, OpenCode instructions, Codex and Claude subagent and command files — so an agent reads the right priority, sees why each constraint exists, and does not apply a rule where it does not fit. Detects the file's incumbent modal vocabulary and closes the set around it rather than imposing one, keeps the reason clauses and intent markers a length-driven pass deletes first, checks instruction claims against the code and CI they describe, and places rules on the intersection of the harnesses' load paths (verified per harness in references/harness-load.md). Proposes a diff by default; writes files only on an explicit apply.

Use when you want to:

• Clean up, tighten, harden, or standardize instruction files without losing the rationale they carry
• Settle obligation wording on one closed modal set per file, in that file's own vocabulary
• Place a rule across a hybrid harness set (Copilot applyTo, Claude .claude/rules paths, OpenCode v2 nested AGENTS.md, Codex directory chains)
• Check whether instruction files have drifted from the code and CI they describe

Do NOT use when:

• You want a one-off task prompt optimized for immediate execution (use optimize-prompt-loop)
• You want a SKILL.md linted against Agent Skills packaging rules (use skill-reviewer)
• You want a feature specification audited for implementation defects (use spec-auditor)

---

optimize-prompt-loop

Install: npx skills add lousy-agents/skills --skill optimize-prompt-loop

Turns a source request into the smallest prompt that reliably produces the intended result in the runtime it will run in. It profiles the model, agent harness, and reasoning/effort level from what the session actually discloses — never guessing a model, tool, or permission — then runs a short internal optimization loop for fidelity, a concrete outcome, an executable plan, proportional verification, and a stopping condition. Missing low-impact details become stated assumptions; at most one question is asked when the answer would change scope or safety. When the target model has a rubric (currently Claude Opus 5.5, in references/), a final rubric pass removes scaffolding written for older models and reports the verdict. Returns a paste-ready prompt plus short notes, and executes it once only when you ask.

Use when you want to:

• Turn a vague, sprawling, or inherited prompt into one an agent can execute and verify
• Fit a prompt to a specific model, harness (Claude Code, Codex, Copilot, direct chat), or effort level
• Strip legacy scaffolding — personas, "think step by step", shouting modifiers, re-check rituals — that no longer helps
• Get an optimized prompt and run it in one step

Do NOT use when:

• You want ordinary task execution with no prompt rewrite
• You want durable instruction files (AGENTS.md, CLAUDE.md) revised (use instruction-style)
• You want a SKILL.md linted (use skill-reviewer) or a spec audited (use spec-auditor)

Install

npx skills add lousy-agents/skills

Install a specific skill:

npx skills add lousy-agents/skills --skill <skill-name>

Install to specific agents:

# GitHub Copilot only
npx skills add lousy-agents/skills -a github-copilot

# Gemini CLI only
npx skills add lousy-agents/skills -a gemini-cli

# Both
npx skills add lousy-agents/skills -a github-copilot -a gemini-cli

Install globally (available across all your projects):

npx skills add lousy-agents/skills -g

Claude Code Plugin Marketplace

Claude Code users can install skills individually through the native plugin system:

/plugin marketplace add lousy-agents/skills

Install any skill by name:

/plugin install feature-to-plan@lousy-agents
/plugin install to-ears@lousy-agents
/plugin install issue-refine-loop@lousy-agents
/plugin install plan-to-graph@lousy-agents
/plugin install designing-for-intent@lousy-agents
/plugin install customer-strategy-forge@lousy-agents
/plugin install go-testable-design@lousy-agents
/plugin install code-tidy@lousy-agents
/plugin install rugged-evil-tester@lousy-agents
/plugin install mutation-hunter@lousy-agents
/plugin install spec-auditor@lousy-agents
/plugin install triaging-pr-reviews@lousy-agents
/plugin install curate-release@lousy-agents
/plugin install skill-reviewer@lousy-agents
/plugin install instruction-style@lousy-agents
/plugin install optimize-prompt-loop@lousy-agents

Supported Agents

Skills follow the open Agent Skills specification and are compatible with any agent that supports it, including:

Agent	--agent / -a	Project Path
GitHub Copilot	github-copilot	.agents/skills/
Gemini CLI	gemini-cli	.agents/skills/
Claude Code	claude-code	.claude/skills/
Cursor	cursor	.agents/skills/
Codex	codex	.agents/skills/

For the full list of supported agents, see vercel-labs/skills.

License

BSD 2-Clause

Contributing

Skills live in skills/<name>/SKILL.md. The .agents/skills, .claude/skills, and .github/skills discovery paths are compatibility links to that canonical tree. To scaffold a new skill:

npx -y @lousy-agents/cli new skill <name>

Before submitting a pull request, run the full lint suite — the same check the CI job runs:

npx -y @lousy-agents/cli lint

For the complete contributor checklist (validation gates, mandatory steps, before-commit workflow), see .github/copilot-instructions.md. Codex and Copilot CLI users should start from AGENTS.md, Claude Code users from CLAUDE.md, and Gemini CLI/Antigravity users from GEMINI.md — all three route back to the same canonical checklist without duplicating it.