# skillsaw

> A configurable linter for agent skills, plugins, and AI coding assistant context.

skillsaw lints the files that steer AI coding agents: skills, plugins,
CLAUDE.md/AGENTS.md instruction files, hooks, and agent configuration.
Run it with `uvx skillsaw` (or `pip install skillsaw`); configure it
with a `.skillsaw.yaml` at the repository root. The complete
documentation is also served as one file: https://skillsaw.org/llms-full.txt.

## Docs

- [Home](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/index.md): project homepage (HTML-heavy hero page)
- [Getting Started](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/getting-started.md): install skillsaw and run your first lint
- [Autofixing](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/autofixing.md): how deterministic autofixes work and when they apply
- [Porting to Agent Plugins](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/porting.md): convert Claude Code and Codex plugins to Agent Plugins v1
- [Baseline](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/baseline.md): adopt skillsaw gradually by baselining existing violations
- [Configuration](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/configuration.md): the .skillsaw.yaml file: rules, severities, exclusions, suppression
- [Repository Types](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/repo-types.md): how skillsaw detects what it is linting
- [CI Integration](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/ci.md): GitHub Actions, GitLab CI, and PR review comments
- [Pre-commit](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/pre-commit.md): run skillsaw as a pre-commit hook
- [CLI Reference](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/cli.md): every command and flag
- [Custom Rules](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/custom-rules.md): write project-local rules in Python
- [Rule Plugins](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/plugins.md): install and publish pip-distributed rule packages
- [Scaffolding](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/scaffolding.md): generate plugins, skills, commands, agents, and hooks
- [Lint Tree](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/lint-tree.md): the typed node tree rules use for discovery
- [Supply Chain Protection](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/supply-chain-protection.md): the security model and dangerous-configuration rules
- [Research](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/research.md): the research basis behind the content intelligence rules

## Rules

- [Rules Reference](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/index.md): overview table of all 79 built-in rules
- [agentskills.io](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskills.md): 8 rules — These rules validate skills against the agentskills.io specification.
- [Agent Plugins](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agent-plugins.md): 3 rules — Validates portable plugin packages against the Agent Plugins v1 specification.
- [Claude Code](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude.md): 13 rules — Validates the Claude Code formats: plugin manifests (`.claude-plugin/plugin.json`), `marketplace.json` catalogs, command and agent frontmatter, `.claude/settings.json` security, and `.claude/rules/` files.
- [OpenAI Codex](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex.md): 5 rules — Validates OpenAI's optional skill metadata in `agents/openai.yaml`, plus Codex plugins and marketplaces against the Codex plugin specification.
- [Hooks](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/hooks.md): 3 rules — Validates hook configuration.
- [Security](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/security.md): 4 rules — Content-validation rules that catch payloads and instructions invisible to human review: invisible/bidi unicode smuggling (ASCII smuggling, Trojan Source), agent directives hidden in HTML comments or Markdown link labels, and long high-entropy base64/hex blobs that can smuggle encoded payloads, plus unallowlisted dynamic-context commands in agent content.
- [MCP (Model Context Protocol)](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/mcp.md): 2 rules
- [OpenClaw](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/openclaw.md): 1 rule — Validates `metadata.openclaw` in SKILL.md frontmatter against the OpenClaw spec.
- [Cursor](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/cursor.md): 2 rules — Validates Cursor's repository-shipped configuration under every `.cursor/` directory in the repository, the root one and any in a monorepo subpackage: `rules/**/*.mdc` frontmatter (the fields that decide whether a rule ever activates) and `.cursor/hooks.json` structure.
- [Instruction Files](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/instruction-files.md): 3 rules — Validates AI coding assistant instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, QWEN.md) at the repository root.
- [Context Budget](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/context-budget.md): 1 rule — Warns when instruction and configuration files exceed recommended token limits.
- [Content Intelligence](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-intelligence.md): 24 rules — Rules that go beyond structural validation to analyze the *quality* of instruction files.
- [CodeRabbit](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/coderabbit.md): 2 rules — Validates `.coderabbit.yaml` config files for YAML syntax and, via `coderabbit-schema-valid`, near-miss unknown top-level keys and the `reviews.profile` enum against the CodeRabbit schema.
- [Promptfoo Evals](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/promptfoo.md): 3 rules — Validates promptfoo eval YAML configs found in `evals/` directories of plugins and skills.
- [APM (Agent Package Manager)](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/apm.md): 2 rules — Validates repositories using the APM directory layout (`.apm/`).
- [Deprecated](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/deprecated.md): 3 rules — These rules are deprecated and will be removed in a future release.

## Optional

- [agentskill-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-valid.md): SKILL.md must have valid frontmatter with name and description
- [agentskill-name](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-name.md): Skill name must be lowercase letters, numbers, and hyphens and match directory name
- [agentskill-rename-refs](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-rename-refs.md): Update stale skill name references after a rename
- [agentskill-description](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-description.md): Skill description should be meaningful and within length limits
- [agentskill-structure](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-structure.md): Skill directories should only contain recognized subdirectories (stricter than spec)
- [agentskill-evals](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-evals.md): Validate evals/evals.json format when present
- [agentskill-evals-required](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-evals-required.md): Require evals/evals.json for each skill (opt-in)
- [agentskill-unreferenced-files](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agentskill-unreferenced-files.md): Every bundled skill file should be referenced from SKILL.md, directly or transitively
- [agent-plugin-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agent-plugin-json-valid.md): Agent Plugins plugin.json and skills location must conform to a supported schema
- [agent-plugin-mcp-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agent-plugin-mcp-valid.md): Agent Plugins mcp.json must conform to a supported schema and semantics
- [agent-plugin-required](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/agent-plugin-required.md): Plugins must also be available as vendor-neutral Agent Plugins v1 packages, with shared manifest metadata in sync
- [claude-plugin-json-required](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-plugin-json-required.md): Plugin must have .claude-plugin/plugin.json
- [claude-plugin-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-plugin-json-valid.md): plugin.json must be valid JSON with required fields
- [claude-plugin-naming](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-plugin-naming.md): Plugin names should use kebab-case
- [claude-plugin-readme](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-plugin-readme.md): Plugin should have a README.md file
- [claude-command-naming](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-command-naming.md): Command files should use kebab-case naming
- [claude-command-frontmatter](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-command-frontmatter.md): Command files must have valid frontmatter with description
- [claude-command-sections](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-command-sections.md): Command files should have Name, Synopsis, Description, and Implementation sections
- [claude-command-name-format](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-command-name-format.md): Command Name section should be 'plugin-name:command-name'
- [claude-agent-frontmatter](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-agent-frontmatter.md): Agent files must have valid frontmatter with name and description
- [claude-marketplace-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-marketplace-json-valid.md): Marketplace.json must be valid JSON with required fields
- [claude-marketplace-registration](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-marketplace-registration.md): Plugins must be registered in marketplace.json
- [claude-settings-dangerous](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-settings-dangerous.md): Flags settings keys that execute arbitrary commands (apiKeyHelper, awsAuthRefresh, awsCredentialExport, gcpAuthRefresh, otelHeadersHelper) and dangerous env vars (LD_PRELOAD, NODE_OPTIONS, proxy settings, GIT_SSH_COMMAND, etc.)
- [claude-rules-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-rules-valid.md): .claude/rules/ files must be markdown with valid optional paths frontmatter
- [codex-openai-metadata](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex-openai-metadata.md): Validate skill openai.yaml and catalog-compatible plugin metadata
- [codex-plugin-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex-plugin-json-valid.md): .codex-plugin/plugin.json must be valid JSON with required fields
- [codex-plugin-structure](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex-plugin-structure.md): Only plugin.json belongs in .codex-plugin/
- [codex-marketplace-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex-marketplace-json-valid.md): .agents/plugins/marketplace.json must be valid JSON with required fields
- [codex-marketplace-registration](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/codex-marketplace-registration.md): Codex plugins must be registered in .agents/plugins/marketplace.json
- [hooks-json-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/hooks-json-valid.md): hooks.json must be valid JSON with proper hook configuration structure
- [hooks-dangerous](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/hooks-dangerous.md): Flags hook commands that execute scripts from dotfile directories, download-and-execute chains (curl|sh), obfuscation (eval/base64), or perform network requests
- [hooks-prohibited](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/hooks-prohibited.md): All hook commands are prohibited unless explicitly allowlisted; catches new or unexpected hooks added to a project
- [security-invisible-unicode](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/security-invisible-unicode.md): Detect invisible or reordering unicode characters (ASCII smuggling, Trojan Source) in agent context
- [security-hidden-instructions](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/security-hidden-instructions.md): Detect agent directives hidden in HTML comments or Markdown link labels invisible to human review
- [security-encoded-payload](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/security-encoded-payload.md): Detect long high-entropy base64/hex blobs that can smuggle encoded payloads
- [security-dynamic-context](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/security-dynamic-context.md): Require an allowlist for dynamic context commands that execute shell code while loading agent context
- [mcp-valid-json](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/mcp-valid-json.md): MCP configuration must be valid JSON with proper mcpServers structure
- [mcp-prohibited](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/mcp-prohibited.md): Repository should not enable non-allowlisted MCP servers
- [openclaw-metadata](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/openclaw-metadata.md): Validate metadata.openclaw fields against the OpenClaw spec
- [cursor-rules-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/cursor-rules-valid.md): Cursor .mdc rules must have frontmatter that lets the rule activate
- [cursor-hooks-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/cursor-hooks-valid.md): .cursor/hooks.json must declare version 1 and known hook events with commands
- [instruction-file-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/instruction-file-valid.md): Instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, QWEN.md) must be valid and non-empty
- [instruction-imports-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/instruction-imports-valid.md): Import references (@path) in AGENTS.md, CLAUDE.md, GEMINI.md and QWEN.md must point to existing files
- [claude-md-agents-import](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/claude-md-agents-import.md): CLAUDE.md next to an AGENTS.md should be the single line '@AGENTS.md' so both assistants read one source of truth
- [content-weak-language](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-weak-language.md): Detect hedging, vague, and non-actionable language in instruction files
- [content-tautological](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-tautological.md): Detect tautological instructions that the model already follows by default
- [content-description-routing](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-description-routing.md): Skill and agent descriptions should guide routing; command descriptions should clearly explain their purpose
- [content-redundant-with-tooling](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-redundant-with-tooling.md): Detect instructions that duplicate .editorconfig, ESLint, Prettier, or tsconfig settings
- [content-instruction-budget](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-instruction-budget.md): Check if instruction count in a file exceeds LLM instruction budget (~150)
- [content-negative-only](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-negative-only.md): Detect prohibitions without a positive alternative (agent has no path forward)
- [content-section-length](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-section-length.md): Warn about markdown sections longer than ~500 tokens
- [content-contradiction](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-contradiction.md): Detect likely contradictions within instruction files using keyword-pair heuristics
- [content-hook-candidate](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-hook-candidate.md): Detect instructions that should be automated as hooks instead of prose instructions
- [content-cognitive-chunks](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-cognitive-chunks.md): Check that instruction files are organized into cognitive chunks with headings
- [content-embedded-secrets](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-embedded-secrets.md): Detect potential API keys, tokens, and passwords in instruction files
- [content-banned-references](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-banned-references.md): Detect banned or deprecated model names, APIs, and custom patterns
- [content-inconsistent-terminology](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-inconsistent-terminology.md): Detect inconsistent terminology across instruction files (e.g., mixing 'directory' and 'folder')
- [content-instruction-drift](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-instruction-drift.md): Detect near-duplicate sections that have drifted apart across instruction files
- [content-broken-internal-reference](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-broken-internal-reference.md): Detect markdown links where the target file does not exist
- [content-unlinked-internal-reference](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-unlinked-internal-reference.md): Detect bare path-like strings not wrapped in markdown link syntax
- [content-placeholder-text](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-placeholder-text.md): Detect TODO markers, bracket placeholders, and unfilled template text
- [content-unclosed-fence](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-unclosed-fence.md): Detect code fences opened but never closed, hiding the rest of the file from content rules
- [content-repeated-directive](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-repeated-directive.md): Detect the same directive stated more than once within a file
- [content-emphasis-density](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-emphasis-density.md): Detect emphasis inflation: too many ALWAYS/NEVER/MUST/IMPORTANT directives per file
- [content-missing-stop-condition](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-missing-stop-condition.md): Detect open-ended loop instructions (keep monitoring, poll, retry) without a stopping condition
- [content-inline-tool-examples](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-inline-tool-examples.md): Detect consecutive code-block examples that all invoke the same tool
- [content-progressive-disclosure](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-progressive-disclosure.md): Large skills and instruction files should use progressive disclosure: split detail into referenced files that load on demand
- [content-mcp-tool-name](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-mcp-tool-name.md): Detect fully-qualified MCP tool names that should use the short tool name
- [coderabbit-yaml-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/coderabbit-yaml-valid.md): .coderabbit.yaml must be valid YAML
- [coderabbit-schema-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/coderabbit-schema-valid.md): .coderabbit.yaml keys and enums should match the CodeRabbit schema
- [promptfoo-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/promptfoo-valid.md): Validate promptfoo eval YAML config structure and file references
- [promptfoo-assertions](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/promptfoo-assertions.md): Require specific assertion types in all promptfoo eval tests
- [promptfoo-metadata](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/promptfoo-metadata.md): Require specific metadata keys on all promptfoo eval tests
- [apm-yaml-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/apm-yaml-valid.md): apm.yml must exist with valid YAML and required fields (name, version)
- [apm-structure-valid](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/apm-structure-valid.md): .apm/ directory must contain a recognized primitive subdirectory with valid structure
- [content-critical-position](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-critical-position.md): Detect critical instructions in the middle of files where LLM attention is lowest (deprecated since v0.18.0)
- [content-actionability-score](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/content-actionability-score.md): Score instruction files on actionability (verb density, commands, file references) (deprecated since v0.18.0)
- [skill-frontmatter](https://raw.githubusercontent.com/stbenjam/skillsaw/main/docs/rules/skill-frontmatter.md): SKILL.md files should have frontmatter with name and description (deprecated since v0.18.0)