docs-api
Docs API Agent. OpenAPI 스펙, API 레퍼런스 문서 작성을 담당합니다.
Install with Tessl CLI
npx tessl i github:shaul1991/shaul-agents-plugin --skill docs-api47
Quality
35%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/docs-api/SKILL.mdDiscovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description identifies a clear domain (API documentation with OpenAPI focus) but suffers from lack of explicit trigger guidance and insufficient detail about specific capabilities. The Korean-only text limits discoverability for English queries, and the absence of a 'Use when...' clause makes it difficult for Claude to know when to select this skill over alternatives.
Suggestions
Add an explicit 'Use when...' clause with trigger terms like 'OpenAPI', 'Swagger', 'API documentation', 'endpoint docs', 'REST API reference'
List specific concrete actions such as 'generate OpenAPI 3.0 specs', 'document request/response schemas', 'create endpoint descriptions', 'validate API specifications'
Include both Korean and English trigger terms to improve discoverability across language contexts
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API documentation) and mentions specific document types (OpenAPI specs, API reference docs), but lacks concrete actions beyond '작성을 담당합니다' (handles writing). Does not list specific capabilities like 'generate endpoints', 'document parameters', etc. | 2 / 3 |
Completeness | Describes what it does (writes API documentation) but completely lacks a 'Use when...' clause or any explicit trigger guidance. The 'when' component is entirely missing, which per rubric guidelines caps this at maximum 2, but the 'what' is also weak. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'OpenAPI', 'API 레퍼런스', '스펙' that users might mention, but missing common variations like 'Swagger', 'REST API docs', 'endpoint documentation', or English equivalents for bilingual contexts. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on OpenAPI and API reference documentation provides some distinction from general documentation skills, but 'Docs' in the name and generic 'API' terms could overlap with other documentation or API-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is concise but severely lacks actionability. It functions more as a role description than a skill that teaches Claude how to perform tasks. The content lists responsibilities and output locations but provides zero guidance on how to write OpenAPI specs, create API references, or format change logs.
Suggestions
Add concrete examples of OpenAPI spec structure and conventions to follow (e.g., a minimal endpoint definition template)
Include a workflow for creating/updating API documentation with validation steps (e.g., lint OpenAPI spec, verify examples match schema)
Provide request/response example templates showing the expected format and level of detail
Link to reference materials or templates for each responsibility (e.g., 'See [OPENAPI_TEMPLATE.yaml](templates/openapi.yaml) for base structure')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is extremely brief and doesn't explain concepts Claude already knows. Every line serves a purpose - role definition, responsibilities, and output locations. | 3 / 3 |
Actionability | The skill provides no concrete guidance, code examples, or executable instructions. It only lists responsibilities and file paths without explaining how to actually perform any of the tasks. | 1 / 3 |
Workflow Clarity | No workflow or process is defined. The skill lists what to produce but provides no steps, sequences, or validation checkpoints for creating OpenAPI specs or API documentation. | 1 / 3 |
Progressive Disclosure | The content is well-organized with clear sections, but it lacks any references to detailed materials. For a skill defining an agent role, it should link to templates, examples, or detailed guides for each responsibility. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
Total | 10 / 11 Passed | |
- 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.