Documentation

aislop agent skill.

One command (npx skills add scanaislop/aislop-skill) installs to every coding agent on your machine. The skill teaches the agent the anti-patterns to avoid while writing, in your project's style rather than a generic one, and catches anything that slips through with a scan plus in-session fix before the reply hits you.

Two jobs: prevention and detection

1. Prevention

Teaches the agent the patterns to avoid while writing: no narrative comments, no unsafe any-typed casts, no swallowed errors, no template-string SQL, no duplicate logic, no dead exports, no generic names. First-draft output passes aislop, not just the rewritten second draft.

2. Detection + fix

After edits, the agent runs the scoped scan, verifies each finding against the source, fixes the non-mechanical ones in-session with its editing tools, and surfaces only what needs your decision. Never dumps raw findings at you.

Running aislop manually between edits is friction. A skill solves that: it teaches the agent how to write, when to scan, how to interpret findings, what to auto-fix, and how to structure the reply when something needs judgment.

What it enforces

The skill makes the agent responsible for a broader bar than plain lint:

Quality gate

Pre-commit, pre-PR, pre-merge, agent-turn-end. One score per run.

Deduplication

Duplicate logic and copy-paste across files; nudges toward shared helpers.

Reusability

Unused exports, unused files, code that should be extracted.

Maintainability

Function and file size, cyclomatic complexity, nesting depth, parameter lists.

AI-authored patterns

Narrative comments, unsafe any casts, swallowed errors, TODO stubs, generic names, console leftovers.

Security

Dangerous runtime calls, template-string SQL, innerHTML, hardcoded secrets, vulnerable dependencies.

Architecture

Project-specific rules: import layering, banned deps, module boundaries.

Agent handoff

One flag passes structured context to any of 14 supported agents.

Install

One command installs the skill to every coding agent on your machine. Verified on Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Cline, VS Code, Amp, Aider, Warp, Goose, OpenCode, Antigravity, Deep Agents, and Kimi, plus 30+ others supported by the skills.sh ecosystem.

$ npx skills add scanaislop/aislop-skill

Scope with -g for global install, -a <agent> for a specific agent, --list to preview. See npx skills add --help for the full option set.

Follows your project's conventions

The skill tells the agent which anti-patterns to avoid. It does not tell it the one right way to structure code. That's your project's decision. The agent is instructed to match your existing logger, error class, naming scheme, test style, and architecture rather than impose generic ones.

And if a convention is missing, the agent invents one that fits and tells you. It doesn't stop to ask. Default voice is "I did X" not "should I do X?". Escalation is reserved for genuine product-level choices.

What the agent does once installed

1. Before writing, the agent internalises the prevention patterns: no narrative comments, no unsafe any casts, no swallowed errors, no duplicate logic, no generic names.
2. After editing code, runs npx aislop scan --changes --json to see only what it touched.
3. Runs npx aislop fix to resolve the mechanical findings.
4. For each remaining finding, reads the file at the cited line, verifies the issue is real (not a false positive), then fixes it in-session using its editing tools.
5. Re-scans. Only reports "done" when the bar is met: no errors, no unaddressed fixable warnings.

Registries

Listed on skill registries that index public GitHub repos. Point your registry at github.com/scanaislop/aislop-skill. The repo ships SKILL.md, skill.json, README.md, and three examples.