Agent Skills
› liaohch3/claude-tap
› legibility-check
legibility-check
GitHub验证维护者文档结构、标准时效性、清单路径及计划状态。用于在修改 .agents/docs/ 下文件后，提前捕获元数据过时、路径断裂和状态漂移问题，避免 CI 失败。
Trigger Scenarios
修改 .agents/docs/standards/ 下的文件
修改 .agents/docs/plans/ 下的文件
修改 .agents/docs/architecture/ 下的文件
修改 AGENTS.md
Install
npx skills add liaohch3/claude-tap --skill legibility-check -g -y
SKILL.md
Frontmatter
{
"name": "legibility-check",
"description": "Validate maintainer docs structure, standards freshness, manifest paths, and plan state. Run this after modifying any file under .agents\/docs\/standards\/, .agents\/docs\/plans\/, .agents\/docs\/architecture\/, or AGENTS.md — it catches stale metadata, broken manifest paths, and plan state drift before CI does.",
"user_invocable": true
}
Legibility Check
Run deterministic checks for maintainer docs that mirror what CI enforces via .github/workflows/legibility.yml. Catching these locally saves a round-trip to CI.
What it checks
- Standards freshness — every
.agents/docs/standards/*.mdmust have frontmatter withowner,last_reviewed(ISO date), andsource_of_truth. Files reviewed more than 60 days ago produce a warning. - Architecture manifest — every path listed in
.agents/docs/architecture/manifest.yamlunderexpected_paths:must exist in the repo. - Plan state drift — every
.agents/docs/plans/**/*.mdmust have astatusfrontmatter field (active,completed, orcancelled). Completed plans must not contain unchecked- [ ]checkboxes (outside fenced code blocks).
Run
uv run python scripts/check_legibility.py
Options:
--freshness-days N— change the staleness threshold (default: 60)--strict-freshness— promote stale warnings to failures--repo-root PATH— override repo root (default: cwd)
Fixing common failures
| Failure | Fix |
|---|---|
missing frontmatter key 'X' |
Add the missing key to the YAML frontmatter block at the top of the file |
last_reviewed must be ISO date |
Use YYYY-MM-DD format |
last_reviewed ... is stale |
Update last_reviewed to today's date after reviewing the content |
expected path missing: X |
Either create the file or remove the stale entry from manifest.yaml |
status must be one of [...] |
Add status: active (or completed/cancelled) to plan frontmatter |
completed plan still contains unchecked TODO |
Check off remaining items or change status back to active |
After fixing
Re-run the check to confirm all issues are resolved before committing:
uv run python scripts/check_legibility.py && echo "All clear"
Version History
- 7170ab3 Current 2026-07-05 15:20
