CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

housekeeping

Run the recurring housekeeping pass — audit the agent files for rot, the glossary against the code, the decision index, the mutation measurement, the worktrees and the diary, then scan the codebase for Ousterhout's red flags and route each finding to the skill that owns it. It never fixes what it finds; findings leave as candidate tickets. Its one write of its own is stamping the diary's Last housekeeping row, and its one delegated action is the worktree pruning it hands to the cleanup skill. Use when the docs gate's housekeeping-due advisory fires, on the cadence the gate config names, or before cutting a release.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-crafted instruction-only skill body: an unambiguous sequenced procedure with pre-state checks and explicit stop points, concrete formats and commands throughout, and a sensible summary-here/detail-elsewhere split. The two real weaknesses are the motivational opener/footer that could be trimmed for token efficiency, and that the checklist's promised full form lives in a CHECKLIST.md that is not present in this bundle, leaving the skill's core reference unresolvable as shipped.

Suggestions

Ship CHECKLIST.md with the skill (or inline the per-item 'what counts as a finding / what to route it to' details), since the body's checklist items depend on it and the file is absent from the bundle.

Trim the opening 'Standing instructions rot on a calendar…' paragraph and the italic closing provenance note to a sentence each — they are motivation, not instruction, and cost roughly 13 lines of context.

Name the actual mutation command (or the exact decision-line format to read it from) in item 4, so step 2's 'item 4 runs one command' is executable without consulting the engineering article.

DimensionReasoningScore

Conciseness

The body is dense and project-specific with no explanation of concepts Claude already knows — commands, paths, and formats are given directly ('sh scripts/agents.lib.sh planner', the exact diary row template, the '<tmpdir>/housekeeping-<YYYYMMDDTHHMMSSZ>.md' naming). Minor trims are possible: the 8-line opening paragraph on why instructions rot and the italic closing provenance note are motivational rather than instructional, which keeps it at anchor 4 instead of the lean anchor-5 case where every token earns its place.

4 / 5

Actionability

Guidance is mostly executable — an exact runbook step order, a copy-paste diary row format, a concrete commit message prefix ('docs(housekeeping): …'), temp-dir resolution rules, and per-finding routing targets. It falls short of anchor 5 because several steps defer their specifics elsewhere ('the full form of each … is in CHECKLIST.md', 'run the mutation tool the engineering article's decision line names' without naming the command), leaving minor gaps the reader must fill from other files.

4 / 5

Workflow Clarity

The Procedure is a clear 6-step sequence with explicit checkpoints: the 'Three states to check before starting' handles edge cases, step 4 mandates per-item evidence ('A pass that finds nothing says so, per item'), and step 5's hard stop ('invoking them is the human's next act') plus step 6's stamp-after-pass rule act as validation gates. The pass's only writes are one row and one local commit — no destructive or batch operation lacking a feedback loop — so it meets the anchor-5 pattern of a well-checklisted, explicitly gated process.

5 / 5

Progressive Disclosure

Structure is good: the checklist section keeps one summary line per item in SKILL.md and clearly signals a single one-level-deep reference for the full forms ('The full form of each — what to look at, what counts as a finding, what to route it to — is in CHECKLIST.md; this is the order'). However, no CHECKLIST.md exists anywhere in the reviewed bundle (references/, scripts/, and assets/ are all absent), so the load-bearing reference is dangling as shipped; that unverifiable split, rather than any structural flaw, holds this at anchor 4 instead of the clean overview-plus-reference pattern of anchor 5.

4 / 5

Total

17

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An exemplary description: concrete and comprehensive on capabilities, explicit about scope boundaries (never fixes, one write, one delegation), and with a clear 'Use when' clause. The only soft spot is that its trigger terms lean on internal kit events (the docs gate advisory, the cadence config) more than on the natural phrases a user would spontaneously say, which leaves slight room for improvement on trigger-term coverage.

DimensionReasoningScore

Specificity

The description enumerates concrete audit targets ('audit the agent files for rot, the glossary against the code, the decision index, the mutation measurement, the worktrees and the diary'), a concrete scan ('scan the codebase for Ousterhout's red flags'), and concrete outputs ('route each finding to the skill that owns it', 'stamping the diary's Last housekeeping row'). Actions are specific and comprehensive rather than generic — clearly the anchor-5 example, not the anchor-4 case, which would leave minor coverage gaps.

5 / 5

Completeness

Both halves are explicit: 'what' is the full audit-and-route inventory plus the boundary ('It never fixes what it finds; findings leave as candidate tickets'), and 'when' is a dedicated 'Use when...' clause with three concrete triggers ('when the docs gate's housekeeping-due advisory fires, on the cadence the gate config names, or before cutting a release'). This matches anchor 5 exactly; anchor 4 would require the 'when' to be less explicit or specific, which it is not.

5 / 5

Trigger Term Quality

Triggers include natural phrases a user would say ('housekeeping', 'audit', 'before cutting a release'), but the primary triggers are system-event terms ('docs gate's housekeeping-due advisory fires', 'the cadence the gate config names') rather than the natural user vocabulary and synonyms the anchor-5 example shows. Good keyword coverage with a few natural terms missing fits anchor 4; it is well above anchor 3's 'missing common variations' because the domain terms are all present and used consistently.

4 / 5

Distinctiveness Conflict Risk

The skill occupies a clear niche — the recurring, calendar-driven audit pass — with triggers (advisory firing, cadence, pre-release) that no sibling skill would claim, and it explicitly delimits its writes and delegation ('its one delegated action is the worktree pruning it hands to the cleanup skill'). Minimal conflict risk, matching anchor 5 rather than anchor 4's 'minor overlap risk with closely related skills'.

5 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 2 possibly missing (scripts/agents.lib.sh, scripts/docs-conformance/config.mjs), 1 deeper-than-1-level

Warning

Total

15

/

16

Passed

Repository

agranado2k/ai-report-platform

Path

.agents/skills/housekeeping/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.