update-docs-from-commits

Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

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.

The body is a well-structured, actionable seven-step workflow with concrete git/mise commands, a useful commit-to-doc mapping table, and a validation step. It is held back from top marks only by minor redundancy (the Example Usage restates the steps), a placeholder code block in Step 4, and an implicit rather than explicit validation feedback loop.

Suggestions

Make Step 4's validation feedback loop explicit: after 'mise run docs', add 'If validation reports warnings or errors, fix them and re-run mise run docs until it passes.'

Replace the empty '# Read the file' code block in Step 4 with a concrete instruction (e.g., 'cat docs/sandboxes/manage-gateways.mdx' or a note to read the file directly), or remove the block.

Trim the 'Example Usage' section since it restates the seven steps already detailed above, or reduce it to the single user prompt plus a one-line pointer to Step 1.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence — the long style-rule list in Step 5 is project-specific (Fern/OpenShell conventions) rather than general knowledge Claude already has — but the 'Example Usage' section restates the seven steps and the empty '# Read the file' block in Step 4 are minor trim opportunities, keeping it just below the top anchor.	4 / 5
Actionability	Concrete, executable commands are provided throughout (git log/show invocations, mise run docs, mise run docs:serve) plus a specific code-area-to-doc-page mapping table, but Step 4's placeholder '# Read the file' code block and the generic 'Read the full target doc page' guidance are minor gaps versus copy-paste-ready.	4 / 5
Workflow Clarity	Seven steps are clearly sequenced and Step 7 provides an explicit validation checkpoint ('Check for: Validation warnings or errors. Broken cross-references.'), avoiding the batch-operation cap; however the error-recovery feedback loop (fix and re-run mise run docs on failure) is implicit rather than spelled out, so it sits at the second-highest anchor.	4 / 5
Progressive Disclosure	Well-organized into clearly labeled sections, and it appropriately points to docs/CONTRIBUTING.mdx for the full style guide while inlining only 'Key reminders', but the bulk of guidance lives in a single inline file with no bundle references, so it does not fully match the one-level-deep split-reference ideal.	4 / 5
	Total	16 / 20 Passed

Description

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

The description is well-crafted: it clearly states what the skill does and when to use it, and supplies a rich set of natural trigger keywords with good synonym coverage. The only mild gap is specificity, where the action list is solid but not exhaustive of the full workflow.

Dimension	Reasoning	Score
Specificity	Names the domain and two concrete actions — 'Scan recent git commits for changes that affect user-facing behavior' and 'draft or update the corresponding documentation pages' — but does not enumerate the fuller workflow (mapping, verification) that the body covers, so coverage is not comprehensive.	3 / 5
Completeness	Explicitly states both what ('Scan recent git commits... then draft or update the corresponding documentation pages') and when ('Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release') with concrete trigger phrases, satisfying the top anchor.	5 / 5
Trigger Term Quality	Eight natural trigger phrases users would actually say — 'update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift' — cover the concept with strong synonym variation, matching the comprehensive-coverage anchor.	5 / 5
Distinctiveness Conflict Risk	The commit-to-docs niche is clear and the trigger keywords ('docs from commits', 'sync docs', 'docs drift', 'docs behind') are specific enough to minimize overlap with a generic docs-writing skill.	5 / 5
	Total	18 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: NVIDIA/OpenShell
Path: .agents/skills/update-docs/SKILL.md
Commit: 69a05eb

Reviewed: 1 day 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.