Install the aislop agent skill - Scanaislop Documentation

The aislop agent skill teaches coding agents how to use the CLI as a quality gate during their own work. It covers two jobs:

Prevention: avoid patterns that aislop flags before writing them.
Detection and fix: run a scoped scan after editing, auto-fix mechanical findings, verify the remaining findings against source, and only hand back work once the bar is met.

Install

npx skills add scanaislop/skills

That installs the aislop skill from the public scanaislop/skills repository. The live skills.sh listing is:

https://www.skills.sh/scanaislop/skills

The listing badge is:

[![skills.sh](https://skills.sh/b/scanaislop/skills)](https://skills.sh/scanaislop/skills)

Use npx skills add --help to see the installer options for global installs, per-agent installs, and dry runs.

Install options

Command	Use
`npx skills add scanaislop/skills`	Install every skill in the repository
`npx skills add scanaislop/skills -s aislop`	Install only the `aislop` skill
`npx skills add scanaislop/skills -a codex`	Install for a specific agent
`npx skills add scanaislop/skills -g`	Install at user scope when the installer supports it
`npx skills add scanaislop/skills --list`	Preview available skills before installing

Repository layout

The skills repo is intentionally small:

scanaislop/skills
|- README.md
|- CONTRIBUTING.md
`- skills/
   `- aislop/
      |- SKILL.md
      |- skill.json
      |- examples/
      |- references/
      `- evals/

skills/aislop/SKILL.md is the agent-facing procedure. skill.json is the registry manifest that skills.sh reads for metadata, examples, compatibility, keywords, and trigger prompts.

skills.sh metadata

The current manifest declares:

Field	Value
Skill name	`aislop`
Repository	`https://github.com/scanaislop/skills`
Entry file	`SKILL.md`
License	MIT
Compatibility	Claude Code, Codex, Cursor, Windsurf, Gemini CLI, VS Code, Amp, Aider, Warp, Goose, OpenCode, Antigravity, Deep Agents, Kimi, Cline
Examples	before commit, remaining findings, CI gate, clean-scan manual pass, agent handoff
Eval set	trigger accuracy for quality-related prompts and adjacent non-trigger prompts

What the skill tells the agent to do

Follow the project first

The agent matches the repository’s logger, error handling, naming, test style, and architecture instead of imposing a generic pattern.

Scan the changed files

After editing, the agent runs a scoped scan such as aislop scan --changes --json.

Auto-fix mechanical findings

The agent runs aislop fix for safe cleanup such as unused imports, duplicate imports, formatting, and narrative comments.

Fix the remaining findings with judgment

For non-mechanical findings, the agent opens the cited source line, confirms the issue is real, and applies a code change in the repository style.

Re-scan before finishing

The agent reports completion only after errors are resolved, fixable warnings are gone, and any intentional finding is clearly called out.

What it prevents

Category	Examples
AI-authored comments	Trivial comments, narrative comments, meta comments
Error handling drift	Swallowed exceptions, silent recovery, redundant try/catch
Type safety bypasses	`as any`, double assertions, untracked TypeScript directives
Dead code and duplication	Unused imports, duplicate imports, duplicate blocks, thin wrappers
Security risks	eval, innerHTML, shell/SQL injection, hardcoded secrets
Architecture drift	Import bans, layer rules, required patterns

How it relates to hooks and MCP

Integration	Best for
Agent skill	Teaches the agent the workflow and rule intent
Hooks	Force a scan after agent edits and feed findings back immediately
MCP Server	Expose `aislop_scan`, `aislop_fix`, `aislop_why`, and `aislop_baseline` as tools
Agent command	Run a local repair loop with Codex, Claude Code, or OpenCode

You can use all of them together. The skill provides the operating procedure, hooks provide automatic per-edit feedback, and MCP gives the agent callable tools.

Example flows included in the skill

The skill repo ships example conversations so agents and maintainers can see the expected behavior end to end:

Example	Scenario
`01-before-commit`	Agent finishes a small feature, scans changed files, fixes findings, and reports score before commit
`02-remaining-findings`	`aislop fix` resolves mechanical issues, then the agent handles non-mechanical findings manually
`03-ci-gate`	Agent adds a GitHub Actions quality gate with `ci.failBelow`
`04-green-scan-manual-pass`	Scan is clean, but the agent still catches semantic slop in its manual pass
`05-agent-handoff`	Large PR cleanup using `aislop fix --claude` for high-volume remaining findings

Contributing to the skill

Skill changes belong in scanaislop/skills, not the CLI repo. Each skill must ship:

SKILL.md with name and description frontmatter.
skill.json with registry metadata and examples.
At least one realistic example under examples/.
Updated evals when trigger behavior changes.

Version skill.json with semver: patch for typos, minor for new sections or examples, and major for breaking changes to the skill interface.

​Install

​Install options

​Repository layout

​skills.sh metadata

​What the skill tells the agent to do

​What it prevents

​How it relates to hooks and MCP

​Example flows included in the skill

​Contributing to the skill