update-docs

Audit and update documentation after code changes. Use when architecture, APIs, or behavior changed and docs may have drifted.

1.00x

Quality

76%

Does it follow best practices?

Impact

100%

1.00x

Average score across 1 eval scenario

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/update-docs/SKILL.md

Quality

Content

75%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-structured, actionable skill body with concrete commands, a useful drift checklist, and a validation step. The main gaps are a verbatim repeated note and a missing lint-failure feedback loop.

Suggestions

De-duplicate the query_language.md CI-sync note: state it once in 'What drifts most' and reference it from 'Fixing' step 6 rather than repeating it verbatim.

Add an explicit feedback loop after step 4: 'If lint:docs fails, fix the reported issues and re-run until it passes' to reach full workflow clarity.

Tighten the core fixing loop (steps 1-3) with a concrete example of diffing a doc against its code, e.g. a grep/diff command, to lift actionability.

Dimension	Reasoning	Score
Conciseness	The body is lean, uses tables and short bullets, and avoids explaining concepts Claude already knows; the CI byte-equal sync note for query_language.md is repeated near-verbatim in both 'What drifts most' and 'Fixing', a minor instance of over-explanation that could be trimmed.	4 / 5
Actionability	Provides concrete executable commands (git log, glab issue/mr list, mise run lint:docs) and a precise file-location table, but the core 'Read the stale doc / Read the code / Edit the doc' loop stays high-level, leaving minor gaps.	4 / 5
Workflow Clarity	The 'Fixing' section is a clear numbered sequence with an explicit validation checkpoint (run lint:docs) and conditional mirroring to AGENTS.md; not a 5 because there is no explicit error-recovery feedback loop (what to do if lint fails).	4 / 5
Progressive Disclosure	Well-organized into clearly headed sections (Where to look, Gathering context, What drifts most, Fixing, Self-improvement) with no nested references and a single self-contained file; not a 5 because a couple of sections (orbit CI-sync notes, the drifts list) run slightly dense for an overview.	4 / 5
	Total	16 / 20 Passed

Description

78%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 concise, well-formed description that explicitly answers both what it does and when to use it with natural trigger phrases. Minor room to expand the action list and tighten distinctiveness.

Dimension	Reasoning	Score
Specificity	Names the domain ('documentation after code changes') and two concrete actions ('Audit and update'), matching the score-3 anchor of 1-2 concrete actions without comprehensive coverage; not a 4 because only two high-level actions are listed.	3 / 5
Completeness	Clearly states what ('Audit and update documentation after code changes') and an explicit when with concrete triggers ('Use when architecture, APIs, or behavior changed and docs may have drifted'), matching the score-5 anchor.	5 / 5
Trigger Term Quality	Phrases like 'architecture, APIs, or behavior changed' and 'docs may have drifted' are natural things a developer would say, giving good keyword coverage; not a 5 because common variations/synonyms are not exhaustively covered.	4 / 5
Distinctiveness Conflict Risk	The post-code-change docs-maintenance niche with specific drift triggers is mostly distinct with only minor overlap risk against general editing skills; not a 5 because 'documentation' as a noun is broad.	4 / 5
	Total	16 / 20 Passed

Validation

87%

Warnings & errors only

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

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
referenced_paths_exist	Referenced path issues: 5 missing	Warning

	Total	14 / 16 Passed

Repository: gitlabhq/orbit-knowledge-graph
Path: .claude/skills/update-docs/SKILL.md
Commit: a2b60b1

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.