Choose-Security — The Ultimate Security Review Skill Chain

Stop asking "is this safe?" — start shipping "fixed, documented, and verified."

Choose-Security is a chain of three AI-agent skills that turns a security review into a complete workflow: find the vulnerabilities, document them in a living ledger, fix them in priority order, and prove the fixes with a re-review. It runs end to end inside Claude Code, pi, opencode, Cursor, or any skill-capable agent — no separate tools, no external scanners.

Table of contents

• The chain
• How it works
• Why a chain instead of one giant skill
• Quick start
• Manual installation
• Usage
• Design principles
• Repository layout
• Contributing
• License

The chain

Most security reviews end at a list of findings. Then what? Copy-pasting checklists, juggling severity scores, and hoping the fixes actually land.

Choose-Security fixes that. Instead of one giant checklist, it is a pipeline of three focused skills, each producing the artifact the next one consumes:

| # | Skill | What it does | Output | | --- | --- | --- | --- | | 1 | choose-security-review | Thinks like an attacker, writes like a defender. Scans 13 domains — OWASP Top 10, auth/sessions/JWT, REST & GraphQL APIs, crypto & secrets, dependencies & supply chain, cloud/IaC, Docker & Kubernetes, CI/CD, frontend/framework XSS, security headers, mobile, logging/monitoring, STRIDE threat modeling — with a master checklist and a reproducible finding format. | Severity-scored findings | | 2 | vulnerability | Consolidates findings into one authoritative, living ledger: stable IDs (VULN-001…), CVSS vectors, a full status lifecycle (open → triaging → fixing → fixed → verified → accepted_risk / false_positive / reopened), redaction rules, and a changelog. | VULNERABILITY.md | | 3 | choose-security | Turns the ledger into a phased, dependency-aware remediation roadmap and executes it: containment → Critical → High → Medium → Low/hardening → verification. Every task has steps, acceptance criteria, a verification method, and rollback. | CHOOSE-SECURITY.md + applied fixes |

The loop closes: after fixes land, skill 1 re-reviews the changed code, and the ledger is updated to verified or reopened. Done means no open Critical/High findings and a clean re-review — with the audit trail to prove it.

How it works

flowchart LR
    A["1 · choose-security-review<br/>(find & triage vulns)"] -->|findings| B["2 · vulnerability skill<br/>(document the ledger)"]
    B -->|VULNERABILITY.md| C["3 · choose-security skill<br/>(plan AND apply fixes)"]
    C -->|CHOOSE-SECURITY.md| D["apply fixes per phase"]
    D -->|re-review| A
    style A fill:#0f172a,stroke:#38bdf8,color:#f8fafc
    style B fill:#0f172a,stroke:#4ade80,color:#f8fafc
    style C fill:#0f172a,stroke:#fbbf24,color:#f8fafc
    style D fill:#1e293b,stroke:#94a3b8,color:#f8fafc

Plain-text fallback (for non-rendering viewers):

[1] choose-security-review ──findings──▶ [2] vulnerability skill ──VULNERABILITY.md──▶ [3] choose-security skill
   find & triage vulns                    document the ledger                            plan AND apply fixes
                                                                                                   │
                                                                              CHOOSE-SECURITY.md   ▼
            ▲───────────────────────────────re-review the fixed code───────────────────────────────┘

Why a chain instead of one giant skill

• Each skill is focused. Finding ≠ documenting ≠ fixing. Splitting them keeps each prompt small enough for the agent to actually follow.
• The ledger is the hand-off artifact. VULNERABILITY.md gives you an audit trail: what was found, when, by whom, and what happened to it. The changelog is the proof.
• Fixing is sequenced, not ad-hoc. Containment first, then severity order, with dependencies respected — so you never rotate a key after revoking the access it protected.
• It loops. Verification re-runs the review, so fixes are proven, not assumed.
• Reproducible reviews. The same rigor across repos, PRs, Dockerfiles, Actions workflows, and infrastructure-as-code.
• Zero new tooling. The skills run inside the agents you already use.

Quick start

npx choose-security install                  # all three skills, global scope
npx choose-security install --scope both     # global + project (current dir)
npx choose-security install claude opencode  # specific agents
npx choose-security list                     # what's installed and where
npx choose-security uninstall                # remove the skills again

That installs all three skills into Claude Code, pi, and opencode. Then just ask:

"Review this repo for security" → "write up the findings" → "fix them" → "verify"

Manual installation

Prefer the CLI above — manual install is only for agents or setups the CLI does not cover. Each skill is self-contained (frontmatter + instructions): copy SKILL.md (skill 1) and the two skills/*/ directories into the agent's skills folder.

Claude Code — global ~/.claude/skills/, project .claude/skills/:

mkdir -p ~/.claude/skills
cp -r skills/vulnerability ~/.claude/skills/
cp -r skills/choose-security ~/.claude/skills/
cp SKILL.md ~/.claude/skills/choose-security-review/SKILL.md   # or symlink

pi — global ~/.pi/agent/skills/, project .pi/skills/ (also reads ~/.agents/skills/ and .agents/skills/):

mkdir -p ~/.pi/agent/skills
cp -r skills/* ~/.pi/agent/skills/
cp SKILL.md ~/.pi/agent/skills/choose-security-review/SKILL.md

opencode — global ~/.config/opencode/skills/, project .opencode/skills/ (also auto-discovers the .claude/skills and .agents/skills dirs above):

mkdir -p ~/.config/opencode/skills
cp -r skills/* ~/.config/opencode/skills/
cp SKILL.md ~/.config/opencode/skills/choose-security-review/SKILL.md

Anywhere / vendored: keep the whole repo in the project and reference the three paths directly. The skills point at each other by relative path, so the chain works without installation.

Usage

| You say | The chain does | | --- | --- | | "Review this repo/PR/Dockerfile/Actions workflow for security" | Skill 1 reviews, produces findings | | "Write up the findings / create a VULNERABILITY.md" | Skill 2 produces VULNERABILITY.md | | "Fix these / plan the remediation / harden this" | Skill 3 produces CHOOSE-SECURITY.md and applies fixes phase by phase | | "Verify the fixes / re-review" | Skill 1 re-runs, ledger statuses updated to verified |

Design principles

1. Exploitability × impact, not bug-spotting for fun — everything is prioritized by real-world risk.
2. Trace to the sink. Input reaching a dangerous function is a finding; naming conventions are not.
3. Recommend, don't just diagnose — every finding and every task carries a concrete fix.
4. Truthful statuses. A finding is fixed only when the code changed, verified only when the re-check passes.
5. Strictly defensive. These skills find and fix vulnerabilities in code you own or are authorized to review — never to build attack tooling.

Repository layout

Choose-Security/
├── README.md               # chain overview + install guide
├── SKILL.md                # skill 1 — choose-security-review (entry point)
├── package.json            # npm package: `npx choose-security install`
├── bin/
│   └── choose-security.mjs # CLI installer for Claude Code / pi / opencode
├── CHANGELOG.md            # keep-a-changelog
├── CONTRIBUTING.md         # how to extend the skills
├── SECURITY.md             # vulnerability disclosure policy
├── LICENSE                 # MIT
├── .editorconfig           # consistent editor defaults
├── .markdownlint.json      # markdownlint rules (prose ≤ 80 cols)
├── assets/
│   └── og-image.png        # hero / social preview
├── .github/
│   └── ISSUE_TEMPLATE/     # bug / feature / skill-request forms
└── skills/
    ├── vulnerability/
    │   └── SKILL.md        # skill 2 — writes VULNERABILITY.md
    └── choose-security/
        └── SKILL.md        # skill 3 — writes & executes CHOOSE-SECURITY.md

Contributing

Contributions welcome — new checklist items, review domains, sharper templates. See CONTRIBUTING.md and the issue templates. Changes are tracked in CHANGELOG.md.

Found a security problem in this repo itself? Don't open a public issue — see SECURITY.md.

License

MIT — use it, fork it, make your company's security reviews run on it.