CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-standards

Microsoft Style Guide + Squad-specific documentation patterns

Quality

74%

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 ./.squad-templates/skills/docs-standards/SKILL.md

The canonical home for this skill is docs-standards in github/gh-aw

SKILL.md
Quality
Evals
Security

Quality

Content

93%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 lean, highly actionable standards reference: rules are given in compact do/don't form with a full correct/incorrect example pair and a precise test-sync rule. The only gap is a missing explicit verification step after updating test assertions, which keeps workflow clarity just below top marks.

Suggestions

Add a verification step to the Test Sync Rule, e.g., "Run the docs build tests to confirm EXPECTED_* assertions pass before committing."

DimensionReasoningScore

Conciseness

Every rule is compressed to a one-line do/don't form ("Sentence-case headings: 'Getting started' not 'Getting Started'") with no explanation of what the Microsoft Style Guide is or how style guides work; the single Context sentence is project-specific rationale rather than padding. This matches anchor 5 ("Lean and efficient; assumes Claude's competence; every token earns its place").

5 / 5

Actionability

Guidance is fully concrete: each rule pairs the correct and incorrect form, the Structure section prescribes an exact page order (Title → Warning → Try this code → Overview → HR → H2 sections), the Test Sync Rule names the exact file and identifiers (test/docs-build.test.ts, EXPECTED_* arrays), and the Examples section shows a complete correct/incorrect pair. For an instruction-only skill this matches anchor 5 (specific guidance covering the common cases).

5 / 5

Workflow Clarity

The Structure section sequences a docs page unambiguously and the Test Sync Rule is a concrete same-commit rule, but there is no explicit verification checkpoint (e.g., "run the docs build/test to confirm assertions pass"). This matches anchor 4 ("Clear sequence with most checkpoints present; minor validation gaps") rather than 5, which requires an explicit validate-then-proceed step.

4 / 5

Progressive Disclosure

This is a self-contained skill with no bundle files (no references/, scripts/, or assets/ directories exist) and no need for external references; the body is organized into well-labeled sections (Context, Patterns, Structure, Test Sync Rule, Examples, Anti-Patterns). Per the simple-skill guidance this matches anchor 5 with just well-organized sections.

5 / 5

Total

19

/

20

Passed

Description

45%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 identifies a clear domain but is a label, not a capability statement: it names no actions, includes no "use when" trigger guidance, and offers few natural keywords. Adding concrete actions (e.g., "Apply...", "Review docs against...") and an explicit trigger clause would move it into the 4-5 range.

Suggestions

Add concrete action verbs, e.g., "Applies Microsoft Style Guide rules (sentence-case headings, active voice, second person) and Squad-specific page structure to documentation review and editing."

Append an explicit trigger clause, e.g., "Use when writing, editing, or reviewing Squad documentation pages, or when the user mentions docs style, the Microsoft Style Guide, or EXPECTED_* test assertions."

Include natural trigger synonyms users would actually say ("docs", "documentation style", "style guide", "headings", "tone") to improve keyword coverage.

DimensionReasoningScore

Specificity

The description names the domain ("Microsoft Style Guide + Squad-specific documentation patterns") but lists no concrete actions at all — no verbs describing what the skill does. This matches anchor 2 ("Names the domain but actions are minimal or generic"); it is above anchor 1 because the domain is clearly identified, and below anchor 3 because no specific actions are enumerated.

2 / 5

Completeness

The "what" is identifiable (documentation style conventions per the Microsoft Style Guide plus Squad-specific patterns) but there is no "Use when..." clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It does not fall to 2 because the "what" is not vague, and cannot reach 4 without any "when" language.

3 / 5

Trigger Term Quality

"Microsoft Style Guide", "documentation", and "patterns" are somewhat relevant keywords, but common natural variations users would say ("docs", "editing docs", "writing style", "tone") are missing. This matches anchor 3 ("Some relevant keywords but missing common variations or synonyms"), below anchor 4 because keyword coverage is thin rather than good.

3 / 5

Distinctiveness Conflict Risk

"Microsoft Style Guide" and "Squad-specific" carve out a recognizable niche, but with no trigger terms the description could still fire on general documentation or style questions. This matches anchor 3 ("Somewhat specific but could still overlap with similar skills"), below anchor 4 because the lack of explicit triggers leaves moderate overlap risk.

3 / 5

Total

11

/

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

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

bradygaster/squad

Path

.squad-templates/skills/docs-standards/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.