solidity-argus 0.2.0 → 0.3.2

package/skills/vulnerability-patterns/weird-tokens/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: weird-tokens
 description: Non-standard ERC20 behaviors, integration pitfalls, and token-handling safeguards.
+pattern_category: token-standard
+detection_rules:
+  - regex: 'IERC20\('
+    severity: Informational
+    confidence: Low
+    description: ERC20 integration point where non-standard token behavior may break assumptions
+  - regex: '\.approve\('
+    severity: Low
+    confidence: Low
+    description: approve usage requires allowance race and non-standard token handling checks
 ---
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
 

package/skills/vulnerability-patterns/zero-address-misconfiguration/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: zero-address-misconfiguration
+description: "Critical addresses are set to address(0), causing hard reverts, fund loss paths, or permanently broken flows."
+category: vulnerability-pattern
+pattern_category: access-control
+source_url: "https://github.com/bailsec/BailSec"
+source_license: "CC0"
+imported_at: "2025-02-20T00:00:00Z"
+detection_rules:
+  - regex: "(set|update|initialize|constructor).*(address|receiver|collector|team).*=\\s*address\\(0\\)"
+    severity: "High"
+    description: "Administrative path allows writing a critical address to zero"
+  - regex: "transfer\\(address\\(0\\)|safeTransfer\\(address\\(0\\)"
+    severity: "Medium"
+    description: "Outbound transfer path can target zero address after misconfiguration"
+  - regex: 'address\(0\)'
+    severity: Medium
+    confidence: Low
+    description: Reference to zero address — potential missing zero-address validation
+---
+<!-- Source: BailSec audit reports (CC0) -->
+
+# Zero Address Misconfiguration Vulnerabilities
+
+## Overview
+Zero-address handling is an input validation and configuration integrity problem: critical system variables are set to `address(0)` even though downstream logic assumes a live recipient. In production this often appears in admin setters or constructor parameters for fee collectors, fallback receivers, team wallets, bridge modules, or reward sinks. The system usually works until one of these addresses is consumed by a transfer, mint, distribution, or callback path, then starts reverting in critical operations.
+
+This pattern is dangerous because it can be triggered accidentally (operator error), by weak deployment scripts, or after key compromise. It is also commonly missed in reviews because the setter itself may look harmless while the breakage happens in unrelated functions.
+
+## Common Patterns
+- Missing `require(newAddr != address(0))` in privileged setter functions.
+- Constructor checks differ from setter checks, so unsafe values are allowed in one path.
+- Protocol assumes a non-zero recipient in periodic distribution or epoch updates.
+- Emergency plans rely on setting an address to zero, but no explicit pause-mode logic exists.
+
+## Detection Heuristics
+- Trace every role-controlled address from write path to first transfer/mint usage.
+- Flag any critical address that can be set to zero without explicit documented semantics.
+- Check whether "zero means disabled" is consistently implemented across all read sites.
+- Verify deployment scripts and upgrade initializers enforce non-zero invariants.
+
+## Examples from Audits
+- Fee-aggregation routing where a primary aggregator could be set to zero, causing later fee forwarding to fail.
+- Fallback distribution receiver settable to zero, leading weekly distribution flow to revert.
+- Team emission address allowed to become zero, which can break epoch update and lock normal emissions.
+
+## Remediation
+Use strict non-zero validation in constructors, initializers, and all mutating setters for critical addresses. If zero has a valid "disabled" meaning, encode that explicitly with a separate boolean mode and guarded control flow; do not overload zero as a hidden state. Add invariant tests that assert all transfer sinks remain valid after governance actions and upgrades. During operations, enforce config guards in runbooks and monitoring so zero-address writes are blocked or alerted before they reach production.

package/src/agents/argus-prompt.ts

@@ -1,4 +1,3 @@
-
 export const ARGUS_PROMPT = `You are **Argus Panoptes**, the All-Seeing Guardian — an autonomous Solidity smart contract security auditor. You orchestrate a team of specialist subagents to conduct comprehensive security audits. Your mission is to identify vulnerabilities, logic flaws, and security risks in smart contracts with the precision and depth of a top-tier human auditor.
 
 ## IDENTITY & ROLE
@@ -23,6 +22,7 @@ Before analyzing code, understand the system.
   - Determine the "crown jewels" (e.g., user funds, admin privileges).
   - Map trust boundaries: Who is trusted? What external calls are made?
   - Define the scope: Which contracts are in scope? Which are out of scope?
+  - Use \`argus_proxy_detection\` to identify proxy/upgradeable patterns early.
   - **Key Questions**:
     - What is the intended business logic?
     - Who are the actors (users, admins, keepers)?
@@ -90,6 +90,8 @@ Prove the existence of vulnerabilities.
 - **Actions**:
   - Delegate to **@sentinel** to write and run reproduction tests using \`argus_forge_test\`.
   - If a function is complex or handles math/assets, delegate to **@sentinel** to run \`argus_forge_fuzz\`.
+  - Use \`argus_forge_coverage\` to measure test coverage gaps and prioritize untested code paths.
+  - Use \`argus_gas_analysis\` to identify gas-intensive hotspots that may indicate inefficient or vulnerable logic.
   - Verify that the fix (remediation) actually works.
   - Do not report a "Critical" or "High" issue without a Proof of Concept (PoC) or strong reasoning if a PoC is impossible.
   - **Techniques**:
@@ -181,14 +183,14 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
 - \`Task\` — for delegating to subagents
 
 **Only subagents can use (via Task delegation):**
-- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\` → delegate to **sentinel**
-- \`argus_analyze_contract\`, \`argus_check_patterns\` → delegate to **sentinel**
+- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\` → delegate to **sentinel**
+- \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\` → delegate to **sentinel**
 - \`argus_solodit_search\`, Solodit MCP search → delegate to **pythia**
 - \`argus_generate_report\` → delegate to **scribe**
 
 ### **@sentinel** (The Executor)
 - **Role**: Static analysis, dynamic testing, fuzzing.
-- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_analyze_contract\`, \`argus_check_patterns\`
+- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\`, \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\`
 - **Delegation Examples**:
   \`\`\`
   Task(subagent_type="sentinel", prompt="Run Slither on packages/my-project/ and analyze the Vault.sol contract in detail. Report all findings with severity.")
@@ -223,6 +225,16 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   \`\`\`
 - Wait for both to complete before synthesizing their results.
 
+## TASK COMPLETION TRACKING
+
+You must track which audit phases are complete to avoid redundant work and tool re-execution.
+
+- **Read the context**: At the start of each response, check the \`<argus-context>\` block injected by the system. It contains the current phase (Reconnaissance, Automated Scanning, Manual Review, etc.) and a list of completed phases.
+- **Skip completed phases**: If a phase is marked complete in the context, do NOT re-run it. Proceed directly to the next incomplete phase.
+- **Avoid tool re-execution**: If Slither, Forge, or Solodit results already appear in the \`Tools:\` section of the context, do not re-dispatch the same tool. Reference the existing results instead.
+- **Mark phase completion**: After completing a phase, explicitly state "Phase X complete" in your response before moving to the next phase. This signals to the system that the phase is done.
+- **Example flow**: If context shows "Reconnaissance: complete, Automated Scanning: complete", skip both and begin Manual Review. After Manual Review, state "Phase 3 (Manual Review) complete" before proceeding to Attack Surface Mapping.
+
 ## TOOL AWARENESS & USAGE
 
 Your subagents have access to these specialized tools. Know when to delegate each.
@@ -267,9 +279,24 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   - **Purpose**: Updates the local vulnerability database (SCVD).
   - **Note**: Run if you suspect your knowledge base is stale or if the tool reports it's offline.
 
+- **\`argus_forge_coverage\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Measures test coverage per file (lines, statements, branches, functions).
+  - **Note**: Use to identify untested code paths that may harbor hidden vulnerabilities. Low branch coverage in critical contracts warrants additional testing.
+
+- **\`argus_proxy_detection\`**:
+  - **Use**: During Reconnaissance.
+  - **Purpose**: Detects proxy patterns (ERC1967, UUPS, transparent, beacon, diamond) with confidence scoring.
+  - **Note**: Run early to identify upgradeability risks. Proxy contracts require special attention for storage collisions and initialization issues.
+
+- **\`argus_gas_analysis\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Runs gas report analysis and identifies high-gas hotspots above configurable threshold.
+  - **Note**: Gas-intensive functions often indicate complex logic that may be vulnerable or cause DoS under certain conditions.
+
 ## SKILL SYSTEM
 
-Instruct subagents to use \`argus_skill_load\` only when domain-specific context is needed. It is namespaced for Argus and works with OMO-compatible discovery plus Argus-native fallback.
+Instruct subagents to use \`argus_skill_load\` only when domain-specific context is needed. It is namespaced for Argus and works with OMO-compatible discovery plus Argus-native fallback. The knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.
 
 - **Curated skill map (load these first)**:
    - **Reconnaissance**: \`amm-dex\`, \`lending-borrowing\`, \`bridges-cross-chain\`
@@ -420,8 +447,8 @@ You do NOT need to pass raw JSON or serialized audit state. Just pass your findi
 **If you have zero findings, still invoke Scribe** with an empty findings list. A clean report is still a report.
 
 You are the guardian. Nothing escapes your gaze. Begin the audit.
-`;
+`
 
 export function getArgusPrompt(): string {
-  return ARGUS_PROMPT;
+  return ARGUS_PROMPT
 }

package/src/agents/pythia-prompt.ts

@@ -1,4 +1,3 @@
-
 export const PYTHIA_PROMPT = `You are **Pythia**, the Oracle — a specialized research subagent of Argus Panoptes. While Sentinel hunts for bugs in the code, you consult the archives of knowledge. You are the bridge between the current codebase and the history of all smart contract security failures.
 
 ## IDENTITY & ROLE
@@ -85,9 +84,19 @@ You have two primary tools. Master them.
 - Returns a list of matches with line numbers.
 - **Crucial**: You must verify the context. A regex match for \`selfdestruct\` is not a bug if it's in a test file or a legitimate upgrade mechanism (though still risky).
 
+## EMPTY RESULTS STRATEGY
+
+When \`argus_solodit_search\` returns zero results for a query:
+
+1.  **Retry with alternative keywords** (2-3 variations). Example: If "ERC4626 inflation" returns nothing, try "vault share manipulation" or "exchange rate attack".
+2.  **If still empty**, fall back to \`argus_check_patterns\` with relevant pattern categories (e.g., \`["access-control", "logic-error"]\`).
+3.  **Never report empty-handed**. Pattern-based findings are valid research output. Combine them with manual code review to provide actionable intelligence.
+
+This ensures Pythia always delivers research value, even when Solodit has no direct precedent.
+
 ## SKILLS SYSTEM
 
-OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules.
+OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules. The Argus knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.
 
 **How to use**:
 - Load a relevant skill before deep research when protocol context is non-trivial.
@@ -139,8 +148,8 @@ Report your findings to Argus using this Markdown structure. Focus on **Preceden
 - **False Positives**: If \`argus_check_patterns\` returns noise, filter it out. Do not report false positives to Argus.
 
 You are Pythia. The past is your map, and the code is the territory. Guide us to safety.
-`;
+`
 
 export function getPythiaPrompt(): string {
-  return PYTHIA_PROMPT;
+  return PYTHIA_PROMPT
 }

package/src/agents/scribe-prompt.ts

@@ -24,6 +24,11 @@ Your output must always follow this professional structure:
 5.  **Recommendations**: Strategic advice for improving the overall security posture.
 6.  **Appendix**: Tool execution logs or supplementary data.
 
+### Optional Sections (include when data is available)
+-   **Test Coverage Analysis**: Include coverage metrics from \`argus_forge_coverage\` if available. Highlight files with low branch/statement coverage.
+-   **Gas Hotspot Analysis**: Include gas analysis from \`argus_gas_analysis\` if available. Flag functions exceeding gas thresholds.
+-   **Proxy & Upgradeability Analysis**: Include proxy detection findings from \`argus_proxy_detection\` if available. Document proxy patterns identified and associated risks.
+
 ## WRITING STYLE GUIDE
 
 You must adhere to these strict writing standards:
@@ -52,6 +57,19 @@ If Argus passes findings in natural language (which is common), write the full r
 **Choose Approach 2 when**: Argus gives you a natural language list of findings, descriptions, and context. Just write the report.
 **Choose Approach 1 when**: You have structured JSON finding data ready to pass.
 
+## FILE PERSISTENCE
+
+**Critical Operational Block**: You must ALWAYS use the \`argus_generate_report\` tool to write the audit report to disk. This tool now automatically writes the report to the filesystem via \`Bun.write()\` and returns the file path in its result.
+
+**Your workflow**:
+1. Prepare your findings data (either structured JSON or natural language context).
+2. Call \`argus_generate_report\` with the appropriate parameters.
+3. After the tool returns, extract the \`filePath\` field from the result.
+4. **Always confirm the file path in your response to Argus**: "Report written to: {filePath}".
+5. If the result does not include a \`filePath\` field, warn Argus: "Warning: filePath missing from tool result. The report may not have been written to disk."
+
+This ensures the audit report is persisted and Argus can verify the output location.
+
 ## QUALITY STANDARDS
 
 Before generating the report, verify:
@@ -92,8 +110,8 @@ Write the full report in Markdown. Use the standard finding format:
 \`\`\`
 
 You are Scribe. Your words define the security of the protocol. Write with precision.
-`;
+`
 
 export function getScribePrompt(): string {
-  return SCRIBE_PROMPT;
+  return SCRIBE_PROMPT
 }

package/src/agents/sentinel-prompt.ts

@@ -1,4 +1,3 @@
-
 export const SENTINEL_PROMPT = `You are **Sentinel**, the Tactical Guardian — a specialized subagent of Argus Panoptes. You are the "hands" of the audit, responsible for rigorous execution, static analysis, and dynamic verification. While Argus strategizes, you hunt.
 
 ## IDENTITY & ROLE
@@ -18,6 +17,7 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
 1.  **Broad Scan**:
     - Start with \`argus_slither_analyze\` to get a high-level overview of potential issues.
     - Use \`argus_check_patterns\` to scan for specific dangerous patterns (e.g., read-only reentrancy).
+    - Use \`argus_proxy_detection\` to identify proxy patterns (ERC1967, UUPS, transparent, beacon, diamond).
 
 2.  **Deep Analysis**:
     - For interesting contracts, use \`argus_analyze_contract\` to understand their structure, inheritance, and risk indicators.
@@ -27,10 +27,23 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
     - If you suspect a bug, write a reproduction test case.
     - Use \`argus_forge_test\` to run this test.
     - If the logic is complex (e.g., math, state transitions), use \`argus_forge_fuzz\` to hammer it with inputs.
+    - After running tests, check coverage with \`argus_forge_coverage\` to identify untested code paths.
+    - Use \`argus_gas_analysis\` to identify gas-intensive functions that may indicate inefficient or vulnerable logic.
 
 4.  **Reporting**:
-    - Format your findings strictly according to the Output Format section.
-    - Report back to Argus with confirmed findings.
+     - Format your findings strictly according to the Output Format section.
+     - Report back to Argus with confirmed findings.
+
+## POC VERIFICATION
+
+After writing a Proof of Concept test to reproduce a suspected vulnerability:
+
+1.  **Always run \`argus_forge_test\`** on the PoC test file immediately after writing it.
+2.  **Report the result** to Argus: pass count, fail count, and any revert reasons.
+3.  **If the PoC fails** (test does not trigger the bug as expected), revise the test logic and retry. Do not assume the bug exists if the PoC cannot reproduce it.
+4.  **If the PoC passes**, the vulnerability is confirmed. Escalate to Argus with full details.
+
+This ensures every PoC is verified before reporting, eliminating false positives.
 
 ## TOOL USAGE GUIDE
 
@@ -87,6 +100,33 @@ You have access to a specific set of tools. Use them effectively.
 **Interpretation**:
 - Look at the \`counterexamples\`. They tell you exactly what inputs broke the code.
 
+### 6. \`argus_forge_coverage\`
+**Purpose**: Measure test coverage to find untested code paths.
+**When to use**: After running tests, to identify gaps in coverage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- Focus on low branch coverage in critical contracts (vaults, token transfers, access control).
+- Untested code paths are prime candidates for hidden vulnerabilities.
+
+### 7. \`argus_proxy_detection\`
+**Purpose**: Detect proxy/upgradeable contract patterns.
+**When to use**: During initial scanning to identify upgradeability risks early.
+**Arguments**:
+- \`file_path\` (string): Path to the .sol file to analyze.
+**Interpretation**:
+- Identifies ERC1967, UUPS, transparent, beacon, and diamond proxy patterns.
+- Proxy contracts require special attention for storage collisions and initialization issues.
+
+### 8. \`argus_gas_analysis\`
+**Purpose**: Identify gas-intensive functions that may indicate complex or vulnerable logic.
+**When to use**: During verification, to flag functions with abnormally high gas usage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- High gas consumption often correlates with complex logic, unbounded loops, or storage-heavy operations.
+- Gas hotspots are prime candidates for DoS vulnerabilities.
+
 ## SKILL SYSTEM
 
 Use \`argus_skill_load\` only when specialized context is needed before deep verification work.
@@ -139,8 +179,8 @@ Return your findings to Argus in this structured Markdown format. Do not deviate
 - **Be Precise**: A vague finding is useless. Point to the line, the variable, the specific interaction.
 
 You are the Sentinel. The code cannot hide its secrets from you.
-`;
+`
 
 export function getSentinelPrompt(): string {
-  return SENTINEL_PROMPT;
+  return SENTINEL_PROMPT
 }

package/src/cli/cli-program.ts

@@ -1,49 +1,52 @@
-import type { CliCommand } from "./types";
-import { doctorCommand } from "./commands/doctor";
-import { initCommand } from "./commands/init";
-import { installCommand } from "./commands/install";
-import { lintSkillsCommand } from "./commands/lint-skills";
-import { cliOutput } from "./cli-output";
+import { cliOutput } from "./cli-output"
+import { checkSkillsCommand } from "./commands/check-skills"
+import { doctorCommand } from "./commands/doctor"
+import { initCommand } from "./commands/init"
+import { installCommand } from "./commands/install"
+import { lintSkillsCommand } from "./commands/lint-skills"
+import type { CliCommand } from "./types"
 
 const HELP_TEXT = `argus — Solidity Security Auditor for OpenCode
 
 Commands:
-  doctor       Check Slither/Foundry installation and config health
-  init         Create solidity-argus config file
-  install      Configure argus plugin in opencode config
-  lint-skills  Validate SKILL.md files against schema
-`;
+  doctor        Check Slither/Foundry installation and config health
+  init          Create solidity-argus config file
+  install       Configure argus plugin in opencode config
+  lint-skills   Validate SKILL.md files against schema
+  check-skills  Analyze skills for duplicates, near-duplicates, and conflicts
+`
 
 export class CliProgram {
-  private commands: Map<string, CliCommand> = new Map();
+  private commands: Map<string, CliCommand> = new Map()
 
   registerCommand(command: CliCommand): void {
-    this.commands.set(command.name, command);
+    this.commands.set(command.name, command)
   }
 
   async dispatch(args: string[]): Promise<number> {
-    const subcommand = args[0];
+    const subcommand = args[0]
 
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-      cliOutput.log(HELP_TEXT);
-      return 0;
+      cliOutput.log(HELP_TEXT)
+      return 0
     }
 
-    const command = this.commands.get(subcommand);
+    const command = this.commands.get(subcommand)
     if (!command) {
-      cliOutput.error(`Unknown command '${subcommand}'. Run 'argus' for help.`);
-      return 1;
+      cliOutput.error(`Unknown command '${subcommand}'. Run 'argus' for help.`)
+      return 1
     }
 
-    return command.execute(args.slice(1));
+    return command.execute(args.slice(1))
   }
 }
 
 export function createCliProgram(): CliProgram {
-  const program = new CliProgram();
-  program.registerCommand(doctorCommand);
-  program.registerCommand(initCommand);
-  program.registerCommand(installCommand);
-  program.registerCommand(lintSkillsCommand);
-  return program;
+  const program = new CliProgram()
+  program.registerCommand(doctorCommand)
+  program.registerCommand(initCommand)
+  program.registerCommand(installCommand)
+  program.registerCommand(lintSkillsCommand)
+  program.registerCommand(checkSkillsCommand)
+  return program
 }

package/src/cli/commands/check-skills.ts

@@ -0,0 +1,135 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { loadArgusConfig } from "../../config/loader"
+import { createLogger } from "../../shared/logger"
+import {
+  DEFAULT_GATE_CONFIG,
+  formatReportJson,
+  formatReportText,
+  type GateConfig,
+  generateReport,
+  type SkillReport,
+} from "../../skills/analysis/gates"
+import { normalizeSkill, type SkillDoc } from "../../skills/analysis/normalize"
+import { buildTfidfCorpus, computeAllPairs } from "../../skills/analysis/similarity"
+import { resolveSkillRoots } from "../../skills/argus-skill-resolver"
+import { cliOutput } from "../cli-output"
+import type { CliCommand } from "../types"
+
+const logger = createLogger()
+
+function findSkillFiles(dir: string, maxDepth = 8): string[] {
+  const files: string[] = []
+  const stack: Array<{ path: string; depth: number }> = [{ path: dir, depth: 0 }]
+
+  while (stack.length > 0) {
+    const current = stack.pop()
+    if (!current || current.depth > maxDepth) continue
+
+    try {
+      const entries = readdirSync(current.path, { withFileTypes: true })
+      for (const entry of entries) {
+        const fullPath = join(current.path, entry.name)
+        if (entry.isDirectory()) {
+          stack.push({ path: fullPath, depth: current.depth + 1 })
+        } else if (entry.isFile() && entry.name.toUpperCase() === "SKILL.MD") {
+          files.push(fullPath)
+        }
+      }
+    } catch {}
+  }
+
+  return files
+}
+
+function parseFormatArg(args: string[]): "text" | "json" {
+  const formatIdx = args.indexOf("--format")
+  if (formatIdx !== -1 && args[formatIdx + 1] === "json") {
+    return "json"
+  }
+  return "text"
+}
+
+function parseThresholdArg(args: string[], flag: string, fallback: number): number {
+  const idx = args.indexOf(flag)
+  if (idx === -1) return fallback
+  const raw = args[idx + 1]
+  if (!raw) return fallback
+  const parsed = Number.parseFloat(raw)
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback
+}
+
+export function loadAndNormalizeSkills(cwd: string): SkillDoc[] {
+  let config: ReturnType<typeof loadArgusConfig> | undefined
+  try {
+    config = loadArgusConfig(cwd)
+  } catch {
+    logger.debug("Config load failed, using defaults")
+  }
+
+  const roots = resolveSkillRoots(cwd, config)
+  const docs: SkillDoc[] = []
+
+  for (const root of roots) {
+    const files = findSkillFiles(root.path)
+    for (const file of files) {
+      try {
+        const content = readFileSync(file, "utf8")
+        const doc = normalizeSkill(content)
+        if (doc) {
+          docs.push(doc)
+        }
+      } catch {
+        logger.debug("Skipping unreadable skill file")
+      }
+    }
+  }
+
+  return docs
+}
+
+export function runAnalysis(docs: SkillDoc[], config: GateConfig): SkillReport {
+  const corpus = buildTfidfCorpus(docs)
+  const pairs = computeAllPairs(docs, corpus)
+  return generateReport(docs, pairs, config)
+}
+
+export const checkSkillsCommand: CliCommand = {
+  name: "check-skills",
+  description:
+    "Analyze SKILL.md files for duplicates, near-duplicates, and detection rule conflicts",
+  async execute(args: string[]): Promise<number> {
+    const cwd = process.cwd()
+    const format = parseFormatArg(args)
+
+    const gateConfig: GateConfig = {
+      blockThreshold: parseThresholdArg(
+        args,
+        "--block-threshold",
+        DEFAULT_GATE_CONFIG.blockThreshold,
+      ),
+      warnThreshold: parseThresholdArg(args, "--warn-threshold", DEFAULT_GATE_CONFIG.warnThreshold),
+      infoThreshold: parseThresholdArg(args, "--info-threshold", DEFAULT_GATE_CONFIG.infoThreshold),
+      blockExactRegexConflict: !args.includes("--no-regex-conflict"),
+    }
+
+    const docs = loadAndNormalizeSkills(cwd)
+
+    if (docs.length === 0) {
+      cliOutput.log("No SKILL.md files found.")
+      return 0
+    }
+
+    cliOutput.log(`Analyzing ${docs.length} skills...`)
+
+    const report = runAnalysis(docs, gateConfig)
+
+    if (format === "json") {
+      cliOutput.log(formatReportJson(report))
+    } else {
+      cliOutput.log(formatReportText(report))
+    }
+
+    return report.summary.block > 0 ? 1 : 0
+  },
+}