From epieczko-betty
The `docs.validate.skill_docs` skill validates SKILL.md documentation files against their corresponding skill.yaml manifests to ensure completeness, consistency, and quality. This skill helps maintain high documentation standards across all Betty Framework skills by automatically checking for required sections and verifying that documented fields match the manifest.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-1 --plugin epieczko-bettyThis skill uses the workspace's default tool permissions.
The `docs.validate.skill_docs` skill validates SKILL.md documentation files against their corresponding skill.yaml manifests to ensure completeness, consistency, and quality. This skill helps maintain high documentation standards across all Betty Framework skills by automatically checking for required sections and verifying that documented fields match the manifest.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
The docs.validate.skill_docs skill validates SKILL.md documentation files against their corresponding skill.yaml manifests to ensure completeness, consistency, and quality. This skill helps maintain high documentation standards across all Betty Framework skills by automatically checking for required sections and verifying that documented fields match the manifest.
Documentation quality is critical for skill discoverability and usability. This skill addresses the common problem of documentation drift, where SKILL.md files become outdated or incomplete as skills evolve. By automatically validating documentation, this skill ensures that:
This enables developers to maintain high-quality, trustworthy documentation with minimal manual effort.
python skills/docs.validate.skill_docs/skill_docs_validate.py <skill_path> [options]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
skill_path | string | Yes | - | Path to skill directory containing skill.yaml and SKILL.md |
--summary | boolean | No | false | Print a short summary table instead of full JSON output |
--no-headers | boolean | No | false | Skip validation of required headers |
--no-manifest-parity | Skip validation of manifest field parity |
--summary: Displays a concise table showing validation status for each skill--no-headers: Skips checking for required section headers--no-manifest-parity: Skips checking that SKILL.md matches skill.yaml fieldsThe skill accepts the following inputs:
skill_path (required): Path to the skill directory to validate. Can be a single skill directory or a parent directory containing multiple skills for batch validation.
summary (optional, default: false): When enabled, outputs a formatted table summary instead of detailed JSON output. Useful for quick validation checks.
check_headers (optional, default: true): Validates that SKILL.md contains all required section headers: Overview, Purpose, Usage, Inputs, Outputs, Examples, Integration, and Errors.
check_manifest_parity (optional, default: true): Validates that documented inputs, outputs, and metadata match the skill.yaml manifest.
The skill produces a JSON validation report with the following fields:
Each error/warning includes:
type: Error type (e.g., "missing_header", "undocumented_input")message: Human-readable descriptionseverity: "error" or "warning"file: Affected file (if applicable)suggestion: Recommended fix (if applicable)python skills/docs.validate.skill_docs/skill_docs_validate.py skills/api.validate
Output:
{
"ok": true,
"status": "valid",
"skill_path": "skills/api.validate",
"errors": [],
"warnings": [],
"details": {
"valid": true,
"skill_name": "api.validate",
"skill_path": "skills/api.validate",
"errors": [],
"warnings": [],
"checks_run": {
"headers": true,
"manifest_parity": true
}
}
}
python skills/docs.validate.skill_docs/skill_docs_validate.py skills --summary
Output:
================================================================================
SKILL DOCUMENTATION VALIDATION SUMMARY
================================================================================
Skill Name Status Errors Warnings
--------------------------------------------------------------------------------
api.validate VALID 0 0
docs.validate.skill_docs VALID 0 0
generate.docs VALID 0 1
workflow.validate INVALID 2 0
--------------------------------------------------------------------------------
Total: 4 skills | Valid: 3 | Total Errors: 2 | Total Warnings: 1
================================================================================
python skills/docs.validate.skill_docs/skill_docs_validate.py skills/workflow.validate
Output:
{
"ok": false,
"status": "invalid",
"skill_path": "skills/workflow.validate",
"errors": [
{
"type": "missing_header",
"message": "Required header 'Integration' not found in SKILL.md",
"severity": "error",
"file": "SKILL.md",
"suggestion": "Add a '## Integration' section to SKILL.md"
},
{
"type": "undocumented_input",
"message": "Input 'strict_mode' from manifest not documented in SKILL.md",
"severity": "error",
"file": "SKILL.md",
"suggestion": "Document the 'strict_mode' input in the Inputs section"
}
],
"warnings": [],
"details": {
"valid": false,
"skill_name": "workflow.validate",
"checks_run": {
"headers": true,
"manifest_parity": true
}
}
}
python skills/docs.validate.skill_docs/skill_docs_validate.py skills/api.validate --no-headers
This validates only manifest field parity, skipping header checks.
The following headers must be present in SKILL.md:
Alternative header variations are accepted (e.g., "How to Use" for "Usage", "Parameters" for "Inputs").
The skill validates that:
| Error Type | Severity | Description |
|---|---|---|
missing_file | error | SKILL.md file not found |
missing_header | error | Required section header missing |
undocumented_input | error | Manifest input not documented |
undocumented_output | warning | Manifest output not documented |
missing_skill_name | warning | Skill name not mentioned in docs |
invalid_status | warning | Non-standard status value |
missing_tags | warning | No tags defined in manifest |
You can integrate this skill with Betty's hook system to automatically validate documentation before commits:
# .betty/hooks/pre-commit.yaml
name: validate-docs-pre-commit
event: pre-commit
skill: docs.validate.skill_docs
inputs:
skill_path: ${CHANGED_SKILL_DIR}
summary: true
on_failure: block
Example workflow for continuous documentation validation:
name: validate-all-skill-docs
description: Validate all skill documentation files
steps:
- name: validate-docs
skill: docs.validate.skill_docs
inputs:
skill_path: skills
summary: true
check_headers: true
check_manifest_parity: true
- name: report-results
condition: ${{ steps.validate-docs.outputs.valid == false }}
action: fail
message: "Documentation validation failed. See errors above."
Add to your CI/CD pipeline:
# Validate all skills and fail on errors
python skills/docs.validate.skill_docs/skill_docs_validate.py skills --summary || exit 1
| Code | Description |
|---|---|
| 0 | All validations passed successfully |
| 1 | Validation failed (errors found) or usage error |
Error:
{
"type": "missing_header",
"message": "Required header 'Integration' not found in SKILL.md"
}
Fix: Add the missing section to SKILL.md:
## Integration
Describe how to integrate this skill with workflows and hooks.
Error:
{
"type": "undocumented_input",
"message": "Input 'api_key' from manifest not documented in SKILL.md"
}
Fix: Document the input in the Inputs section:
## Inputs
- **api_key** (optional): API authentication key for external service
Error:
{
"type": "invalid_status",
"message": "Manifest status 'beta' is not a standard value"
}
Fix: Update skill.yaml to use a standard status:
status: experimental # Use: active, deprecated, or experimental
v0.1.0