update-docs

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

1.03x

Quality

73%

Does it follow best practices?

Impact

95%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/update-docs/SKILL.md

Quality

Discovery

67%

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 is a competent description that clearly communicates both purpose and trigger conditions. Its main weakness is a lack of specificity in the concrete actions performed (e.g., what kinds of docs are updated, what the audit entails) and missing some natural trigger terms users might use. The explicit 'Use when' clause is a strength.

Suggestions

Add more specific concrete actions, e.g., 'Audit and update READMEs, API references, architecture diagrams, and inline docstrings after code changes.'

Expand trigger terms to include common user phrases like 'outdated docs', 'stale documentation', 'sync docs', 'README update', 'docstrings'.

Dimension	Reasoning	Score
Specificity	Names the domain (documentation) and some actions ('audit and update'), but doesn't list specific concrete actions like 'update API references, sync README with new endpoints, flag stale architecture diagrams'.	2 / 3
Completeness	Clearly answers both 'what' (audit and update documentation after code changes) and 'when' (when architecture, APIs, or behavior changed and docs may have drifted), with an explicit 'Use when' clause.	3 / 3
Trigger Term Quality	Includes relevant terms like 'documentation', 'code changes', 'APIs', 'architecture', and 'docs', but misses common user variations like 'README', 'docstrings', 'outdated docs', 'stale documentation', or 'sync docs'.	2 / 3
Distinctiveness Conflict Risk	Reasonably specific to documentation drift after code changes, but could overlap with general documentation generation skills or code review skills that also touch on docs. The 'drifted' concept helps distinguish it somewhat.	2 / 3
	Total	9 / 12 Passed

Implementation

79%

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

This is a strong, project-specific skill that provides actionable guidance for documentation auditing. Its main strengths are conciseness, domain-specific file paths and commands, and a clear table of documentation locations. The workflow could benefit from explicit error-recovery steps after validation, and the progressive disclosure is adequate but could be improved with supporting reference files for the more detailed sections.

Suggestions

Add an explicit feedback loop after `mise run lint:docs` — e.g., 'If linting fails, fix the reported issues and re-run before committing.'

Consider extracting the 'What drifts most' checklist into a separate reference file that can be independently maintained and extended.

Dimension	Reasoning	Score
Conciseness	The skill is lean and efficient. It doesn't explain what documentation drift is in abstract terms—it jumps straight to where to look, what drifts, and how to fix it. Every section earns its place with project-specific knowledge Claude wouldn't have.	3 / 3
Actionability	Provides concrete shell commands for gathering context (git log, glab), specific file paths to check, a concrete lint command for validation, and explicit mirroring instructions for CLAUDE.md/AGENTS.md. The guidance is specific and directly executable.	3 / 3
Workflow Clarity	The 'Fixing' section provides a clear 6-step sequence with a validation step (lint:docs) and a conditional mirror step. However, there's no explicit feedback loop for what to do if linting fails, and the overall workflow from 'Gathering context' to 'Fixing' could be more explicitly sequenced as a unified process with checkpoints.	2 / 3
Progressive Disclosure	The content is well-organized with clear sections and a useful table, but it's all inline in a single file. Given the breadth of locations and drift patterns covered, some content (e.g., the detailed orbit skill update process, or per-location checklists) could benefit from being split into referenced files. However, no bundle files exist to support this, and the skill is not excessively long.	2 / 3
	Total	10 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	10 / 11 Passed

Repository: gitlabhq/orbit-knowledge-graph
Commit: f5efc36

Reviewed: 2 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.