coding-guidelines-verify
npx machina-cli add skill jmerta/codex-skills/coding-guidelines-verify --openclawCoding guidelines verifier
Goal
Validate that changes follow the nearest nested AGENTS.md:
- default: changed files only
- default: auto-fix formatting before lint/tests
- monorepo-aware: each module’s
AGENTS.mdis the source of truth for that scope
Workflow (checklist)
- Collect changed files (staged + unstaged + untracked).
- For each changed file, find the nearest parent
AGENTS.md.- If a file has no scoped
AGENTS.md, report it (suggest runningcoding-guidelines-gen).
- If a file has no scoped
- Parse the
codex-guidelinesblock (schema:references/verifiable-block.md). - Run, per scope:
- format (auto-fix) -> lint -> tests
- apply simple forbid rules (globs/regex) from the block
- Produce a short compliance report (template:
references/report-template.md).
Automation
Use scripts/verify_guidelines.py to group scopes, run commands, and report results.
- If
pythonis not available or the script fails, tell the user and ask whether to install Python or proceed with a manual per-scope verification.
Deliverable
Provide:
- The per-scope compliance report (use
references/report-template.md). - Any auto-fix formatting changes applied.
- Lint/test commands run and their results, plus any violations.
Source
git clone https://github.com/jmerta/codex-skills/blob/main/coding-guidelines-verify/SKILL.mdView on GitHub Overview
This skill verifies that code changes follow the nearest nested AGENTS.md rules. It groups changed files by scope, auto-fixes formatting before lint/tests, and reports violations per scope. This monorepo-aware approach keeps module-specific standards intact and actionable.
How This Skill Works
It collects all changed files (staged, unstaged, and untracked) and locates the nearest parent AGENTS.md for each file. It then parses the codex-guidelines block to determine scope rules, and for every scope executes format (auto-fix) → lint → tests, applying simple forbid rules from the block. Automation is driven by scripts/verify_guidelines.py to group scopes, run commands, and produce a compliance report using references/report-template.md.
When to Use It
- When auditing changes across a monorepo with nested AGENTS.md rules
- During a feature branch that touches multiple modules and needs scoped compliance
- To auto-fix formatting before linting/tests for changed files
- When enforcing per-scope compliance rather than global standards
- To generate a per-scope compliance report for reviewer-ready results
Quick Start
- Step 1: Run scripts/verify_guidelines.py to collect and check changed files
- Step 2: Review the per-scope compliance report generated from references/report-template.md
- Step 3: Apply auto-fix changes if formatter suggestions are shown and re-run the check
Best Practices
- Always run on the full set of changed files (staged, unstaged, untracked)
- Ensure each affected file has an AGENTS.md in a parent scope
- Let auto-fix formatting complete before lint/tests
- Review the per-scope report and address violations in the relevant scope
- Keep AGENTS.md and the codex-guidelines block up to date for accurate results
Example Use Cases
- Monorepo with modules A/B/C each with their own AGENTS.md
- Feature across services modifying shared utilities
- CI runs verify_guidelines.py to automatically format and validate changes
- A file lacking a scoped AGENTS.md triggers a remediation step
- Teams use per-scope reports to close PRs with clear compliance status
