What is AGENTS.md in this context?

A governance and operational contract document for agents that the skill validates.

What outputs does the skill produce?

A structured markdown report with five validation phases, a compliance score, categorized issue buckets, and concrete fixes.

What inputs are required?

Target AGENTS.md path, repository path context for link validation, and policy expectations for session state and command namespace.

validate-agents-md

npx machina-cli add skill MSiccDev/ai-context-kit/validate-agents-md --openclaw

Files (1)

SKILL.md

1.9 KB

Validate AGENTS.md

Purpose

Validate AGENTS.md files to ensure they are concise, operationally complete, and aligned with repository structure and governance.

When To Use

Use this skill when adding or updating root or nested AGENTS.md files.
Use this skill before accepting AGENTS policy changes.
Do not use this skill for user/project instruction validation.

Required Inputs

Target AGENTS.md path.
Repository path context for link/path validation.
Policy expectations for session-state and command namespace.

Workflow

Run validation phases from references/phase-checks.md.
Generate report using references/report-contract.md.
Apply deterministic scoring from references/scoring.md.
Classify findings into critical/warning/enhancement buckets.
Provide concrete fixes for operational contract gaps.

Output Expectations

Structured markdown report with five validation phases.
Compliance score and pass band.
Explicit list of critical issues, warnings, and enhancements.
Example fixes for common structural and policy failures.
Report schema follows references/report-contract.md.
Scoring and grade bands follow references/scoring.md.

Resources

Phase checks: references/phase-checks.md
Report contract: references/report-contract.md
Scoring model: references/scoring.md
Example target: ../../AGENTS.md

Constraints And Safety

Keep findings deterministic and repository-specific.
Avoid over-prescriptive style-only feedback.
Preserve provider-neutral language.
Do not duplicate full normative specs when suggesting fixes.

Source

git clone https://github.com/MSiccDev/ai-context-kit/blob/development/skills/validate-agents-md/SKILL.mdView on GitHub

Overview

Validate AGENTS.md files to ensure conciseness, operational coverage, and governance alignment. It checks structure, policy commitments for the operational contract, neutrality, and repository alignment, then outputs a deterministic report with scoring and actionable fixes.

How This Skill Works

The skill runs the prescribed phase checks from references/phase-checks.md, generates a report using references/report-contract.md, and applies deterministic scoring from references/scoring.md. It then classifies findings into critical, warning, and enhancement buckets and provides concrete fixes for gaps in the operational contract.

When to Use It

When adding or updating root or nested AGENTS.md files
Before accepting AGENTS policy changes
Auditing policy coverage across repositories
Validating link and path integrity against the repository context
Not suitable for validating user or project instruction validation

Quick Start

Step 1: Provide the target AGENTS.md path and repository path context
Step 2: Run the validation workflow to perform phase checks and scoring
Step 3: Review the generated report and apply the recommended fixes

Best Practices

Run validation phases from references/phase-checks.md
Apply scoring from references/scoring.md to prioritize fixes
Validate link and path references using the repository path context
Review critical/warning/enhancement buckets and map to concrete fixes
Provide example fixes for common structural and policy failures without duplicating full normative specs

Example Use Cases

Root AGENTS.md in a multi-repo project to enforce governance
Nested module AGENTS.md updated to reflect policy changes
PR review stage validating AGENTS.md before merge
Cross-repo audit ensuring neutrality and alignment with governance references
Post-change validation to confirm references/phase-checks.md alignment

Frequently Asked Questions

Add this skill to your agents