Use when docs/solutions/ learnings may be stale — after refactors, migrations, or dependency upgrades, when a retrieved learning feels outdated or contradicts a recently solved problem, when pattern docs no longer reflect current code, or when reviewing docs/solutions/ for accuracy.
34
31%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/compound-refresh/SKILL.mdQuality
Discovery
22%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is heavily skewed toward 'when' triggers while entirely omitting 'what' the skill does. A reader or Claude selecting this skill would know the situations that call for it but have no idea what actions it performs. The description needs a clear statement of capabilities before the trigger conditions.
Suggestions
Add a clear 'what' clause at the beginning describing concrete actions, e.g., 'Reviews and updates docs/solutions/ learnings and pattern docs to remove or correct stale information.'
Include explicit outcome language so Claude knows what the skill produces, e.g., 'Flags outdated learnings, updates pattern documentation to reflect current code, and removes contradictory or obsolete entries.'
Restructure to lead with capabilities followed by a 'Use when...' clause, matching the pattern: '[What it does]. Use when [trigger conditions].'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lacks concrete actions. It describes when to use the skill but never states what the skill actually does — no verbs like 'updates', 'validates', 'removes', or 'refreshes' are present. The language is abstract and situational rather than action-oriented. | 1 / 3 |
Completeness | The description answers 'when' extensively but completely fails to answer 'what does this do'. There is no indication of the actual actions or outcomes the skill performs — does it delete stale docs, update them, flag them, or something else entirely? | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'refactors', 'migrations', 'dependency upgrades', 'learning', 'pattern docs', and 'docs/solutions/' which could match user queries. However, it misses common natural terms a user might say like 'outdated documentation', 'clean up docs', 'update learnings', or 'stale knowledge'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on 'docs/solutions/' and 'learnings' staleness gives it some specificity, but the broad mention of 'refactors, migrations, or dependency upgrades' could overlap with skills related to code migration, refactoring, or dependency management. Without clear actions, it's hard to distinguish from general documentation skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill demonstrates excellent workflow design with clear phasing, validation checkpoints, and decision frameworks for maintaining documentation quality. However, it is severely over-engineered for a context-window-constrained skill file — the content is roughly 4-5x longer than necessary, with extensive repetition (autonomous mode rules appear in at least 3 sections), explanations of concepts Claude already knows (git branching, subagent patterns), and no progressive disclosure despite the length demanding it. The lack of executable code examples also limits actionability.
Suggestions
Reduce the document to ~100-150 lines by eliminating repeated autonomous mode rules (consolidate into one section), removing explanations of concepts Claude knows (git workflows, what subagents are), and compressing tables that restate prose.
Extract detailed content into bundle files: autonomous-mode-rules.md, subagent-strategy.md, commit-conventions.md, and common-mistakes.md, with clear one-level-deep references from the main SKILL.md.
Add concrete executable examples — e.g., actual frontmatter YAML for stale-marking, actual shell commands for the archive flow, and a sample replacement learning document rather than describing the format in prose.
Consolidate the autonomous vs interactive mode guidance into a single decision table rather than repeating 'in autonomous mode, do X instead' throughout every section of the document.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~400+ lines. It extensively explains concepts Claude already understands (what subagents are, how to ask questions, what git branches are), repeats rules across multiple sections (autonomous mode behavior is stated in at least 3 places), and includes lengthy tables and examples for relatively straightforward decision logic. Many sections could be compressed to a fraction of their size. | 1 / 3 |
Actionability | The skill provides clear decision frameworks, classification criteria, and workflow steps, but lacks executable code examples. The guidance is specific (e.g., frontmatter fields to add, directory paths to use) but mostly procedural prose rather than concrete commands or code snippets. The commit phase includes some specific git commands but most phases describe what to do abstractly. | 2 / 3 |
Workflow Clarity | The multi-phase workflow (Phase 0 through Phase 5) is clearly sequenced with explicit ordering rationale, validation checkpoints (e.g., evidence assessment before Replace, checking problem domain before Archive), and feedback loops (mark stale when uncertain, re-run compound when evidence is insufficient). The refresh order section explicitly explains why learnings come before patterns. | 3 / 3 |
Progressive Disclosure | No bundle files are provided, yet this is a monolithic ~400+ line document with no references to supporting files. Content like the detailed subagent strategy, autonomous mode rules, commit conventions, and common mistakes table could all be split into separate reference files. Everything is inline in a single wall of text with no progressive disclosure structure. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (550 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
c037ce3
Table of Contents
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.