What is TopGun?
TopGun is a plugin that solves a simple but critical problem: finding and installing the right skill, safely. Without TopGun, you search one registry at a time, install code you've never audited, and have no way to know if a better option exists elsewhere.
TopGun fixes all three problems with a four-stage pipeline:
- FindSkills — searches 16 active registries in parallel
- CompareSkills — ranks candidates by capability, security, popularity, and recency
- SecureSkills — runs SENTINEL audit until 2 consecutive clean passes
- InstallSkills — installs the winner after your approval
The result: every skill you install via TopGun is the best available option, and it has been independently audited before it touches your environment.
Prerequisites
TopGun only requires one thing:
Codex Required
TopGun is installed through the Codex plugin system. You need Codex available before adding the marketplace source.
skills/sentinel/SKILL.md. No prerequisites required — reinstall TopGun to restore it if needed.Installation
With prerequisites in place, add the official TopGun marketplace source in one command:
Codex will register the official marketplace source and make the shared TopGun bundle available without any extra configuration. When the install completes, TopGun should appear in the skill picker without a restart.
TopGun appears. You can also invoke /topgun --help after the install completes.Your First /topgun Invocation
Invoke TopGun with a plain-English description of the skill you need. TopGun interprets the description and searches all registries accordingly.
After you run a /topgun command, the pipeline executes automatically:
-
1
FindSkills searches all registries in parallel
16 active registries are queried simultaneously. Results are normalized to a unified schema and deduplicated by contentSha. This typically completes in 2–5 seconds.
-
2
CompareSkills ranks the candidates
Every candidate is scored across four dimensions and given a composite score. The top-ranked candidate advances to the audit stage.
-
3
SecureSkills runs SENTINEL
SENTINEL audits the top candidate. If findings are detected, TopGun applies fixes and re-runs. This repeats until 2 consecutive clean passes are achieved.
-
4
InstallSkills — you approve, then it installs
TopGun presents the full audit manifest. You review and approve. The skill is installed through the plugin flow when possible, with a local-copy fallback to
~/.codex/skills/if needed.
Understanding the Output
As TopGun runs, it emits a real-time audit trail in the Codex terminal. Here's what a successful run looks like:
Key things to look for:
- Candidate count — how many skills were found and how many were unique after deduplication
- Composite score — the winning skill's overall quality score (0–1)
- Four sub-scores — capability, security, popularity, recency
- SENTINEL passes — both passes must be clean before install is offered
- SHA-256 verified — confirms the skill content was not modified between audit passes
What's Next
Now that you've installed TopGun and run your first command, explore the rest of the documentation: