CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

update-docs

Update documentation in docs/public/ based on recent code changes. Reads git history since a watermark commit, maps changed files to doc pages, and makes surgical edits to keep docs in sync with code.

Quality

84%

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

93%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 tight, highly actionable workflow: exact commands, concrete filters for what to update vs. skip, an early-exit condition, and a validation feedback loop with the watermark written only after validation passes. The only improvement opportunity is extending verification beyond DOT examples to other edit types.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence: every step is a direct instruction with exact commands ('git log --oneline --no-merges --name-only <watermark>..HEAD', './test/docs/run_tests.sh validate') and no padding or explanation of concepts Claude already knows. It matches the 'every token earns its place' anchor.

5 / 5

Actionability

Guidance is fully executable: copy-paste-ready git commands for the watermark fallback, change gathering, and watermark write, plus the exact validation script path. Concrete edit patterns (insert rows, add sections, never edit fabro-api.yaml) cover the common cases, matching the anchor-5 example.

5 / 5

Workflow Clarity

Eight clearly sequenced steps with an early-exit checkpoint ('If nothing affects docs, tell the user and stop') and an explicit validation feedback loop ('run ./test/docs/run_tests.sh validate. Fix any failures before proceeding') before the watermark is written. It stays below anchor 5 because validation is conditional on DOT blocks only — non-DOT edits have no verification step, a minor validation gap for a batch editing workflow.

4 / 5

Progressive Disclosure

The body is a concise overview plus workflow, with the bulk mapping table correctly split into references/mapping.md (a real file, verified), clearly signaled with a linked bullet ('code-to-doc page mapping') and re-referenced at the point of use in step 3. References are one level deep and navigation is easy, matching the anchor-5 structure.

5 / 5

Total

19

/

20

Passed

Description

66%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 specific, third-person description that names the concrete mechanism (watermark commit, file-to-page mapping, surgical edits) rather than resorting to vague language. Its main weakness is the absence of any explicit 'Use when...' trigger clause, which caps completeness and slightly limits natural trigger-term coverage.

Suggestions

Add an explicit trigger clause, e.g., 'Use when documentation is stale or out of sync after recent code changes, or when the user asks to update or sync the docs.'

Include natural trigger synonyms users would actually say — 'stale docs', 'outdated documentation', 'keep docs up to date' — to broaden trigger-term coverage.

Optionally mention the validation pass (e.g., DOT example validation) to round out capability coverage for a 5-level specificity score.

DimensionReasoningScore

Specificity

The description lists several concrete actions — 'Reads git history since a watermark commit, maps changed files to doc pages, and makes surgical edits' — naming the mechanism, not just the domain. It falls short of anchor 5 only because ancillary capabilities (validation of examples, writing the watermark) are omitted, leaving minor coverage gaps.

4 / 5

Completeness

The 'what' is clear and concrete (update docs/public/ via git-history analysis, mapping, and surgical edits), but there is no 'Use when...' clause or equivalent explicit trigger guidance — 'based on recent code changes' only weakly implies when. Per the judging guidelines, a missing explicit trigger clause caps completeness at 3.

3 / 5

Trigger Term Quality

Natural terms users would say are present: 'Update documentation', 'docs', 'code changes', 'keep docs in sync with code'. A few common variations are missing (e.g., 'stale', 'outdated', 'out of date'), which keeps it below the comprehensive-synonym coverage of anchor 5 but above the sparse keyword coverage of anchor 3.

4 / 5

Distinctiveness Conflict Risk

The watermark-commit mechanism and 'surgical edits to keep docs in sync with code' carve out a distinct sync-docs-to-code niche with clear triggers. Minor overlap risk remains with general documentation-writing or commit-message skills, so it does not reach anchor 5's minimal conflict risk.

4 / 5

Total

15

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

fkukuck/fabro

Path

.claude/skills/docs/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.