api-and-namespace-design

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

Quality

83%

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

Quality

Content

100%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a tight, well-organized reference: lean bullets and tables, concrete commands and exact paths, and an OpenAPI sync workflow with an explicit drift-check feedback loop. It assumes Claude's competence throughout and needs no external bundle files, so it scores well across all content dimensions.

Dimension	Reasoning	Score
Conciseness	The body is lean and project-specific — terse bullets, tables, and exact paths like 'com.iflytek.skillhub.controller/' with no padding or explanations of concepts Claude already knows, matching the 'lean and efficient; every token earns its place' anchor.	3 / 3
Actionability	It gives copy-paste-ready commands ('make generate-api', './scripts/check-openapi-generated.sh'), exact endpoint paths with status codes, and named exception/DTO types, matching 'fully executable code/commands; specific examples; copy-paste ready' rather than the pseudocode/incomplete score-2 anchor.	3 / 3
Workflow Clarity	The OpenAPI sync flow is a clear sequence with an explicit verification/feedback loop ('To verify no drift… fails if the checked-in SDK is stale'), matching 'clear sequence with explicit validation steps; feedback loops for error recovery' rather than the checkpoint-missing score-2 anchor.	3 / 3
Progressive Disclosure	The skill is a single self-contained reference with no bundle files and no external references; content is cleanly split into well-signaled sections (Trigger, Namespace, ClawHub, API Design, OpenAPI Sync, Endpoints, Pitfalls), so per the simple-skills note well-organized sections earn a 3 even without file references.	3 / 3
	Total	12 / 12 Passed

Description

67%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific and distinct, naming six concrete capability areas in a clearly delineated niche. Its main weakness is the absence of an explicit 'Use when…' trigger clause, which caps completeness, and its keywords lean technical rather than natural-language.

Suggestions

Append an explicit 'Use when…' trigger clause (e.g., 'Use when adding or modifying SkillHub REST endpoints, namespace/RBAC logic, the ClawHub compatibility layer, or OpenAPI contracts') to lift completeness to 3.

Soften some jargon with natural-language variations users might actually say (e.g., add 'permissions/roles' alongside 'RBAC', 'session login' alongside 'CSRF/session') to broaden trigger-term coverage.

Consider folding in a couple of the body's existing trigger phrases ('adding or modifying REST API endpoints', 'OpenAPI contract sync') so the description mirrors how the skill is actually invoked.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — 'API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling' — matching the score-3 anchor of multiple specific concrete actions rather than the single-domain score-2 anchor.	3 / 3
Completeness	It clearly states what the skill covers but has no 'Use when…' trigger clause, so 'when' is only implied — the judging guideline caps completeness at 2 for a missing explicit trigger.	2 / 3
Trigger Term Quality	Relevant expert keywords ('RBAC roles', 'OpenAPI', 'CSRF/session', 'namespace') are present but skewed toward jargon and lack common natural-language variations a user would casually say, matching 'some relevant keywords but missing common variations' rather than the broad natural-term coverage of score 3.	2 / 3
Distinctiveness Conflict Risk	The SkillHub/ClawHub API niche with named subsystems is highly specific and unlikely to trigger for the wrong skill, matching 'clear niche with distinct triggers' rather than the overlapping score-2 anchor.	3 / 3
	Total	10 / 12 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: ac46ad5

Reviewed: 3 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.