TopGun/ Help Center/ Core Concepts

Core Concepts

The pipeline, registry adapters, scoring rubric, SENTINEL audit, state management, and caching — all in one place.

The Pipeline

Every /topgun invocation runs a deterministic four-stage pipeline. Stages execute in order; no stage is skipped.

1

FindSkills — Discover

Queries all enabled registries in parallel. Each registry adapter normalizes its results to a unified candidate schema. Candidates with identical contentSha values (SHA-256 of skill content) are deduplicated to a single entry.

2

CompareSkills — Rank

Each unique candidate receives a composite score based on four weighted dimensions. The highest-scoring candidate advances to the audit stage. Scores and all candidate metadata are written to ~/.topgun/candidates.json.

3

SecureSkills — Audit

Invokes the bundled SENTINEL v2.3.0 audit (skills/sentinel/SKILL.md, shipped inside the TopGun plugin) on the top candidate. Requires two consecutive clean passes. Findings are auto-fixed between passes when possible. SHA-256 is re-verified before each pass.

4

InstallSkills — Install

Presents the full audit manifest (scores, findings history, SHA-256, registry source) for user approval. On approval, installs via /plugin install. Falls back to local-copy installation if the plugin system has a known bug.

The pipeline state is checkpointed after each stage to ~/.topgun/state.json. If the pipeline is interrupted, it can resume from the last completed stage. See State & Resume.

Registry Adapters

TopGun uses a registry adapter pattern. Each adapter knows how to query one registry, parse its response format, and return normalized candidates. All adapters run in parallel during the FindSkills stage.

Adapter behavior rules

  • Each adapter has an 8-second timeout. If a registry doesn't respond in time, the adapter returns an empty result and logs a warning — it does not block the pipeline.
  • Adapters implement exponential backoff with up to 3 retries for transient errors (HTTP 429, 503).
  • If 3 or more adapters fail simultaneously, TopGun logs a connectivity warning but continues with the adapters that succeeded.
  • Adapters that require auth tokens (GitHub, Smithery) skip silently if no token is configured rather than throwing errors.
RegistryAuth requiredTimeoutNotes
skills.shNo8sPrimary registry — highest quality signal
agentskill.shNo8sAgent-focused; good tool-pack coverage
SmitheryOptional8sToken unlocks private listings
GitHub TopicsOptional8sToken avoids rate limits (60→5000 req/hr)
GitLabOptional8sToken required for private group repos
npmNo8sSearches @claude-skill scope
LobeHubNo8sREST API; no auth needed
SkillsMPNo8sCommercial; verified publisher badge in score
ClawHubNo8sClaude-native; auto compatibility checks

Scoring Rubric

CompareSkills assigns each candidate a composite score between 0 and 1. The composite is a weighted average of four dimensions:

DimensionWeightBarWhat it measures
Capability match 55%
How closely the skill's described capabilities match the requested task, scored against a domain-specific 5-sub-criterion rubric synthesized from the candidate field
Security posture 20%
Pre-scan signals: no network calls in SKILL.md, minimal allowed-tools, no eval/exec patterns
Popularity 15%
Stars, installs, or download count from the source registry, normalized logarithmically
Recency 10%
Days since last commit or publish; skills updated within 90 days score highest

The composite score formula:

// composite_raw = weighted sum composite_raw = (capability × 0.55) + (security × 0.20) + (popularity × 0.15) + (recency × 0.10) // capability floor — demote low-fit candidates if (capability_match < 30) composite = composite_raw × 0.5 else composite = composite_raw
All four sub-scores and the composite are included in the audit manifest shown at the approval gate, so you can always see exactly why a skill was selected. The capability floor (added in v1.7.3) prevents popular-but-irrelevant skills from displacing true matches with low star counts. As of v0.7.7, the capability sub-score is itself decomposed into 5 weighted sub-criteria (4 domain-specific + a 10-15 weight cap on external_quality_signal so benchmark wins and parent-repo stars never dominate a sparse-pipeline candidate); the rubric and per-candidate breakdown ship inside the comparison JSON.

SENTINEL Audit

SENTINEL v2.3.0 is the adversarial security auditor that ships bundled inside the TopGun plugin at skills/sentinel/SKILL.md. TopGun loads it directly during the SecureSkills stage — no separate installation required.

The 2-pass requirement

TopGun requires two consecutive clean passes — not just one — before a skill is eligible for installation. This guards against a class of attacks where a first-pass fix introduces a new vulnerability.

  1. SENTINEL runs pass 1. Findings (if any) are logged and auto-remediated where possible.
  2. SHA-256 of the (possibly modified) skill content is computed and stored.
  3. SENTINEL runs pass 2 on the same content. SHA-256 is re-verified before the pass starts.
  4. If pass 2 is also clean, the skill is cleared for installation.
  5. If pass 2 finds new issues, the loop restarts. There is no maximum iteration cap, but TopGun will warn after 5 cycles.

SHA-256 integrity gating

Between every pair of passes, TopGun re-hashes the skill content and compares it to the hash from the previous pass. If the hashes differ and no remediation was performed, the pipeline immediately aborts. This prevents any external modification of skill files during the audit loop.

There is no --skip-audit flag. The SENTINEL requirement cannot be bypassed. If you need to install a skill without an audit, use /plugin install directly — TopGun will not do it for you.

Structural Envelope

Before SENTINEL injects skill content into the agent context for analysis, TopGun wraps it in a structural envelope. The envelope is a set of delimiter markers that signal to the agent that the content inside is external data — not executable instructions.

This prevents a class of attacks called prompt injection via skill content, where a malicious SKILL.md contains instructions addressed to the AI model (e.g., "IGNORE PREVIOUS INSTRUCTIONS AND…"). The envelope causes the model to treat all content between the delimiters as documentation text, not commands.

The structural envelope is applied automatically by TopGun. You do not need to configure it. It applies to all skills regardless of their source registry.

State and Resume

TopGun writes pipeline state to ~/.topgun/state.json after each stage completes. If the pipeline is interrupted (Claude Code crash, network loss, Ctrl-C), you can resume it by running the same /topgun command again.

~/.topgun/state.json structure
{ "query": "web scraping skill", "stage": "SecureSkills", // last completed stage "winner": "web-scraper-pro", "winnerSha": "a3f9c2b1...", "auditPasses": 1, // passes completed so far "timestamp": "2026-04-13T10:22:00Z" }

TopGun resumes from the last completed stage, not from the beginning. If FindSkills and CompareSkills already completed, resuming skips those stages and continues with SecureSkills.

Use --reset to discard the state and restart the pipeline from scratch.

Caching

TopGun caches registry results and audit outcomes to avoid redundant work across invocations.

Registry cache

  • Registry results are cached by contentSha (not by skill name), so the same content from different registries is not re-fetched.
  • Cache TTL is 24 hours. After 24 hours, registry queries run fresh.
  • Use --force-audit to bypass the cache and re-audit even if a clean result exists.
  • Use --offline to use only cached results and skip all live registry queries.

Audit cache

  • A clean SENTINEL result is cached against the skill's contentSha.
  • If the same contentSha is encountered again within 24 hours, the cached clean result is used and SENTINEL is not re-invoked.
  • --force-audit bypasses the audit cache and always runs fresh SENTINEL passes.
← Previous Getting Started Next → Command Reference