skill-review

Reviewing SKILL.md files involves auditing frontmatter for required keys like name and description, and checking body structure for imperative, third-person style and progressive disclosure. This ensures documentation consistency and clarity across all core, openspec-plugin, and openspec-rewrite directories.

The best way to enforce frontmatter presence and writing style is to run a comprehensive quality review on a specified skill directory. This process identifies missing required keys and ensures the writing style aligns with established repo conventions for skill documentation.

Yes, you can audit cross-skill consistency and side effect guardrails across an entire repository. The review process applies repository-wide consistency guidance, checking for guardrails when side effects are present to ensure uniform skill documentation quality.

Yes, the skill documentation review works on a user-specified directory path. You provide the path to a skill directory or a specific SKILL.md file to run a comprehensive quality review for clarity, consistency, and conformance issues.

Skill documentation files fail consistency checks due to missing frontmatter keys, inconsistent writing style, lack of imperative third-person voice, poor body structure, or missing cross-skill guardrails. Auditing identifies these specific clarity and conformance issues.

You need to run a skill documentation quality audit when creating or updating SKILL.md files. It is necessary to verify frontmatter presence, enforce writing style guidelines, and validate cross-skill consistency before finalizing skill documentation.