speckit-wiki-lint
Skill107 starsChanged 9 months agoMITView on GitHub
Health-check the wiki: contradictions, orphan pages, stale claims, broken
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- commitSkill
- create-pull-requestSkill
- create-release-branchSkill
- create-release-notesSkill
- handle-pr-reviewSkill
- qlty-checkSkill
- record-code-review-feedbackSkill
- record-spec-feedbackSkill
- recreate-test-dbSkill
- redmine-playwright-loginSkill
- regression-checkSkill
- rubocopSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-branch-convention-configureSkill
- speckit-branch-convention-renameSkill
- speckit-branch-convention-validateSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-token-budget-compactSkill
- speckit-token-budget-conciseSkill
- speckit-token-budget-scopeSkill
- speckit-token-budget-usageSkill
- speckit-wiki-ingestSkill
- speckit-wiki-initSkill
- speckit-wiki-querySkill
- speckit-wiki-statusSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 58
If lint.auto_fix is index-and-links:
- Very specific: line 65
If lint.auto_fix is none, list these as suggested fixes instead.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Wiki Lint Skill
Lint the Wiki
The maintenance pass that keeps a compounding wiki from rotting. Karpathy's LLM Wiki pattern calls for regular health checks — contradictions, orphaned pages, stale claims, coverage gaps — because an unmaintained knowledge base is abandoned, not merely imperfect.
Mechanical problems are fixed automatically (when configured); semantic problems are reported with suggested edits, never auto-rewritten.
User Input
$ARGUMENTSOptional scope: a page filename (lint one page and its neighbors) or a check name from the list below (run only that check). Empty means the full pass.
Steps
1. Resolve the wiki
Load configuration exactly as /speckit.wiki.init does. If
WIKI_DIR/SCHEMA.md does not exist, report that and stop. Read SCHEMA.md,
INDEX.md, and sources.md; read pages as each check requires.
2. Run the checks
| Check | Finds | Severity |
index-drift | pages missing from INDEX.md; index lines pointing at nonexistent files | mechanical |
links | relative links to missing pages; citations naming unknown S-ids | mechanical |
orphans | pages no other page links to (INDEX itself does not count) | structural |
contradictions | > ⚠ conflict: markers still unresolved; pairs of pages sharing a source or link that assert incompatible claims | semantic |
stale | pages whose updated is older than lint.stale_after_days; pages whose source was re-ingested after the page was last updated | semantic |
citations | claims without a source ID, when ingest.require_citations is true | semantic |
Bound the contradiction check: compare only pages that share a source ID or a link — never all pairs.
3. Apply mechanical fixes (per config)
If lint.auto_fix is index-and-links:
- regenerate
INDEX.mdfrom the actualpages/contents (grouped by frontmattertype, one line each); - repair links whose target was renamed (when the target is unambiguous) and remove links to pages that no longer exist.
If lint.auto_fix is none, list these as suggested fixes instead. Never
auto-fix a semantic finding — do not rewrite prose, resolve conflicts, or
delete claims.
4. Write the report
Overwrite WIKI_DIR/lint-report.md:
# Wiki Lint Report — <today's date>
| # | Check | Severity | Page | Finding | Suggested fix |
|---|-------|----------|------|---------|---------------|
| 1 | contradictions | semantic | payments-retries.md | S002 vs S007 on retry cap | re-ingest source S002; keep the newer claim, drop the marker |One row per finding; a clean pass writes the header plus "No findings."
5. Report
- Counts per check, fixes applied vs. suggested.
- The two or three highest-value findings, verbatim from the table.
- Next step: the single action that clears the most severe finding (usually a re-ingest of a stale source, or a conflict for the user to resolve by editing the page).
Guardrails
- Mechanical fixes only —
INDEX.mdand link targets. Page prose, claims, conflict markers, andsources.mdhistory are never modified by lint. lint-report.mdis the only file lint may overwrite wholesale.- Findings must be verifiable: every row names the page and the exact claim or link it refers to.
- Stay within the configured token budget: read pages check-by-check, not the whole wiki at once.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

