CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

gsd-docs-update

Generate or update project documentation verified against the codebase

Quality

61%

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

Quality

Content

53%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 deliberately thin Pi-host wrapper that delegates the real workflow to an external file, with strong fail-closed dispatch semantics and clear flag-handling rules. Its main weaknesses are redundant flag-handling instructions repeated across the objective and context sections, and the fact that the single workflow reference is an unresolved placeholder path, so the skill body alone cannot drive execution.

Suggestions

Consolidate the flag rules: state the active/inactive derivation and --force precedence once (either in <objective> or <context>) instead of repeating them across three bullet groups.

Inline a minimal execution skeleton (phase order, the 9 doc types, what preservation_check and wave execution mean) so the skill degrades gracefully if the external workflow file fails to resolve, and so the batch/destructive flow has visible validation checkpoints.

Replace or supplement the "__GSD_PI_ENGINE_ROOT__" placeholder with a resolvable path (or copy the workflow into references/) so the one-level-deep reference is followable within the installed skill bundle.

DimensionReasoningScore

Conciseness

The Pi-dispatch and Pi-includes sections are tight and necessary, but the flag-inactivity rules are stated three times: the objective's six-bullet "Flag handling rule", the context's two flag bullets, and the context's "Do not infer that a flag is active just because it is documented in this prompt" bullets. Mostly efficient, but the duplicated flag semantics should be consolidated into one section.

3 / 5

Actionability

Dispatch guidance is concrete and executable (call gsd_dispatch with role and task, fail-closed on unresolved role or child failure, --force/--verify-only precedence), but the core execution workflow lives entirely in the external "@__GSD_PI_ENGINE_ROOT__/gsd-core/workflows/docs-update.md" reference, so the body itself is missing the specific steps (doc types, wave execution, preservation prompts) needed to execute. Some concrete guidance, incomplete on its own.

3 / 5

Workflow Clarity

The body sequences only two steps (read execution_context files, then follow the workflow) and names the gates to preserve ("preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting") without defining or ordering them; validation checkpoints are delegated to the external file. The skill is a batch, partially destructive operation (up to 9 docs, --force overwrites, commit), which caps workflow clarity at 3.

3 / 5

Progressive Disclosure

The body is a well-organized thin overview with clearly labeled sections (objective, execution_context, context, process) and a single, clearly signaled, one-level-deep reference under <execution_context>. It falls short of 5 because that reference is a "__GSD_PI_ENGINE_ROOT__" template placeholder that does not resolve to a real file within this skill bundle (no references/ directory exists), leaving navigation dependent on install-time substitution.

4 / 5

Total

13

/

20

Passed

Description

50%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 concise and states a clear, specific capability (generate/update codebase-verified documentation) in third person, but it is incomplete: it gives no trigger guidance for when to use the skill and omits natural keyword variations users would type. It reads as a competent one-line summary rather than a full activation description.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to generate, update, or verify project docs (README, API docs, architecture docs) against the codebase."

Include natural synonyms and concrete doc types ("docs", "README", "API reference", "architecture documentation") so the description matches what users actually say.

Mention the verification capability as a distinct action (e.g. "check existing docs for accuracy against the codebase") to broaden action coverage and distinguish it from plain doc-generation skills.

DimensionReasoningScore

Specificity

"Generate or update project documentation" names the domain with two concrete actions, and "verified against the codebase" is a verification qualifier rather than a separately stated action; no doc types or coverage details are given, matching the '1-2 concrete actions, not comprehensive' anchor. It does not reach 4 because it lacks the several distinct verb-object actions that anchor expects.

3 / 5

Completeness

The description clearly answers "what" ("Generate or update project documentation verified against the codebase") but contains no "when" — no "Use when..." clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 2 because the "what" is clear and specific, not vague.

3 / 5

Trigger Term Quality

"project documentation" is a relevant keyword users would naturally say, but common variations and synonyms ("docs", "README", "API docs", "update the docs") are absent. It clears anchor 2 because "documentation" is domain-specific rather than generic, but misses the fuller keyword coverage of anchor 4.

3 / 5

Distinctiveness Conflict Risk

"verified against the codebase" carves out a codebase-grounded niche, but "Generate or update project documentation" is broad enough to overlap with generic documentation, README, and doc-generation skills. It is somewhat specific with residual overlap risk, fitting anchor 3 rather than the mostly-distinct anchor 4.

3 / 5

Total

12

/

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

open-gsd/gsd-core

Path

pi/package-skills/gsd-docs-update/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.