CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

common-documentation

Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.

69

1.14x
Quality

80%

Does it follow best practices?

Impact

100%

1.14x

1 of 3 eval scenarios. Add 2 more for a full score.

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/common/common-documentation/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

71%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 concise, well-sectioned instruction skill with mostly concrete directives and no wasted concept explanations. Its main weaknesses are an orphaned bundle reference that is never surfaced from the body, a few ambiguous one-liner directives, and the odd 'Canonical response anchors' section that duplicates content without clear purpose.

Suggestions

Link the existing references/implementation.md from the body (e.g., under 'Intent-First Comments': 'See [implementation.md](references/implementation.md) for good/bad comment examples') so the bundle file is discoverable instead of orphaned.

Replace ambiguous one-liners like 'Sync: Documentation ships with feature' with a concrete directive, e.g. 'Update the affected README/ADR section in the same commit as the feature change.'

Fold the 'Canonical response anchors' section (JSDoc, Usage, why) into the relevant sections or remove it — it restates terms already covered without adding guidance.

DimensionReasoningScore

Conciseness

The body is lean, bullet-style guidance ('Delete commented-out code. Use Git history.') with no explanation of concepts Claude already knows, but the 'Canonical response anchors' section and filler items like 'Sync: Documentation ships with feature' spend tokens without adding guidance — minor trimmable padding, so 4 rather than 5.

4 / 5

Actionability

Mostly concrete directives: 'Format: `TODO(username): description`. Link tickets.', 'Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for public members', 'Use Swagger/OpenAPI for REST', 'Document rationale ... in `docs/adr/`'. A few items describe rather than instruct ('Define contract before implementation', 'Provide copy-pasteable examples for endpoints'), so it sits at 4 rather than fully executable coverage.

4 / 5

Workflow Clarity

This is an instruction-only standards skill under 50 lines with no multi-step process and no destructive or batch operations, so the simple-skill exception applies: per-topic sections with an Anti-Patterns do/don't contrast are mostly unambiguous. It is not 5 because some one-line directives ('Sync: Documentation ships with feature') give no concrete application steps.

4 / 5

Progressive Disclosure

The bundle provides references/implementation.md (a good/bad intent-first comment example), but the body never mentions or links it — a buried reference, matching the 'references present but not clearly signaled' anchor exactly. The body itself is well-organized under 50 lines, which keeps it above the minimal-structure 2 anchor.

3 / 5

Total

15

/

20

Passed

Description

83%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 with a clear what-and-when structure and natural trigger phrases covering comments, docstrings, READMEs, and documentation. Main gaps are missing common synonyms (e.g., 'docs', 'API docs', 'ADR') and a slightly broad catch-all trigger.

DimensionReasoningScore

Specificity

Names the domain and several concrete actions ('Write effective code comments, READMEs, and technical documentation', 'writing docstrings') with minor gaps; 'effective' and 'following intent-first principles' are mildly abstract, keeping it below the comprehensive coverage of the 5 anchor and clearly above the 1-2-action 3 anchor.

4 / 5

Completeness

Explicitly answers both: what ('Write effective code comments, READMEs, and technical documentation following intent-first principles') and when ('Use when adding comments, writing docstrings, creating READMEs, or updating any documentation') with concrete trigger phrases — a direct match to the 5 anchor.

5 / 5

Trigger Term Quality

'comments', 'docstrings', 'READMEs', and 'documentation' are natural phrases users would say, but common synonyms and variations ('docs', 'API docs', 'ADR') are missing — good coverage with a few natural terms absent, not the comprehensive synonym coverage of the 5 anchor.

4 / 5

Distinctiveness Conflict Risk

Documentation writing is a clear, mostly distinct niche, but the broad tail 'or updating any documentation' plus generic 'comments' leaves minor overlap risk with adjacent doc-related skills — mostly distinct rather than minimal conflict risk.

4 / 5

Total

17

/

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

HoangNguyen0403/agent-skills-standard

Path

.github/skills/common/common-documentation/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.