Rules CLI

ails rules exposes the framework rule set as a queryable registry. Use it to fetch the rules that apply before writing a skill, agent, rule, or instruction file — write compliant content from the start instead of patching lint findings after.

Why preflight

ails check runs after a file is on disk and reports what's wrong. ails rules runs before and tells you what to do. The shift:

For an AI coding agent about to author a SKILL.md, the preflight output becomes context that shapes the draft. Catastrophe patterns (8 rule violations on a fresh skill) drop sharply when the agent reads the constraints first.

Commands

ails rules list

Every rule in the registry, filterable. Filters compose.

ails rules list                              # all rules across all agents
ails rules list --capability=skill           # rules whose match.type includes skill
ails rules list --capability=skill --capability=agent  # multiple capabilities (repeatable)
ails rules list --agent=claude               # CORE + CLAUDE rules only
ails rules list --severity=high              # critical + high severity rules
ails rules list --format=json                # structured output for tooling

--severity accepts critical, high, medium, low — interpreted as at or above (so --severity=high returns critical + high).

Workflow-ordered preflight: pass --capability and use --format=md to pipe rules straight into an authoring agent's prompt. The output groups by category in writing order:

1. structure — get the shape right first (frontmatter, file location, links resolve)
2. direction — directive instructions are clear, no ambiguity
3. coherence — content consistent, no contradictions
4. efficiency — keep within context budget
5. maintenance — keep fresh, no stale refs
6. governance — policy alignment

Within each category, rules are sorted by severity (critical → high → medium → low). The operator (or agent) reads top-down and addresses concerns in the right order.

ails rules agents

Enumerate known agents (antigravity, claude, codex, copilot, cursor, ...).

ails rules agents
ails rules agents -f json

ails rules capabilities

Enumerate the capability vocabulary an agent declares (skills, agents, main, hooks, ...). Detects current project's agent by default; override with --agent.

ails rules capabilities                      # auto-detect agent from cwd
ails rules capabilities --agent=claude       # explicit
ails rules capabilities --agent=claude -f json

For each capability the text output shows the resolved path glob it scans and the number of matching targets in the current project, so you can see at a glance what ails check <capability> would actually pick up:

Capabilities for claude (17):
  agents             .claude/agents/**/*.md                 14 found
  child_instruction  **/CLAUDE.md                           90 found
  commands           .claude/commands/*.md                  0 found
  ...
  skills             .claude/skills/**/SKILL.md             15 found
  worktree_include   .worktreeinclude                       0 found

The list is per-agent and covers every surface that agent declares, so the count is higher than the handful you target day to day. The ... above stands in for the rows this page omits — the command prints all 17.

The JSON form keeps the flat capabilities name list and adds a resolution array alongside it — one entry per capability with name, resolves_to (the path glob), and found (the count of matching targets):

{
  "agent": "claude",
  "capabilities": ["agents", "child_instruction", "commands", "config", "hooks", "keybindings", "main", "mcp",
                   "memory", "output_styles", "override", "plugins", "rules", "scheduled_tasks", "skills",
                   "subagent_memory", "worktree_include"],
  "resolution": [
    { "name": "skills", "resolves_to": ".claude/skills/**/SKILL.md", "found": 15 }
  ]
}

The resolution array carries one entry per capability; the sample shows a single entry for brevity.

ails explain <id-or-slug>

Single-rule detail: title, category, severity, type, body, and pass/fail examples. Accepts a rule ID or a slug (run ails --install-completion once for tab completion).

ails explain CORE:S:0024                     # by ID
ails explain section-headers-present         # by slug

Output formats

Text (-f text, default)

Compact terminal output. Rule IDs, severity, titles only. Useful for quick scans.

Markdown (-f md)

Rich output suitable for piping into an agent's context. Default behavior includes Pass / Fail example blocks pulled from each rule's rule.md body. --no-examples strips them for a shorter context payload.

ails rules list --capability=skill --agent=claude -f md > skill-preflight.md
# Paste skill-preflight.md into your authoring agent's prompt before writing.

JSON (-f json)

Stable structured payload for tooling. Top-level keys: capability, capabilities, agent, agents_loaded, count, checks. Each entry in checks has id, title, slug, category, severity, type, and match. For rule bodies and Pass / Fail examples, use the markdown format (-f md) or the text view ails explain <id>.

Integration patterns

Pipe into an authoring agent

ails rules list --capability=skill --agent=claude -f md | claude code "Write a skill called 'analyze-test-coverage' following these rules"

The agent receives the rule set as context before writing. Output should pass ails check skills:analyze-test-coverage on the first run.

Custom Claude Code agent

Add a slash command that wraps ails rules:

---
description: Fetch reporails rules for authoring a {{capability}}
---

Run `ails rules list --capability={{capability}} -f md` and follow the rules when writing the requested file.

CI gate

# Before opening a PR that adds a new skill, run preflight:
- run: ails rules list --capability=skill -f md > preflight.md
- run: # ... your authoring step
- run: ails check skills:<new-skill-name> --strict

Related

• Score Guide — how findings compose into a score
• Capability Levels — read-out of project architectural maturity
• Configuration — .ails/config.yml options

← Score Guide · Rules CLI · Capability Levels →