CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

document-release

Post-ship documentation update. Reads all project docs, cross-references the diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when asked to "update the docs", "sync documentation", or "post-ship docs". Proactively suggest after a PR is merged or code is shipped.

Quality

79%

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 ./skills/gstack/.agents/skills/gstack-document-release/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

62%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 document-release workflow itself (Steps 0-9) is excellent: concrete commands, explicit validation checkpoints, conservative stop/ask rules, and race-safe error recovery. However, roughly half the body is inlined gstack framework boilerplate (persona coaching, telemetry plumbing, onboarding prompts) that wastes tokens and buries the actual skill content in a single monolithic file with no bundle references.

Suggestions

Move the shared gstack framework sections (Preamble, Voice, AskUserQuestion Format, Completeness Principle, Contributor Mode, Completion Status Protocol, Telemetry, Plan Status Footer) into a common reference file (e.g., references/gstack-common.md) referenced with a one-line pointer, cutting ~350 lines of boilerplate from this skill's body.

Trim the CHANGELOG incident anecdote ("A real incident occurred where an agent replaced existing CHANGELOG entries...") down to the imperative rules that follow it — "Never delete, reorder, or replace entries" already carries the full instruction.

Extract the per-file audit checklists (README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md heuristics in Step 2) into a references/ file so SKILL.md stays an overview, and make the "review/TODOS-format.md" dependency unconditional by bundling it or dropping the reference.

DimensionReasoningScore

Conciseness

Roughly half of the ~712-line body is auto-generated gstack framework boilerplate — the persona/voice coaching ("You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment..."), the Boil-the-Lake effort table, telemetry opt-in dialogs, Contributor Mode, and an incident anecdote ("A real incident occurred where an agent replaced existing CHANGELOG entries...") — none of which is about updating documentation. This is noticeably verbose with several padded sections (anchor 2); it avoids anchor 1 only because the actual Steps 0-9 are dense and free of basic-concept explanations, and it is well below anchor 3 because the padding is substantial, not incidental.

2 / 5

Actionability

The workflow supplies concrete, executable commands throughout: "git diff <base>...HEAD --stat", the "find . -maxdepth 2 -name "*.md"..." discovery command, a full commit heredoc template, "gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md", and a platform-detection fallback tree covering GitHub, GitLab, and git-native paths. It falls short of anchor 5 because several commands contain unsubstituted placeholders (SKILL_NAME, OUTCOME, USED_BROWSE, <base>) and the "review/TODOS-format.md (if available)" reference is hedged, but it is well above anchor 3 since the guidance is overwhelmingly copy-paste-ready.

4 / 5

Workflow Clarity

Steps 0-9 are clearly sequenced with explicit validation checkpoints and error-recovery branches: "Empty check first: Run git status... If no documentation files were modified... exit without committing", "If gh pr edit / glab mr update fails: warn... and continue", the Step 6 cross-doc consistency pass, and the rule "Read before editing. Always read the full content of a file before modifying it." This matches anchor 5 (explicit validation, feedback paths, structured final checklist output); the batch-operation cap does not apply because validation before batch edits is abundant, and anchor 4 underrates it since checkpoints are explicit rather than minor-gap.

5 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/ directories), so everything lives in one monolithic file. Section headers (## Voice, ## Completeness Principle, ## Telemetry (run last), ## Step 1-9) provide navigable structure, but several hundred lines of shared framework content that clearly belongs in a common reference file — the file is even marked "AUTO-GENERATED from SKILL.md.tmpl" — are inlined directly. That matches anchor 3 (structure present, but content that should be separate is inline); not anchor 2 because headers do make it navigable, and not anchor 4 because the inlined boilerplate is a major organization gap, not a minor one.

3 / 5

Total

14

/

20

Passed

Description

88%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: it enumerates concrete capabilities with named files, uses third person, and provides explicit trigger phrases plus proactive timing guidance. The only weaknesses are a few missing natural synonyms (README, changelog, "docs are out of date") and the slightly generic "update the docs" trigger creating minor overlap risk with general docs skills.

DimensionReasoningScore

Specificity

"Reads all project docs, cross-references the diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION" lists multiple concrete actions with named target files, comprehensively covering the post-ship docs domain. It matches anchor 5 rather than 4 because coverage is comprehensive with no minor gaps, and it is written in third person ("Reads", "updates", "polishes") so no voice penalty applies.

5 / 5

Completeness

Both questions are answered explicitly: the "what" is a detailed action list, and the "when" is "Use when asked to 'update the docs', 'sync documentation', or 'post-ship docs'" with concrete trigger phrases plus proactive timing guidance. This matches anchor 5 rather than 4 because the "when" clause is explicit and specific, not merely present or implied.

5 / 5

Trigger Term Quality

"Use when asked to 'update the docs', 'sync documentation', or 'post-ship docs'" plus "Proactively suggest after a PR is merged or code is shipped" are natural phrases a user would actually say. It sits at anchor 4 rather than 5 because common variations like "update the README", "changelog", or "docs are out of date" are missing, and above anchor 3 because the quoted triggers are exactly the phrases users naturally use.

4 / 5

Distinctiveness Conflict Risk

"Post-ship documentation update" tied to the diff and "after a PR is merged or code is shipped" carve a distinct niche, but the trigger "update the docs" is generic enough that a general documentation or changelog skill could also claim it. That is minor overlap risk with closely related skills (anchor 4), not the minimal-conflict clarity of anchor 5 nor the broad overlap of anchor 3.

4 / 5

Total

18

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (712 lines); consider splitting into references/ and linking

Warning

Total

15

/

16

Passed

Repository

valeriibeck-star/claude-skills

Path

skills/gstack/.agents/skills/gstack-document-release/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.