CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

generating-api-docs

Create comprehensive API documentation with examples, authentication guides, and SDKs. Use when creating comprehensive API documentation. Trigger with phrases like "generate API docs", "create API documentation", or "document the API".

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 ./plugins/api-development/api-documentation-generator/skills/generating-api-docs/SKILL.md
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, token-efficient overview with exemplary progressive disclosure into real, one-level-deep bundle files. The gap is executability: the workflow reads as a content checklist rather than a runnable procedure, with no generator commands in the body or references and no validation step confirming the generated site or code examples work before deployment.

Suggestions

Add the concrete generator invocation(s) (e.g. the Redocly/Stoplight build command or config-driven pipeline) to the Instructions or implementation.md so the doc-generation step is executable rather than directive.

Insert an explicit verification checkpoint before the deploy step: build the site, check links/search index, and smoke-test the generated code examples against a staging API, echoing the error table's own guidance.

Fold the per-step "what good output looks like" details already present in references (e.g. the redoc.yaml example) into the relevant instruction steps as one-line pointers so each step is self-checkable.

DimensionReasoningScore

Conciseness

The body is an efficient, well-structured set of lists with no re-explanation of concepts Claude already knows (no "what is OpenAPI" padding). Minor trims are possible — e.g. "comprehensive, interactive" in the Overview and prerequisite entries like "Custom branding assets (logo, color scheme) for white-labeled documentation" — fitting anchor 4 (efficient, minor over-explanation) rather than anchor 5's every-token-earns-its-place.

4 / 5

Actionability

Steps are concrete about what to produce and with which tools ("Generate interactive documentation using Redoc or Stoplight Elements", per-endpoint examples in curl/JS/Python/Go, explicit output paths), but no executable commands or code appear in the body — the actual generator invocation (e.g. a Redocly CLI command) is never shown, and the referenced implementation.md likewise stays at the directive level. This matches anchor 3 (concrete but incomplete, missing key executable details) rather than anchor 4's mostly-executable guidance.

3 / 5

Workflow Clarity

The eight steps form a clear audit → enrich → generate → examples → auth → errors → versioning → deploy sequence, with an input checkpoint in step 1 (audit spec completeness) and an error-handling table. However, validation of the generated output is only implicit: there is no step to verify the site builds, links resolve, or code examples execute before deployment. That matches anchor 3 (sequence present, checkpoints missing or implicit) rather than anchor 4's most-checkpoints-present.

3 / 5

Progressive Disclosure

The body is a concise overview that delegates depth via three clearly signaled, one-level-deep references — [`references/implementation.md`], [`references/errors.md`], and [`references/examples.md`] — all of which exist, contain the promised material, and do not nest further references. Section organization (Prerequisites, Instructions, Output, Error Handling, Examples, Resources) makes navigation easy, matching anchor 5.

5 / 5

Total

15

/

20

Passed

Description

73%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 solid, third-person description with genuinely natural trigger phrases and a clear, low-conflict niche. Its main weaknesses are a single-verb capability statement softened by the buzzword "comprehensive" and a circular "Use when" clause that adds no new triggering conditions beyond the listed phrases.

Suggestions

Replace the circular "Use when creating comprehensive API documentation" with expanding conditions, e.g. "Use when the user mentions API docs, API reference, OpenAPI/Swagger specs, or developer portals".

Drop the buzzword "comprehensive" and enumerate distinct actions: generate docs sites from OpenAPI specs, write auth guides, build error references, and produce multi-language SDK examples.

Add missing natural trigger synonyms such as "API reference", "OpenAPI", and "Swagger docs" to broaden keyword coverage.

DimensionReasoningScore

Specificity

"Create comprehensive API documentation with examples, authentication guides, and SDKs" names the domain and its deliverables but hinges on a single verb; "comprehensive" is padding rather than a concrete action. It sits between anchor 3 (1-2 concrete actions, not comprehensive) and anchor 4 (several distinct actions), and the buzzword tips it down to 3.

3 / 5

Completeness

Both "what" (create API documentation with examples, authentication guides, and SDKs) and "when" are present, plus explicit trigger phrases. However the "when" clause — "Use when creating comprehensive API documentation" — merely restates the what instead of adding a distinct condition, matching anchor 4 ('when' could be more explicit or specific) rather than anchor 5's genuinely expanding when-clause.

4 / 5

Trigger Term Quality

"generate API docs", "create API documentation", and "document the API" are natural phrases a user would say. Coverage is good but misses common variations like "API reference", "OpenAPI docs", "Swagger docs", or "developer documentation", so it fits anchor 4 (good coverage, a few natural terms missing) rather than anchor 5's comprehensive synonym list.

4 / 5

Distinctiveness Conflict Risk

The API-documentation niche is clearly carved out and the triggers ("generate API docs", "create API documentation", "document the API") are distinct to it with minimal overlap risk against adjacent skills like general technical writing. This matches anchor 5's clear niche with distinct triggers; anchor 4 would require noticeable overlap with a closely related skill, which is not the case.

5 / 5

Total

16

/

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

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

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

Warning

Total

14

/

16

Passed

Repository

jeremylongshore/tons-of-skills-marketplace

Path

plugins/api-development/api-documentation-generator/skills/generating-api-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.