agentleFS
synthetic-reconsynthetic-recon/atlas-obsidian-vault/.agents/skills/vault-maintain/SKILL.md

vault-maintain

Skill2 starsChanged 7 months agoMITView on GitHub

Maintain the wiki — run lint with LLM judgment, crystallize mature Outputs into Concepts/Entities, archive stale content, and promote pages through the seed → developing → mature → evergreen lifecycle. Use when the user says "lint the wiki", "health check", "clean up", "find stale pages", "promote mature concepts", or runs bin/vault-health.sh manually. Wraps the bash lint tools and adds judgment for orphan/stale/promotion decisions.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After a series of ingests, the user wants to consolidate

    line 16
  2. Distinctive:

    Look for Outputs/ pages that have:

    line 61
  3. Distinctive:

    Create or update the Concept/Entity page with them

    line 70
  4. Very specific:

    Leave the Output in place with status: current and the original query (it stays discoverable)

    line 72
  5. Distinctive:

    Never delete. The superseded page remains navigable for history.

    line 94
  6. Distinctive:

    Run weekly for an active vault.

    line 119
  7. Distinctive:

    Don't crystallize every Output: Only those that have been used, stabilized, and contain reusable claims.

    line 125

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Vault Maintain Skill

The weekly (or on-demand) upkeep pass. Bash tools do the mechanical checks; this skill adds the judgment — "is this really an orphan or just not yet linked?", "should this be promoted from developing to mature?", "is this Output crystallizable?"

When to Use

  • "Lint the wiki" / "run health check" / "clean up"
  • "What's stale?" / "Any contradictions to resolve?"
  • "Promote mature concepts"
  • "Crystallize outputs into concepts"
  • After a series of ingests, the user wants to consolidate

When NOT to Use

  • User is ingesting a new source (use vault-ingest)
  • User is reviewing the queue (use vault-review)
  • User has a specific question (use vault-query)

Workflow

Step 1 — Run the mechanical lint

bin/vault-health.sh
bin/cross-linker.sh
bin/stats.sh

Capture the output. The lint gives severity-tiered findings:

  • ERRORS (must fix): broken wikilinks, missing required frontmatter
  • WARNINGS (should address): orphans, no-outgoing-links, stale claims
  • INFO (nice to clean up): explored:false, seed-status, missing aliases

The cross-linker suggests unlinked mentions. Stats shows the vault's shape.

Step 2 — Fix ERRORS immediately

Broken wikilinks and missing frontmatter are never OK. Fix each one:

  • Broken link → either create a stub page (if the concept is worth having) or remove the link (if it was illustrative)
  • Missing status → add from the schema. If unclear, default to status: seed and mark for review

Step 3 — Judgment pass on WARNINGS

Orphans and no-outgoing-links often look bad but may be legitimate:

  • An Outputs/ page linked from nowhere is a lint failure — link it from related Concepts
  • A Sources/ page linked from nowhere means nobody extracted from it — consider re-ingesting or archiving
  • A Concept with no outgoing links is usually a stub — either populate it or delete (if truly unused)

Apply judgment, don't blindly fix.

Step 4 — Spot crystallization candidates

Look for Outputs/ pages that have:

  • Been referenced by 2+ other pages (via rg -l "[[Outputs/<name>")
  • Stabilized (no edits for a while)
  • Contain reusable claims beyond the original question

For each, consider promoting durable insights into Concepts/ or Entities/:

  1. Extract the reusable claims
  2. Create or update the Concept/Entity page with them
  3. Cross-link the Output to the new page
  4. Leave the Output in place with status: current and the original query (it stays discoverable)

This is the compounding mechanism — Outputs become Concepts, the wiki densifies.

Step 5 — Lifecycle promotion

For each Concept/Entity page, consider whether the status should advance:

  • seed → developing: when a 2nd source confirms or extends the claim
  • developing → mature: when the page has multiple sources, Counter-arguments populated, and stable structure
  • mature → evergreen: human-reviewed and rarely changing

Propose promotions; let the user confirm.

Step 6 — Archival candidates

Pages that should be marked (not deleted):

  • Questions resolved by later ingests → status: resolved, link to the resolver
  • Concepts superseded by a refined successor → status: superseded, link to replacement
  • Outputs whose underlying claims changed → status: superseded

Never delete. The superseded page remains navigable for history.

Step 7 — Update hot.md and log.md

  • log.md: append ## [date] lint | <summary of what was fixed>
  • hot.md: if significant (multiple crystallizations, promotions), update Recent Changes

Step 8 — Report

Lint results:
  Errors fixed:      N
  Warnings resolved: M
  Crystallized:      X Outputs → Concepts/Entities
  Promoted:          Y pages advanced lifecycle
  Archived:          Z pages marked superseded/resolved

Remaining:
  <anything deferred>

Next suggested action: <e.g., "re-ingest Sources/Foo" or "resolve [[Questions/X]] — 3 sources now support resolution">

Cadence

Run weekly for an active vault. Run after every 5–10 ingests during a bulk-ingest session. Run before any major refactor.

Anti-Patterns

  • Don't auto-archive. Lint surfaces candidates; humans confirm.
  • Don't delete pages to fix orphans. Links are the value; missing links are the fix, not missing pages.
  • Don't crystallize every Output. Only those that have been used, stabilized, and contain reusable claims.
  • Don't promote on schedule. Lifecycle advances on evidence, not time.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.