Skip to content

Rules Reference

skillsaw includes 101 built-in rules organized into the following categories:

All Rules

Rule ID Description Default Severity Autofix Category
agent-plugin-json-valid Agent Plugins plugin.json and skills location must conform to a supported schema error (auto) - Agent Plugins
agent-plugin-mcp-valid Agent Plugins mcp.json must conform to a supported schema and semantics error (auto) - Agent Plugins
agent-plugin-required Plugins must also be available as vendor-neutral Agent Plugins v1 packages, with shared manifest metadata in sync warning (disabled) auto Agent Plugins
agentskill-valid SKILL.md must have valid frontmatter with name and description error (auto) auto agentskills.io
agentskill-name Skill name must be lowercase letters, numbers, and hyphens and match directory name error (auto) auto agentskills.io
agentskill-rename-refs Update stale skill name references after a rename warning (auto) auto agentskills.io
agentskill-description Skill description should be meaningful and within length limits warning (auto) - agentskills.io
agentskill-structure Skill directories should only contain recognized subdirectories (stricter than spec) warning (disabled) - agentskills.io
agentskill-evals Validate evals/evals.json format when present warning (auto) - agentskills.io
agentskill-evals-required Require evals/evals.json for each skill (opt-in) warning (disabled) - agentskills.io
agentskill-unreferenced-files Every bundled skill file should be referenced from SKILL.md, directly or transitively warning (auto) - agentskills.io
apm-yaml-valid apm.yml must exist with valid YAML and required fields (name, version) error (auto) - APM (Agent Package Manager)
apm-structure-valid .apm/ directory must contain a recognized primitive subdirectory with valid structure warning (auto) - APM (Agent Package Manager)
claude-plugin-json-required Plugin must have .claude-plugin/plugin.json error (auto) - Claude Code
claude-plugin-json-valid plugin.json must be valid JSON with required fields error (auto) - Claude Code
claude-plugin-naming Plugin names should use kebab-case warning (auto) - Claude Code
claude-plugin-readme Plugin should have a README.md file warning (auto) - Claude Code
claude-command-naming Command files should use kebab-case naming warning auto Claude Code
claude-command-frontmatter Command files must have valid frontmatter with description error auto Claude Code
claude-command-sections Command files should have Name, Synopsis, Description, and Implementation sections warning (disabled) - Claude Code
claude-command-name-format Command Name section should be 'plugin-name:command-name' warning (disabled) - Claude Code
claude-agent-frontmatter Agent files must have valid frontmatter with name and description error auto Claude Code
claude-marketplace-json-valid Marketplace.json must be valid JSON with required fields error (auto) - Claude Code
claude-marketplace-registration Plugins must be registered in marketplace.json error (auto) auto Claude Code
claude-settings-dangerous 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.) error (auto) - Claude Code
claude-rules-valid .claude/rules/ files must be markdown with valid optional paths frontmatter error (auto) - Claude Code
coderabbit-yaml-valid .coderabbit.yaml must be valid YAML error (auto) - CodeRabbit
coderabbit-schema-valid .coderabbit.yaml keys and enums should match the CodeRabbit schema warning (auto) - CodeRabbit
content-weak-language Detect hedging, vague, and non-actionable language in instruction files info (auto) - Content Intelligence
content-tautological Detect tautological instructions that the model already follows by default info (auto) - Content Intelligence
content-description-routing Skill and agent descriptions should guide routing; command descriptions should clearly explain their purpose warning (auto) - Content Intelligence
content-redundant-with-tooling Detect instructions that duplicate .editorconfig, ESLint, Prettier, or tsconfig settings warning (auto) - Content Intelligence
content-instruction-budget Check if instruction count in a file exceeds LLM instruction budget (~150) warning (auto) - Content Intelligence
content-negative-only Detect prohibitions without a positive alternative (agent has no path forward) info (auto) - Content Intelligence
content-section-length Warn about markdown sections longer than ~500 tokens info (auto) - Content Intelligence
content-contradiction Detect likely contradictions within instruction files using keyword-pair heuristics warning (auto) - Content Intelligence
content-hook-candidate Detect instructions that should be automated as hooks instead of prose instructions info (auto) - Content Intelligence
content-cognitive-chunks Check that instruction files are organized into cognitive chunks with headings info (auto) - Content Intelligence
content-embedded-secrets Detect potential API keys, tokens, and passwords in instruction files error (auto) - Content Intelligence
content-banned-references Detect banned or deprecated model names, APIs, and custom patterns warning (auto) - Content Intelligence
content-inconsistent-terminology Detect inconsistent terminology across instruction files (e.g., mixing 'directory' and 'folder') info (auto) - Content Intelligence
content-instruction-drift Detect near-duplicate sections that have drifted apart across instruction files info (auto) - Content Intelligence
content-broken-internal-reference Detect markdown links where the target file does not exist warning (auto) auto Content Intelligence
content-unlinked-internal-reference Detect bare path-like strings not wrapped in markdown link syntax info (auto) auto Content Intelligence
content-placeholder-text Detect TODO markers, bracket placeholders, and unfilled template text warning (auto) - Content Intelligence
content-unclosed-fence Detect code fences opened but never closed, hiding the rest of the file from content rules warning (auto) auto Content Intelligence
content-repeated-directive Detect the same directive stated more than once within a file info (auto) - Content Intelligence
content-emphasis-density Detect emphasis inflation: too many ALWAYS/NEVER/MUST/IMPORTANT directives per file warning (auto) - Content Intelligence
content-missing-stop-condition Detect open-ended loop instructions (keep monitoring, poll, retry) without a stopping condition warning (disabled) - Content Intelligence
content-inline-tool-examples Detect consecutive code-block examples that all invoke the same tool info (disabled) - Content Intelligence
content-progressive-disclosure Large skills and instruction files should use progressive disclosure: split detail into referenced files that load on demand warning (auto) - Content Intelligence
content-mcp-tool-name Detect fully-qualified MCP tool names in portable prose that should use the short tool name warning (disabled) auto Content Intelligence
context-budget Warn when instruction or config files exceed recommended token limits warning (auto) - Context Budget
copilot-agent-valid Copilot and VS Code custom agents must use target-compatible frontmatter error (auto) - Copilot / VS Code
cursor-rules-valid Cursor .mdc rules must have frontmatter that lets the rule activate error (auto) auto Cursor
cursor-hooks-valid .cursor/hooks.json must declare version 1 and known hook events with commands error (auto) - Cursor
devin-rules-valid Devin workspace rules must have valid activation frontmatter and fit its size limit error (auto) - Devin
devin-skill-valid Devin-native SKILL.md frontmatter must use Devin's documented field shapes error (auto) - Devin
antigravity-config-json-valid Antigravity registry files must decode their paths and filters correctly error (disabled) - Google Antigravity
antigravity-hooks-valid hooks.json must use Antigravity's hook events, handler types and fields error (auto) - Google Antigravity
antigravity-mcp-valid mcp_config.json must parse and declare servers Antigravity can load error (auto) - Google Antigravity
antigravity-plugin-json-valid plugin.json must parse as an Antigravity manifest with correctly typed fields error (auto) - Google Antigravity
grok-agent-valid .grok/agents/*.md must declare a name and a description in frontmatter error (auto) - Grok Build
grok-config-project-scope .grok/config.toml must only carry settings a project file contributes warning (auto) - Grok Build
grok-config-valid .grok/config.toml must parse, and its servers and permissions must load error (auto) - Grok Build
grok-hooks-valid .grok/hooks/*.json must use Grok's hook events, handler types and fields error (auto) - Grok Build
grok-marketplace-index-parity plugin-index.json must agree with its marketplace catalog warning (auto) - Grok Build
grok-marketplace-json-valid .grok-plugin/marketplace.json must be valid JSON with installable entries error (auto) - Grok Build
grok-plugin-json-valid .grok-plugin/plugin.json must be valid JSON with a name Grok's loader accepts error (auto) - Grok Build
grok-plugin-structure A Grok plugin directory needs a manifest or a component Grok installs warning (auto) - Grok Build
claude-hooks-valid Claude Code hooks.json must be valid JSON with proper hook configuration structure error - Hooks
hooks-dangerous Flags hook commands that chain a download into execution (curl|sh), obfuscate their payload (eval/base64), or perform network requests error (auto) - Hooks
hooks-prohibited All hooks are prohibited unless explicitly allowlisted; catches new or unexpected hooks added to a project error (disabled) - Hooks
instruction-file-valid Instruction files (AGENTS.md and tool-compatible alternatives) must be valid and non-empty warning (auto) - Instruction Files
instruction-imports-valid Import references (@path) in AGENTS.md, CLAUDE.md, GEMINI.md and QWEN.md must point to existing files warning (auto) - Instruction Files
claude-md-agents-import CLAUDE.md next to an AGENTS.md should import it so both assistants read one source of truth info (auto) auto Instruction Files
mcp-valid-json MCP configuration must use valid syntax and a host-readable server structure error - MCP (Model Context Protocol)
mcp-prohibited Repository should not enable non-allowlisted MCP servers error (disabled) - MCP (Model Context Protocol)
mcp-registry-server-json-valid MCP Registry server.json must conform to a supported schema and its enums error (auto) - MCP (Model Context Protocol)
mcp-registry-version-semver MCP Registry server versions should use strict Semantic Versioning 2.0.0 warning (auto) - MCP (Model Context Protocol)
mcp-registry-npm-name-match Local npm package.json mcpName must match MCP Registry server.json name error (auto) - MCP (Model Context Protocol)
muse-hooks-valid .muse/hooks.json must use Muse's events, matcher groups and handler fields error (disabled) - Muse Code
codex-hooks-valid Codex hooks files must use Codex's hook events, handler types, and fields error (auto) - OpenAI Codex
codex-openai-metadata Validate skill openai.yaml and catalog-compatible plugin metadata error (auto) - OpenAI Codex
codex-plugin-json-valid .codex-plugin/plugin.json must be valid JSON with required fields error (auto) - OpenAI Codex
codex-plugin-structure Only plugin.json belongs in .codex-plugin/ warning (auto) - OpenAI Codex
codex-marketplace-json-valid .agents/plugins/marketplace.json must be valid JSON with required fields error (auto) - OpenAI Codex
codex-marketplace-registration Codex plugins must be registered in .agents/plugins/marketplace.json error (auto) auto OpenAI Codex
openclaw-metadata Validate metadata.openclaw fields against the OpenClaw spec warning (auto) - OpenClaw
opencode-config-valid opencode.json and opencode.jsonc must parse and use keys and MCP server shapes OpenCode reads error (auto) - OpenCode
promptfoo-valid Validate promptfoo eval YAML config structure and file references error (auto) - Promptfoo Evals
promptfoo-assertions Require specific assertion types in all promptfoo eval tests warning (disabled) - Promptfoo Evals
promptfoo-metadata Require specific metadata keys on all promptfoo eval tests warning (disabled) - Promptfoo Evals
security-invisible-unicode Detect invisible or reordering unicode characters (ASCII smuggling, Trojan Source) in agent context error (auto) - Security
security-hidden-instructions Detect agent directives hidden in HTML comments or Markdown link labels invisible to human review warning (auto) - Security
security-encoded-payload Detect long high-entropy base64/hex blobs that can smuggle encoded payloads warning (auto) - Security
security-dynamic-context Require an allowlist for dynamic context commands that execute shell code while loading agent context warning (auto) - Security
skills-lock-valid skills-lock.json files must be valid and portable project lockfiles error (auto) - Vercel
content-critical-position Detect critical instructions in the middle of files where LLM attention is lowest info (deprecated) - Deprecated
content-actionability-score Score instruction files on actionability (verb density, commands, file references) info (deprecated) - Deprecated
skill-frontmatter SKILL.md files should have frontmatter with name and description warning (deprecated) auto Deprecated