CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-update

Update project documentation — README.md, user guide, and UML.md. Evaluates whether the project is a coding project or a non-code workspace and adapts accordingly. Load when asked to update docs, refresh documentation, or after significant changes.

Quality

80%

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

Fix and improve this skill with Tessl

tessl review fix ./pi/agent/skills/docs-update/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

68%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-organized, actionable instruction-style skill with concrete commands, clear decision tables, and sensible guardrails ("Don't invent information", "Preserve hand-written sections"). Its main weakness is the absence of any validation or verification pass in a multi-file batch update workflow, which both costs it workflow clarity and leaves accuracy of the produced docs unconfirmed.

Suggestions

Add a verification checkpoint before the summary — e.g., re-read the updated README and confirm each documented command/path actually exists in the repo, and confirm hand-written sections were preserved verbatim.

Specify how to detect staleness in the user guide concretely (e.g., compare documented commands/API surfaces against current code) instead of the vague "check for staleness against current code/files".

Provide a fallback for Step 4 when the `uml-maintenance` skill is unavailable, or note explicitly that this skill requires it as a prerequisite.

DimensionReasoningScore

Conciseness

The body is prescriptive and efficient — no explanations of concepts Claude already knows — with only minor trimmable material (the opening line repeats the frontmatter, and the summary template is slightly padded). Matches anchor 4; not level 5 because a few passages could be tightened, but well above level 3's "unnecessary explanation".

4 / 5

Actionability

Concrete, copy-pasteable classification commands (ls/find), a signals table, exact candidate file paths for the user guide, and per-project-type README checklists. Minor gaps keep it at anchor 4 rather than 5: staleness detection is unspecified ("check for staleness against current code/files"), guide detection ends with "or similar", and Step 4 hard-depends on an external `uml-maintenance` skill with no fallback.

4 / 5

Workflow Clarity

Steps 1–5 are clearly sequenced with per-type branches, but this is a batch update across README, user guide, UML.md, and UML.html with no verification checkpoint — Step 5 is a report, not a validation, and nothing confirms hand-written sections were preserved or that documented commands/structure match reality. Per the rubric, a batch workflow missing validation is capped at 3; without the cap it would merit 4.

3 / 5

Progressive Disclosure

No bundle files exist, and the single body is well-sectioned (Steps 1–5 plus "When NOT to use") with the cross-skill delegation clearly signaled. It does not reach level 5 because at ~115 lines it exceeds the under-50-line simple-skill exception and inlines both full README checklists that could live in reference files; it is clearly above level 3 since structure and navigation are good.

4 / 5

Total

15

/

20

Passed

Description

83%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.

A strong description: it names specific artifacts and an adaptive classification behavior, and pairs them with an explicit, naturally phrased load-trigger clause. The only weaknesses are minor — a few missing trigger synonyms and slight breadth in "after significant changes".

DimensionReasoningScore

Specificity

Names concrete artifacts ("README.md, user guide, and UML.md") and a concrete adaptive behavior ("Evaluates whether the project is a coding project or a non-code workspace and adapts accordingly") — several specific actions with minor gaps (e.g., UML.html sync is not surfaced). It is not level 5 because coverage is not fully comprehensive, and not level 3 since it goes well beyond 1–2 actions.

4 / 5

Completeness

Explicitly answers both questions: a clear "what" ("Update project documentation — README.md, user guide, and UML.md") and an explicit "when" with concrete trigger phrases ("Load when asked to update docs, refresh documentation, or after significant changes"). This matches the level-5 anchor; level 4 would require the "when" to be less explicit than it is.

5 / 5

Trigger Term Quality

Includes natural phrases users would say — "update docs", "refresh documentation", "after significant changes" — with reasonable synonym coverage. Not level 5 because common variations like "keep docs current", "outdated README", or "bring documentation up to date" are missing; not level 3 since the terms present are natural rather than jargon.

4 / 5

Distinctiveness Conflict Risk

A distinct niche (doc refresh across README/guide/UML with project-type adaptation) with mostly distinct triggers; minor overlap risk with README-writing or generic documentation skills, and "after significant changes" is somewhat broad. Not level 5 due to that residual overlap risk; clearly above level 3's "could still overlap with similar skills".

4 / 5

Total

17

/

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: 1 missing

Warning

Total

15

/

16

Passed

Repository

g23polar/dotfiles

Path

pi/agent/skills/docs-update/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.