CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

api-ref-tone

Tone of voice guidance for Highcharts API reference doclets - covering sentence structure, vocabulary, and phrasing patterns for public-facing TS doclets.

Quality

86%

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

96%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.

An exemplary instruction-only skill: every section carries non-obvious, Highcharts-specific conventions with concrete examples, and the wrong/right table doubles as a validation checklist. The only notable gap is that the single external reference (`ts/DOCLETS.md`) does not exist within the skill bundle, leaving navigation dependent on the surrounding repository.

DimensionReasoningScore

Conciseness

The body is dense, table-driven, and contains exclusively Highcharts-specific conventions Claude cannot be assumed to know (opening-sentence patterns per member type, 'Whether' vs 'Enable or disable', preferred vocabulary, wrong/right pairs). It matches 'lean and efficient; assumes Claude's competence; every token earns its place' — there is no generic filler or explanation of concepts Claude already knows, so it is not 4.

5 / 5

Actionability

Every rule is paired with a concrete before/after example: pattern-per-member-type table ('Fires when a point is clicked.'), vocabulary substitutions ('Returns' not 'Gives back'), and a wrong/right mistakes table ('This property contains the current height.' → 'The current pixel height of the chart.'). This is copy-paste-ready guidance for the common doclet cases; per the rubric's code-vs-instruction note, the absence of code is not penalized for an instruction-only skill whose guidance is this specific, so it is not 4.

5 / 5

Workflow Clarity

This is a simple, single-purpose skill (apply tone conventions when writing a doclet) whose single action is unambiguous: pick the opening pattern by member type, apply the vocabulary rules, and check the result against the mistakes table. The 'Common mistakes to avoid' table functions as an explicit validation checklist and the multi-sentence structure section sequences edge cases → defaults → cross-references, which clears the simple-skill bar of 5 rather than the 4 anchor.

5 / 5

Progressive Disclosure

The body is a single well-organized file (~97 lines) with a clearly signaled, one-level-deep split: 'Read `ts/DOCLETS.md` for tag syntax, formatting rules, and tooling' cleanly delegates non-tone material. It does not reach 5 because no bundle directory (references/, scripts/, assets/) exists alongside SKILL.md, so the referenced `ts/DOCLETS.md` is not resolvable within the skill bundle — navigation depends on an external repo path; it is above 3 because structure, signaling, and split of concerns are otherwise good.

4 / 5

Total

19

/

20

Passed

Description

70%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 distinct, well-scoped description with concrete coverage areas, but it is missing any 'Use when...' trigger clause and a few natural synonyms (JSDoc, TSDoc, documentation, wording). The what is clear; the when is entirely implicit.

Suggestions

Add an explicit trigger clause, e.g. 'Use when writing or reviewing JSDoc/TSDoc doclets for Highcharts TypeScript members, or when the user mentions API reference docs, doclet wording, or documentation tone.'

Include natural synonyms users would actually say — 'JSDoc', 'TSDoc', 'API documentation', 'doclet wording', 'style guide' — alongside the current terminology.

State concrete actions (write, review, rewrite doclets) rather than only listing the aspects covered, to strengthen the specificity of capabilities.

DimensionReasoningScore

Specificity

The description names the domain ('Tone of voice guidance for Highcharts API reference doclets') and lists several concrete coverage areas ('sentence structure, vocabulary, and phrasing patterns for public-facing TS doclets'), which matches the 'lists several specific items; minor gaps' anchor. It falls short of 5 because it describes scope rather than concrete actions (e.g., writing or reviewing doclets), and is above 3 because it enumerates multiple specific facets rather than just 1-2.

4 / 5

Completeness

The 'what' is clearly stated (tone guidance covering sentence structure, vocabulary, and phrasing for TS doclets), but there is no 'Use when...' clause or any equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 4 because the 'when' is entirely absent rather than merely under-specified, and it is above 2 because the 'what' half is concrete and complete.

3 / 5

Trigger Term Quality

Natural terms a user would say are present ('tone of voice', 'sentence structure', 'vocabulary', 'phrasing patterns', 'API reference', 'Highcharts'), fitting the 'good keyword coverage; a few natural terms missing' anchor. It is not 5 because common synonyms and formats users would actually use are absent — 'JSDoc', 'TSDoc', 'documentation', 'API docs', 'wording', 'style guide' — and it is above 3 because the included keywords are specific and natural rather than generic.

4 / 5

Distinctiveness Conflict Risk

The description is tightly scoped to 'Highcharts API reference doclets' and 'public-facing TS doclets', a clear niche with distinct triggers and minimal overlap with general writing or documentation skills. It clearly matches the 'clear niche with distinct triggers; minimal conflict risk' anchor and not the 4 anchor, which requires minor overlap risk with closely related skills.

5 / 5

Total

16

/

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

highcharts/highcharts

Path

.agents/skills/api-ref-tone/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.