Skip to content

SKILL.md

Latest commit

 

History

History
244 lines (177 loc) · 5.03 KB

SKILL.md

File metadata and controls

244 lines (177 loc) · 5.03 KB
Raw
Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column 261
---
name: slop-detector
description: Structural review skill for AI-SLOP Detector. Use when asked to review AI-assisted code, inspect changed-code risk, prioritize structural hotspots, plan cleanup, verify governance, or run MCP/JSON-first workflows. Prefer the canonical CLI surfaces: scan, review, pulse, sweep, explain, verify-governance, and mcp. Treat review/pulse/sweep as the primary agent-facing surfaces; use scan for full baseline analysis.
---

AI-SLOP Detector Skill

Use AI-SLOP Detector as a structured review loop, not as a last-minute lint step.

The preferred flow is:

  1. generate or edit code
  2. run a structured review in JSON
  3. inspect evidence and action classes
  4. apply only bounded fixes
  5. re-run review / health / cleanup
  6. hand the result to a human with evidence

Install

Python core:

pip install ai-slop-detector
pip install "ai-slop-detector[js]"   # optional JS/TS support
pip install "ai-slop-detector[go]"   # optional Go support

Optional Node-first wrapper:

npm install --save-dev ai-slop-detector

Verify:

slop-detector --version
npx ai-slop-detector --version

Command Selection

Use the smallest surface that matches the job.

scan

slop-detector scan . --format json

Use when you need:

  • full single-file or project analysis
  • baseline structural metrics
  • complete pattern output

Before acting on a project scan, inspect:

  • finding_summary for total and severity counts
  • scan_coverage for analyzed, excluded, and unsupported files
  • ml_scoring for the optional ML capability state

review

slop-detector review . --format json

Use when you need:

  • changed-code review
  • introduced vs inherited attribution
  • build/pass-fail guidance

Inspect first:

  • verdict
  • should_fail_build
  • attribution
  • targets
  • actions
  • findings

pulse

slop-detector pulse . --format json

Use when you need:

  • health summary
  • hotspot prioritization
  • next repair order

Inspect first:

  • summary
  • targets
  • signals

sweep <family>

slop-detector sweep dead-code . --format json
slop-detector sweep dupes . --format json
slop-detector sweep unused-deps . --format json
slop-detector sweep stale-suppressions . --format json
slop-detector sweep boundary-violations . --format json

Use when you need cleanup planning with:

  • issues
  • confidence
  • action_class
  • evidence

explain

slop-detector explain empty_except --format json

Use when you need mitigation guidance for a pattern or finding.

verify-governance

slop-detector verify-governance ./.cr-ep

Use when governance artifacts, not score output, are the enforcement boundary.

mcp

slop-detector mcp

Use when the host tool already speaks MCP and wants the structured tool surface directly.

Recommended Agent Loop

1. Run changed-code review first

slop-detector review . --format json

If the task is PR-like or patch-like, this is the default entry point.

2. Inspect only bounded evidence

Safe agent targets:

  • unused imports
  • obvious duplicate functions
  • placeholder branches
  • stale suppressions

Unsafe without human confirmation:

  • deleting needs_review cleanup findings automatically
  • changing architecture boundaries
  • removing high-churn files solely from cleanup heuristics
  • treating clean as proof that no findings exist or all files were analyzed
  • treating an unavailable ML capability as a passing ML signal

Use --include-tests only when test-file findings are in scope. It includes built-in test-file exclusions only; configured ignores and artifacts remain excluded.

3. Use cleanup families intentionally

If review points at a cleanup class, run the narrow family:

slop-detector sweep dupes . --format json
slop-detector sweep dead-code . --format json
slop-detector sweep unused-deps . --format json

Do not treat confidence as permission. It is prioritization guidance.

4. Re-run health after edits

slop-detector pulse . --format json

Confirm that the hotspot moved, the score improved, or the finding count dropped.

5. Escalate with evidence

Human handoff should include:

  • what changed
  • what command was run
  • what verdict / score / issue count changed
  • what remains unfixed
  • what the agent deliberately did not change

Programmatic Node Surface

import {
  scanProject,
  reviewChanges,
  computeHealth,
  runCleanupFamily,
} from "ai-slop-detector";

Typed contracts:

import type {
  ScanOutput,
  ReviewOutput,
  HealthOutput,
  CleanupOutput,
} from "ai-slop-detector/types";

Legacy Note

Older skill revisions used a /slop, /slop-file, /slop-gate, /slop-delta, and /slop-spar framing. Those names are historical. Prefer the canonical product surfaces:

  • scan
  • review
  • pulse
  • sweep
  • explain
  • verify-governance
  • mcp

If a host environment adds slash aliases, they should delegate to those canonical commands rather than documenting a separate behavior model.