validate-project-instructions
Scannednpx machina-cli add skill MSiccDev/ai-context-kit/validate-project-instructions --openclawValidate Project Context AGENTS
Purpose
Validate project-context AGENTS.md files with deterministic checks for required sections, session-state controls, role definitions, and core required-section completeness.
When To Use
- Use this skill to validate project-context
AGENTS.mdfiles. - Use this skill when reviewing project context quality prior to active use.
- Do not use this skill for user-context instruction validation.
Required Inputs
- Target project-context
AGENTS.mdpath. - Expected section model and command reference expectations.
- Any strictness preferences for warnings vs required fixes.
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.
- Produce project-specific remediation guidance.
Output Expectations
- Structured markdown report with five validation phases.
- Clear status for critical issues vs warnings.
- Numeric score and grading band.
- Concrete example fixes for major gaps.
- 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 specific and actionable.
- Preserve project terminology when proposing fixes.
- Keep validation language provider-neutral.
- Do not rewrite source files automatically.
Source
git clone https://github.com/MSiccDev/ai-context-kit/blob/development/skills/validate-project-instructions/SKILL.mdView on GitHub Overview
This skill performs deterministic checks on project-context AGENTS.md files to ensure required sections, session-state controls, role definitions, and core completeness. It aligns with established references to produce a structured report and remediation guidance. Validation yields a clear score and actionable fixes without rewriting source files.
How This Skill Works
It executes validation phases defined in references/phase-checks.md, generates a report using references/report-contract.md, and applies scoring from references/scoring.md. Findings are categorized into critical, warning, and enhancement buckets, with project-specific remediation guidance provided for each gap.
When to Use It
- Before starting a project that relies on a project-context AGENTS.md
- During a project-context quality review prior to active use
- When a stakeholder requests QA of project-context artifacts
- When updating references, scoring model, or phase checks to ensure alignment
- For formal audits or retrofits of AGENTS.md over time
Quick Start
- Step 1: Provide the Target AGENTS.md path and any strictness preferences for warnings vs fixes
- Step 2: Run the validation workflow to produce a structured report
- Step 3: Review the remediation guidance and implement changes manually (no automatic edits)
Best Practices
- Clearly specify the target AGENTS.md path and the expected section model in inputs
- Run the five validation phases from references/phase-checks.md to ensure consistency
- Preserve project terminology and avoid automatic rewriting of source files
- Keep findings specific and actionable with concrete remediation steps
- Cross-check scoring and remediation plans against references/scoring.md for determinism
Example Use Cases
- An AGENTS.md is missing the Roles or Session-State sections and triggers critical findings
- An AGENTS.md contains an incomplete session-state model, leading to warnings and fixes
- An AGENTS.md defines vague or ambiguous roles, prompting enhancement recommendations
- An AGENTS.md scoring deviates from references/scoring.md, requiring score normalization
- An AGENTS.md receives remediation guidance that includes concrete, project-specific fixes
