CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

awesome-docs

Generate, convert, and maintain animated GitHub-safe Markdown documents with animated SVG diagrams. Covers four SVG patterns (architecture flow, lifecycle loop, field carousel, timeline phases), guided interview for any doc type (README, architecture guide, runbook, API reference, tutorial, RFC, post-mortem, how-it-works, or custom), converting existing plain Markdown, diffing for stale diagrams, quality auditing, local preview, and multi-platform export. Use when asked to "create a README for X", "write an architecture doc", "animate this guide", "convert my doc to animated", "check if my diagrams are stale", or "export my doc for Confluence".

Quality

80%

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 ./plugins/platform-skills/skills/awesome-docs/SKILL.md

The canonical home for this skill is awesome-docs in nitinjain999/platform-skills

SKILL.md
Quality
Evals
Security

Quality

Content

65%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 well-organized, lean, six-mode skill body with genuinely executable commands, naming conventions, and confirmation checkpoints. Two structural issues hold it back: every SVG-generation step delegates to `references/awesome-docs.md`, which is absent from the bundle, and the batch/auto-commit workflows lack validation steps, capping workflow clarity per the rubric.

Suggestions

Ship `references/awesome-docs.md` (or inline minimal SVG blueprint skeletons for each pattern): it is cited six times as the location of all SVG blueprints, the Theme System, and the Quality Checklist, but no references/ directory exists in the bundle.

Add a validation step to batch/destructive paths — e.g. after batch convert, verify every inserted `<img src="assets/...">` resolves to an existing file (or run the audit checklist) before the single commit, mirroring the interactive modes' confirmation checkpoints.

Reconcile the description with the body: the frontmatter says "four SVG patterns" while the content defines six (arch-flow, lifecycle-loop, sequence-diagram, state-machine, field-carousel, timeline-phases).

DimensionReasoningScore

Conciseness

The body is dense and operational — a compact doc-type section map table, exact naming conventions (`assets/<topic-slug>-<pattern>.svg`), and ready-made commit commands — with no explanation of concepts Claude already knows. Minor over-explanation: the preview mode spells out per-OS browser-open commands (macOS/Linux/Windows) and repeats the preview URL in consecutive steps, and the confirm-before-continue phrasing is restated across modes. Not 5 because those spots could be trimmed; not 3 because padding is genuinely minor.

4 / 5

Actionability

Mostly executable: `git add <output-path> assets/ && git commit -m "docs(<scope>): add <doc-type> for <topic>"`, `python3 -m http.server 8080 --directory .`, `find <dir> -name "*.md"`, the svgexport loop, and a complete doc-type→SVG-pattern mapping table. Not 5 because the core action — "Generate the SVG using the blueprint in `references/awesome-docs.md`" — delegates the actual SVG construction to a file that is not present in the bundle, leaving the central generation step without concrete guidance; not 3 because every other instruction is specific and executable as written.

4 / 5

Workflow Clarity

Sequences are clearly numbered and interactive modes have explicit checkpoints ("Only proceed after explicit confirmation", "confirm before writing"), which alone would be anchor-4/5 quality. However, convert's batch mode ("skip confirmation in batch mode, process all automatically" followed by a single commit) and the auto-commit steps involve batch/destructive operations with no validation or verification step — only a post-hoc summary table — so the rubric's batch-operations cap applies. Not 4 because the cap takes precedence; not 2 because sequencing and interactive checkpoints are otherwise well defined.

3 / 5

Progressive Disclosure

The SKILL.md-as-overview pattern is right — six clearly separated modes and a single well-signaled reference ("If you need deeper context on SVG patterns, theme configuration, or the quality checklist, load `references/awesome-docs.md`") one level deep. But no `references/` directory (or any bundle file) exists, so the file cited six times — which holds all SVG blueprints, the Theme System, and the Quality Checklist — is a dangling reference, and the audit mode's instruction to check that file's checklist is only rescuable because its items are also inlined. Not 4 because a core reference is broken in the actual bundle; not 2 because SKILL.md itself is well structured, not monolithic, and does inline the essential mode logic.

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: third-person voice, concrete capabilities enumerated for all six modes, and an explicit 'Use when' clause with natural quoted trigger phrases. The only weaknesses are a few missing synonyms/file extensions in the trigger list and two generic doc-creation triggers that could over-fire for non-animated requests.

DimensionReasoningScore

Specificity

"Generate, convert, and maintain animated GitHub-safe Markdown documents", "converting existing plain Markdown, diffing for stale diagrams, quality auditing, local preview, and multi-platform export" — multiple concrete actions covering all six modes with specific objects (SVG patterns, doc types, Markdown), matching the comprehensive-coverage anchor. Not 4 because no meaningful capability area of the skill is left unlisted.

5 / 5

Completeness

Explicitly answers both questions: a detailed 'what' ("Covers four SVG patterns (architecture flow, lifecycle loop, field carousel, timeline phases), guided interview for any doc type..., diffing for stale diagrams, quality auditing, local preview, and multi-platform export") and an explicit 'when' with six concrete trigger phrases ("Use when asked to..."). This matches the anchor-5 example structure exactly; not 4 because neither 'what' nor 'when' could be more explicit.

5 / 5

Trigger Term Quality

Natural quoted trigger phrases cover every mode: "create a README for X", "animate this guide", "convert my doc to animated", "check if my diagrams are stale", "export my doc for Confluence". Not 5 because common synonyms and file extensions are missing (e.g. ".md", "add diagrams to", "make a doc", "documentation"); not 3 because the phrases given are exactly what users would naturally say.

4 / 5

Distinctiveness Conflict Risk

"animated GitHub-safe Markdown documents with animated SVG diagrams" and "diffing for stale diagrams" carve a clear niche with minimal overlap. Not 5 because two triggers — "create a README for X" and "write an architecture doc" — are generic document-creation requests with no animation qualifier, so the skill could fire for users who want a plain README; not 3 because the niche and remaining triggers are clearly distinct from typical doc skills.

4 / 5

Total

18

/

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

frontmatter_unknown_keys

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

Warning

referenced_paths_exist

Referenced path issues: 7 missing

Warning

Total

14

/

16

Passed

Repository

nitinjain999/platform-skills

Path

plugins/platform-skills/skills/awesome-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.