agentleFS
KirKruglovKirKruglov/ARMARIUM/.claude/skills/health/SKILL.md

health

Skill1 starsChanged 5 months agoMITView on GitHub

Run the base-health maintenance — delegate a read-only audit (contradictions, duplicates, stale notes, missing links) to the auditor subagent, then produce concrete proposals and run the per-item owner-approval gate. Only owner-approved patches are applied to the base, each marked agent-authored; reviews and synthesis go to the service zone. Invoked by the armarium agent.

56 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use plan-tune, ios-clean and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ShreyRaviSkill

    plan-tune

    Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track profile (what you declared vs what your behavior suggests), and enable/disable question tuning. Conversational interface — no CLI syntax required.

    Also in 9 projects that use this

  • Saqlain-811Skill

    ios-clean

    Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)

    Also in 5 projects that use this

  • Saqlain-811Skill

    ios-fix

    Autonomous iOS bug fixer. (gstack)

    Also in 5 projects that use this

  • seek888Skill

    pair-agent

    Pair a remote AI agent with your browser. One command generates a setup key and prints instructions the other agent can follow to connect. Works with OpenClaw, Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent gets its own tab with scoped access (read+write by default, admin on request). Use when asked to "pair agent", "connect agent", "share browser", "remote browser", "let another agent use my browser", or "give browser access". (gstack) Voice triggers (speech-to-text aliases): "pair agent", "connect agent", "share my browser", "remote browser access".

    Also in 11 projects that use this

  • ShreyRaviSkill

    landing-report

    Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

    Also in 8 projects that use this

  • timurgaleevSkill

    document-generate

    Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.

    Also in 7 projects that use this

  • +1 more from Saqlain-811
  • +2 more from ShreyRavi

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 4 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 41 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    A clean run — an honest empty report: No defects → say so; don't pad with invented findings.

    line 36
  2. Distinctive:

    All write operations (applying a patch to the base.

    line 52
  3. Very specific:

    If the script emits a --- NEEDS-SEMANTIC-ENRICHMENT --- block with a non-empty list — semantic enrichment (summaries/aliases) is run by …

    line 76
  4. Very specific:

    If lock exited with exit 1 — the run is skipped, finish here.

    line 101
  5. Very specific:

    Dedup against previously rejected: Read .claude/armarium/health/decisions-log.md: a finding that matches a previously rejected item in …

    line 119
  6. Very specific:

    When there isn't enough data to decide — [health] ❓ Clarifying on item <id>: <what's missing>.

    line 133
  7. Distinctive:

    Applicability check: If the affected note was edited by the owner after the proposal was generated (the patch no longer applies cleanly) — …

    line 141
  8. Very specific:

    After applying, assemble the BINDINGS of the applied edits and return them to armarium: it runs the verifier grounding gate before delivery …

    line 158
  9. Distinctive:

    Update the health reviews per the compaction protocol (compiled-truth + archive under a separator.

    line 164
  10. Very specific:

    Don't call commit on this branch.

    line 191

“Common” is measured: kept by at least 6 in 10 of the 41 edited versions of this file we could read. “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

health — base-health maintenance workflow (the "Maintenance" pillar)

The health-run procedure of the armarium keeper agent: refresh the index, under the carrier lock delegate a read-only scan to auditor, gather the findings, produce a per-item proposal report, run the per-item owner gate, apply only approved patches to knowledge-base/ (with an authorship marker), and write the health reviews to the service zone. This is the first function where the agent, under a gate, writes to the base — the load-bearing invariant: no edit reaches the base without an explicit per-item approval.

The skill is invoked by the armarium agent on a Maintenance intent ("check base health / find duplicates / contradictions / what's stale / missing links"). A run may go headless (cron) — then the findings accumulate in the queue, and the owner works the gate in the next interactive session.

Posture and boundaries (what the skill does not do)

  • Read-only over knowledge-base/ outside the gate. The scan (auditor) and building the proposals happen with no write to the base. The only write to the base is applying an approved patch under the per-item gate, marked agent-authored. There is no autonomous, proactive, or batch write to the base.
  • The gate is mandatory and per-item. Without an explicit per-item approval, an edit is not applied. There is no default "apply all" — this is a load-bearing invariant, not a setting.
  • Maintenance does NOT run base-diff.sh (the taste diff). The mode's input is index + grep + git + health reviews. The skill doesn't read or write state/taste/sources (that's recon input, not Maintenance).
  • Service and derived output — to its own zone. Health reviews and draft synthesis notes are written to .claude/armarium/health/, not the base. Promoting a synthesis note into the base — only through the same gate + the agent-authored marker.
  • The base only. No WebSearch/WebFetch — Maintenance doesn't go to the internet.
  • A clean run — an honest empty report. No defects → say so; don't pad with invented findings.
  • auditor is invoked only from here (a single channel), never by armarium's auto-delegation.

Process indication (only at the gate)

The owner gate is a dialog point; status lines there are mandatory. Format: [health] <emoji> <action>: <value> [<context>].

  • ⏸️ — waiting on the owner's verdict for the presented item.
  • ❓ — clarification when there isn't enough data to decide on the item.

The skill does not open a checklist (TaskCreate): this is a headless procedure, invoked by the agent with no observable forward plan; status lines are needed only at the dialog gate.

Idempotency and write cadence

All write operations (applying a patch to the base; writing health reviews) run under the global carrier-reliability writer lock:

Start:  bin/run-guard.sh check  → (exit 3 → recover; exit 4 → the next lock clears the orphan) → bin/run-guard.sh lock health
Finish: bin/run-guard.sh commit → bin/run-guard.sh log --mode health --outcome ok → bin/run-guard.sh unlock
  • lock exited with exit 1 (writer-lock held) — another writing run is active: the run is skipped, do nothing further. Finish here.
  • A repeat run doesn't double proposals (dedup against the queue and the decisions log) and doesn't apply an already-applied patch twice (the approved item leaves the active queue).
  • The scripts live in .claude/armarium/bin/; run them from the repo root.

STEP 1 — index freshness (precondition)

The structural index layer must be fresh (the owner may have edited notes in Obsidian between runs):

bash .claude/armarium/bin/build-index.sh

If the script emits a --- NEEDS-SEMANTIC-ENRICHMENT --- block with a non-empty list — semantic enrichment (summaries/aliases) is run by armarium (as in QA), it's not health's job. Health is a consumer of the structural layer: for a health scan the structure is enough (paths · titles · tags · sections). Note the fact of stale semantics, but don't block on it.

STEP 2 — start under run-guard and delegate the scan

Start sanity check:

bash .claude/armarium/bin/run-guard.sh check

By the return code:

  • exit 0 (CLEAN) — proceed to the lock.
  • exit 3 (DIRTY-ZONE) — a leftover from an unfinished run: bash .claude/armarium/bin/run-guard.sh recover, then to the lock.
  • exit 4 (STALE-LOCK) — an orphaned lock; no need to clear it by hand, the next lock clears it.

Take the writer lock in health mode:

bash .claude/armarium/bin/run-guard.sh lock health

If lock exited with exit 1 — the run is skipped, finish here.

Delegate the scan to the auditor subagent via the Agent tool in a fresh window. Pass the scan domain/topic in the task text (auditor reads no config files, works over the base and git). Bring back to the main context only the findings summary (noise isolation): FINDINGS (class · affected notes · quote · rationale), SCAN STATUS, LIMITATIONS, BINDINGS, USED_NOTES.

A clean run (auditor returned empty FINDINGS) is a valid outcome: proceed to the honest empty report and finish (STEP 6), without inventing defects.

STEP 3 — per-item proposal report

For each finding, build a concrete proposal:

  • what and why — the essence of the defect with quotes citing the affected notes (paths from BINDINGS);
  • a ready patch (where applicable) — a diff of the edit / merge / restructure / added link, ready to apply via Edit/Write after approval.

Dedup against previously rejected. Read .claude/armarium/health/decisions-log.md: a finding that matches a previously rejected item in substance is not proposed again. Also read .claude/armarium/health/proposals-queue.md — don't double items already standing in the queue.

Save the report to the queue .claude/armarium/health/proposals-queue.md (under the lock, in the item format from the file's header, status pending). The owner can work the queue asynchronously, not in one pass.

STEP 4 — per-item gate (dialog point)

The owner approves / rejects / defers each item individually. There is no batch "apply all". Without an explicit per-item approval, no edit reaches the base.

  • Waiting on a verdict for an item — status line [health] ⏸️ Awaiting a verdict on item: <id> (<class>).
  • When there isn't enough data to decide — [health] ❓ Clarifying on item <id>: <what's missing>.
  • Headless run (cron, no owner in dialog): don't force the gate — items stay pending in the queue and are presented in the next interactive session. Don't second-guess the verdict.

STEP 5 — apply ONLY the approved

For items with status "approved" (under the lock):

  1. Applicability check. If the affected note was edited by the owner after the proposal was generated (the patch no longer applies cleanly) — don't apply it blind: mark the item "stale, re-evaluate next run" in the queue, don't corrupt the note. This doesn't affect the other items.
  2. Apply the patch to knowledge-base/ via Edit/Write.
  3. Authorship marker — BOTH mechanisms (the owner's decision):
    • inline marker <!-- agent-authored --> on the note's changed lines (via the same Edit/Write);
    • git commit trailer Agent-Authored: armarium, path-scoped to knowledge-base/, e.g.:
      git commit -m "fix(kb): <essence of the approved edit>" --trailer "Agent-Authored: armarium" -- knowledge-base/
    By these signs base-diff.sh excludes the agent's edit from the taste diff, so the agent doesn't learn from its own edits. The #from-curator marker is left untouched.
  4. Rejected — record in .claude/armarium/health/decisions-log.md (for the STEP 3 dedup), do not enter into the base. Deferred — leave pending in the queue.
  5. Derived (draft synthesis notes, working reviews) — only to the service zone .claude/armarium/health/, not the base.

After applying, assemble the BINDINGS of the applied edits and return them to armarium: it runs the verifier grounding gate before delivery to the owner. Do not call verifier from this skill — its Agent is held only by armarium; here this is a commitment, not a call.

STEP 6 — finish under run-guard + review compaction

Update the health reviews per the compaction protocol (compiled-truth + archive under a separator; compaction is a judgment, not truncation, by the size threshold of the working part):

  • proposals-queue.md — compiled-truth = the current queue of pending/stale items. Worked items (applied/rejected) are carried out of the active queue; the raw history of decisions goes to the archive under the separator.
  • decisions-log.md — append this run's decisions (approved/rejected/deferred) for dedup against re-proposing the rejected; drip an overgrown journal into the archive under the separator.

Then atomically commit the zone and release the lock:

bash .claude/armarium/bin/run-guard.sh commit
bash .claude/armarium/bin/run-guard.sh log --mode health --outcome ok [--mem-cost <N>]
bash .claude/armarium/bin/run-guard.sh unlock
  • commit is idempotent: NOTHING-TO-COMMIT is not an error.
  • --mem-cost <N> — a soft cost rail for the start (the size of the reviews' working part), optional.

Run failure (scan didn't assemble · fatal error) — don't write back the reviews, don't touch the base:

bash .claude/armarium/bin/run-guard.sh log --mode health --outcome failed
bash .claude/armarium/bin/run-guard.sh unlock

Don't call commit on this branch.

Edges (name them, don't mask them)

  • Stale/incomplete index → risk of missing a duplicate/contradiction or a false "missing link" — name it in the report, don't mask it.
  • False contradiction (a slice in time / different contexts) — present it as a candidate for review, not as a verdict.
  • Approved patch doesn't apply (the note changed) — mark it "stale, re-evaluate", don't apply blind (STEP 5.1).
  • Shallow/squashed git history limits the precision of the "stale" class — name the resolution limit.

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.