Skip to content

Rules Reference

skillsaw includes 59 builtin rules organized into the following categories:

All Rules

Rule ID Description Default Severity Autofix Category
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
plugin-json-required Plugin must have .claude-plugin/plugin.json error (auto) - Plugin Structure
plugin-json-valid plugin.json must be valid JSON with required fields error (auto) - Plugin Structure
plugin-naming Plugin names should use kebab-case warning (auto) - Plugin Structure
plugin-readme Plugin should have a README.md file warning (auto) - Plugin Structure
command-naming Command files should use kebab-case naming warning auto Command Format
command-frontmatter Command files must have valid frontmatter with description error auto Command Format
command-sections Command files should have Name, Synopsis, Description, and Implementation sections warning (disabled) - Command Format
command-name-format Command Name section should be 'plugin-name:command-name' warning (disabled) - Command Format
marketplace-json-valid Marketplace.json must be valid JSON with required fields error (auto) - Marketplace
marketplace-registration Plugins must be registered in marketplace.json error (auto) auto Marketplace
skill-frontmatter SKILL.md files should have frontmatter with name and description warning auto Skills, Agents, Hooks
agent-frontmatter Agent files must have valid frontmatter with name and description error auto Skills, Agents, Hooks
hooks-json-valid hooks.json must be valid JSON with proper hook configuration structure error - Skills, Agents, Hooks
hooks-dangerous Flags hook commands that execute scripts from dotfile directories, download-and-execute chains (curl|sh), obfuscation (eval/base64), or perform network requests error (auto) - Skills, Agents, Hooks
hooks-prohibited All hook commands are prohibited unless explicitly allowlisted; catches new or unexpected hooks added to a project error (disabled) - Skills, Agents, Hooks
mcp-valid-json MCP configuration must be valid JSON with proper mcpServers structure error - MCP (Model Context Protocol)
mcp-prohibited Repository should not enable non-allowlisted MCP servers error (disabled) - MCP (Model Context Protocol)
rules-valid .claude/rules/ files must be markdown with valid optional paths frontmatter error (auto) - Rules Directory
openclaw-metadata Validate metadata.openclaw fields against the OpenClaw spec warning (auto) - OpenClaw
instruction-file-valid Instruction files (AGENTS.md, CLAUDE.md, GEMINI.md) must be valid and non-empty warning (auto) - Instruction Files
instruction-imports-valid Import references (@path) in AGENTS.md, CLAUDE.md, and GEMINI.md must point to existing files warning (auto) - Instruction Files
context-budget Warn when instruction or config files exceed recommended token limits warning (auto) - Context Budget
content-weak-language Detect hedging, vague, and non-actionable language in instruction files warning (auto) - Content Intelligence
content-tautological Detect tautological instructions that the model already follows by default warning (auto) - Content Intelligence
content-critical-position Detect critical instructions in the middle of files where LLM attention is lowest 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) warning (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-actionability-score Score instruction files on actionability (verb density, commands, file references) 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 warning (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
coderabbit-yaml-valid .coderabbit.yaml must be valid YAML error (auto) - CodeRabbit
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
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) - Settings
apm-yaml-valid apm.yml must exist with valid YAML and required fields (name, version, description) error (auto) - APM (Agent Package Manager)
apm-structure-valid .apm/ directory must contain skills/ or instructions/ with valid structure warning (auto) - APM (Agent Package Manager)