CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

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 ./.agents/skills/update-docs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

63%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-sequenced, highly actionable workflow with real validation steps, undermined by token inefficiency: the skill points to docs/CONTRIBUTING.mdx as the authoritative style guide and then re-inlines most of it, and one step ships a placeholder code block instead of an actual command.

Suggestions

Trim Step 5's style-rule list to the handful of non-obvious, OpenShell/Fern-specific reminders and rely on the already-mandated docs/CONTRIBUTING.mdx for the rest (or move the full list to a references/style-reminders.md file and link to it).

Replace the Step 4 placeholder bash block ("# Read the file") with the actual action, e.g. instruct reading the full target doc page with the Read tool before identifying where new content fits.

Make the Step 7 validation loop explicit: if mise run docs or mise run test:docs-website reports warnings, broken cross-references, or redirect errors, fix them and re-run until clean before presenting results.

DimensionReasoningScore

Conciseness

Prerequisites mandates reading docs/CONTRIBUTING.mdx ("It contains the current style guide and formatting rules") yet Step 5 re-inlines roughly 25 style bullets duplicating that file, including rules Claude already knows ("Active voice, present tense, second person", "No superlatives"). The mapping table and commands are otherwise dense and efficient, so this sits between efficient and noticeably verbose.

3 / 5

Actionability

Concrete executable commands throughout (git log v0.2.0..HEAD --oneline --no-merges, git show <commit-hash> --stat, mise run docs, mise run test:docs-website), but Step 4's bash block contains only the placeholder comment "# Read the file" with no actual command, and the default "commits since the head of the main branch" is ambiguous. These are minor gaps, not missing specifics.

4 / 5

Workflow Clarity

A clear 7-step sequence with an explicit validation step (Step 7: run mise run docs, check for "Validation warnings or errors" and "Broken cross-references") and redirect verification, so the batch-operation cap does not apply. It falls short of anchor 5 only because the fix-and-retry loop is implicit: it says to check for errors but never instructs fixing and re-running on failure.

4 / 5

Progressive Disclosure

The body is well-sectioned and there is no bundle directory, but the ~30-line Step 5 style-rule block duplicates docs/CONTRIBUTING.mdx and is content that should be either left to that referenced file or moved to a references/ file. This matches the anchor where structure exists but content that should be separate is inline.

3 / 5

Total

14

/

20

Passed

Description

91%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: concrete actions, explicit use-when conditions, and a rich set of natural trigger synonyms. The only weakness is that a few trigger phrases are generic enough to overlap with plain doc-editing requests.

DimensionReasoningScore

Specificity

"Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages" lists several concrete actions (scan, filter to user-facing changes, draft, update), matching the minor-gaps anchor rather than the comprehensive anchor 5 since it omits workflow stages like mapping and verification.

4 / 5

Completeness

Explicitly answers 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"), plus concrete trigger phrases, matching the anchor-5 example structure.

5 / 5

Trigger Term Quality

"update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift" is comprehensive natural-phrase coverage with multiple synonyms; this domain has no file extensions for the anchor-5 clause to cover, and nothing natural is clearly missing.

5 / 5

Distinctiveness Conflict Risk

The commit-to-docs-sync niche is distinct, but generic triggers like "update docs" and "draft docs" could fire for ordinary single-page doc edit requests where commit scanning is not wanted, giving minor overlap risk with general doc-editing skills.

4 / 5

Total

18

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

Total

14

/

16

Passed

Repository

NVIDIA/OpenShell

Path

.agents/skills/update-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.