CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

update-docs

Handle documentation-only tasks such as README quickstarts, guides, FAQs, and prose or comment edits that do not change application behavior. Use for new documentation sections too. Application code bugs and features belong to fix-the-ticket.

Quality

82%

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

SKILL.md
Quality
Evals
Security

Quality

Content

78%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 lean, well-scoped instruction-only skill that makes every token count and handles scope decisions (ticket naming, branch protection, fix-the-ticket redirect) crisply. Its weakness is actionability: the validation checklist names what to check but gives no commands or concrete methods for checking formatting, links, or accuracy.

Suggestions

Add one or two concrete validation commands (e.g., a markdown link-check one-liner or 'run the repo's docs linter if configured') so the 'check formatting, links, examples and accuracy' step is executable rather than just named.

Define what "validation" encompasses in 'finish after validation' — e.g., 'validation = the formatting/links/examples/accuracy check above passes' — so the exit condition is unambiguous.

Optionally number the flow (edit → validate → branch/commit/PR per repo policy) so the sequence and the conditional 'edit-only' exit path are scannable at a glance.

DimensionReasoningScore

Conciseness

Nine lean lines with zero padding and no explanation of concepts Claude already knows; every sentence carries actionable guidance (e.g., "Do not invoke code-review polling solely because the request is called a ticket").

5 / 5

Actionability

Guidance names concrete validation targets ("check formatting, links, examples and accuracy") and clear policy directives, but contains no commands or specifics on how to execute them — link checking, formatting validation, and the referenced "validation" step are never operationalized.

3 / 5

Workflow Clarity

As a simple single-task skill the flow is clear — edit, then check formatting/links/examples/accuracy, then follow the repo's contribution policy for branching/committing/PRs, finishing after validation — with an explicit validation checkpoint, though steps are prose rather than sequenced and the git workflow is delegated to repo policy.

4 / 5

Progressive Disclosure

Under 50 lines with no need for external references (no bundle files exist) and nothing that belongs in a separate file inlined; the two focused paragraphs are well-organized for a skill of this size, qualifying for the simple-skill exception.

5 / 5

Total

17

/

20

Passed

Description

78%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, third-person description with concrete task examples, natural trigger terms, and excellent boundary marking against the sibling fix-the-ticket skill. Its main weakness is the narrow "Use for new documentation sections too" clause, which could be a broader, more explicit "Use when..." trigger statement.

DimensionReasoningScore

Specificity

The description lists several concrete task types ("README quickstarts, guides, FAQs, and prose or comment edits", "new documentation sections"), but the governing verb is a single generic "Handle" rather than multiple distinct concrete actions, matching the 'several specific actions; minor gaps' anchor rather than comprehensive coverage.

4 / 5

Completeness

Both "what" (documentation-only tasks with a concrete list) and "when" are present — "Use for new documentation sections too" plus the boundary "that do not change application behavior" — but the trigger clause is narrow (only new sections) rather than a general "Use when..." phrasing, matching the anchor where "when" could be more explicit.

4 / 5

Trigger Term Quality

Good natural keyword coverage ("README", "quickstarts", "guides", "FAQs", "comment edits") that users would plausibly say, but common synonyms like "docs", "tutorials", or "user guides" are missing, so it falls short of comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

Clear niche (documentation-only work) with an explicit redirect boundary — "Application code bugs and features belong to fix-the-ticket" — giving it distinct triggers and minimal conflict risk with sibling skills.

5 / 5

Total

17

/

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

jbaruch/skill-issue-policy

Path

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.