Overview

Validates user-context instruction files against schema and required sections, delivering deterministic reports with issues, recommendations, and a compliance score. This helps ensure quality before publishing or reusing files.

How This Skill Works

It executes phase checks from references/phase-checks.md, generates a report using references/report-contract.md, and applies scoring from references/scoring.md. Findings are then classified into critical, warning, and enhancement buckets with actionable, implementation-ready recommendations.

When to Use It

• Validate *_usercontext.instructions.md files to ensure they conform to the target schema and sections.
• Run before publishing a new or updated user-context file to catch issues early.
• Use to prevent reuse of non-compliant user-context files across projects or agents.
• Verify alignment with the expected spec version and required sections during validation.
• Note: Do not use this skill for AGENTS.md (project context) files.

Quick Start

1. Step 1: Provide the target file path, the expected spec version, and the required sections.
2. Step 2: Run the validation to produce phase reports, the results, and the score.
3. Step 3: Review the recommendations and apply implementation-ready fixes to the source file.

Best Practices

• Provide the exact target file path, expected spec version, and required sections as inputs.
• Run the phase checks and review phase-by-phase findings in the generated report.
• Cross-check that the score and grade bands match references/scoring.md.
• Keep findings privacy-preserving and avoid exposing sensitive data in reports.
• Do not auto-modify validated source files; implement fixes manually based on recommendations.

Example Use Cases

• A QA engineer validates a new sample_usercontext.instructions.md before release.
• An automated CI job runs this skill on a pull request to surface issues.
• A team re-validates a user-context file after schema updates to ensure compatibility.
• Governance reviews ensure the compliance score meets organizational thresholds.
• A migration scenario documents adapting an existing file to a new spec version.

Frequently Asked Questions