api-and-namespace-design

API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/api-and-namespace-design/SKILL.md

Quality

Content

71%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, project-specific convention reference with genuinely executable commands and a validation loop for OpenAPI drift. Its main weaknesses are inlined reference material that belongs in separate files and convention descriptions that would benefit from one compact code example.

Suggestions

Move the Key API Endpoints table and namespace/RBAC model details into references/ files, keeping SKILL.md as an overview with clearly signaled links.

Add a short controller code example showing the transport-only pattern (extract auth, bind params, wrap response) so the convention is demonstrable, not just described.

State explicitly when to run ./scripts/check-openapi-generated.sh (e.g. as a pre-PR checklist step) to turn the drift check into an explicit workflow checkpoint.

Dimension	Reasoning	Score
Conciseness	The body is dense and convention-driven with no padding or explanations of concepts Claude already knows (tables for ClawHub slug mapping and endpoints, one-line RBAC role definitions). Minor trimming is possible — e.g. the 11-row Key API Endpoints table is bulk that could live in a reference file.	4 / 5
Actionability	Concrete, copy-paste-ready commands are present ('make generate-api', './scripts/check-openapi-generated.sh', the openapi-typescript invocation) alongside specific class names ('DomainBadRequestException', 'ReviewTaskRequest') and exact endpoint paths. Minor gaps: conventions like 'transport only controllers' lack a code example showing the pattern.	4 / 5
Workflow Clarity	The OpenAPI Contract Sync section has a clear sequence with an explicit validation step ('fails if the checked-in SDK is stale'), and the Common Pitfalls section acts as an error-avoidance checklist. Most other sections are convention references rather than workflows, so a few lack explicit checkpoints, keeping this just below the feedback-loop anchor.	4 / 5
Progressive Disclosure	Sections are clearly headed and navigable, but no references/, scripts/, or assets/ bundle exists, so reference-style content (the Key API Endpoints table, RBAC/namespace model details) is inlined in the single file rather than split out. At ~135 lines it exceeds the simple-skill exception, fitting the 'content that should be separate is inline' anchor.	3 / 5
	Total	15 / 20 Passed

Description

61%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 topical, keyword-rich description that clearly identifies the domain, but it reads as a table of contents rather than a capability statement and entirely lacks a 'when to use' trigger clause. Voice is appropriately third-person and concise.

Suggestions

Add an explicit trigger clause, e.g. 'Use when adding or modifying REST API endpoints, changing namespace/RBAC logic, or syncing OpenAPI contracts.'

Lead with what the skill does rather than a topic inventory, e.g. 'Designs REST API endpoints and defines the SkillHub namespace coordinate system...'.

Include a couple of natural user synonyms such as 'endpoints' or 'permissions' alongside the existing jargon terms.

Dimension	Reasoning	Score
Specificity	The description names the domain ("API design conventions") plus six concrete subject areas ("namespace coordinate system", "RBAC roles", "ClawHub compatibility layer", "OpenAPI contract sync rules", "CSRF/session handling"), but it is a noun-phrase topic list with no action verbs describing what the skill actually does, so it does not reach the 'several specific actions' anchor.	3 / 5
Completeness	The 'what' is clear via the enumerated topics, but there is no 'Use when...' or equivalent trigger clause anywhere in the description, which per the guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	Strong domain keywords users would naturally say: "API design", "namespace", "RBAC", "OpenAPI", "CSRF", "session". A few natural synonyms are missing ("endpoints", "REST", "permissions"), keeping it below comprehensive coverage.	4 / 5
Distinctiveness Conflict Risk	Project-specific terms like "ClawHub compatibility layer" and "namespace coordinate system" give it a clear niche, but generic phrases like "API design conventions" and "CSRF/session handling" leave minor overlap risk with general API/security skills.	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

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: iflytek/skillhub
Path: .agents/skills/api-and-namespace-design/SKILL.md
Commit: 7352597

Reviewed: 10 days ago

Table of Contents

Discovery Implementation Validation

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.