What does this skill do, and when should you use it?
This skill is a reference guide for developers working on the SkillHub backend, covering API design, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync, and CSRF/session handling. It is triggered when adding or modifying REST endpoints, namespace/skill/user coordinate logic, ClawHub CLI compatibility, OpenAPI specs, or admin/governance endpoints. The skill emphasizes that controllers are transport-only, business logic belongs in domain or app services, and all user identities are String.
The skill provides a readable specification that defines: a two-axis namespace coordinate system (@namespace/skill) with namespace states and roles; platform-level SUPER_ADMIN role; ClawHub compatibility layer's single-slug mapping rules; REST controller responsibilities (transport only, no business logic); request/response DTO patterns and exception handling; CSRF protection via XSRF-TOKEN cookie and X-XSRF-TOKEN header; session-based auth and mock auth via X-Mock-User-Id for local dev; /.well-known/clawhub.json discovery endpoint; OpenAPI type generation commands (make generate-api and check-openapi-generated.sh script); semantic versioning with tags like latest, stable, beta; and a list of common API endpoints.
- Backend developers adding or modifying REST API endpoints can follow controller responsibilities and DTO patterns.
- Developers changing namespace or user coordinate logic can reference the coordinate system and slug validation rules.
- Engineers maintaining the ClawHub CLI compatibility layer can consult the compat slug mapping and conflict resolution.
- When updating OpenAPI specs or generated TypeScript types, developers run 'make generate-api' and commit the change.
- When adding new admin or governance endpoints (e.g., label management), developers verify RBAC permissions and audit logging.
- When debugging CSRF or session auth, developers use the documented cookie/header rules and mock auth for local testing.
How do you install this skill?
- Static review cannot verify actual operation; run tests and CI workflows for higher confidence.
- Publisher identity is unverified; assess risks before use.
- The skill relies on external services and tools (e.g., Docker, Kubernetes), which may require mirror configuration in mainland China.
- Shell / CLI
- Local filesystem
Java 21DockerMaven
This skill resides in the repository at .agents/skills/api-and-namespace-design/SKILL.md. To use it, clone the entire iflytek/skillhub repository, or copy the .agents/skills/api-and-namespace-design folder into your agent skills directory. This skill is documentation-only and has no separate installation package.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/iflytek/skillhub.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/.agents/skills/api-and-namespace-design" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Consult the api-and-namespace-design skill to design a new authentication endpoint.
Trigger this skill when working on SkillHub backend development, e.g., when adding a new endpoint or modifying namespace logic, you can prompt: 'Consult the api-and-namespace-design skill to design a new authentication endpoint.' The agent will read SKILL.md and apply its conventions, such as controller transport layer, DTO models, CSRF requirements, and OpenAPI sync steps.
What are this skill's strengths and limitations?
- Comprehensive API design conventions reduce team decision-making overhead.
- Defined RBAC roles and namespace model aid governance.
- Includes ClawHub compatibility mapping for CLI integration.
- Enforces OpenAPI contract sync to prevent type drift between frontend and backend.
- Clear documentation with common pitfalls list to avoid errors.
- This skill is a specification document only; no automated scripts or validators are provided to enforce compliance.
- Limited applicability if you are not working on the SkillHub project itself.
- No test cases or example code, only textual descriptions.
- Does not cover detailed error response structures beyond exception types.
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| API & Namespace Design this page | 50 · Use with care | ★ 5.2k | 3d ago | Apache-2.0 |
| Stable Interface Design | 50 · Use with care | ★ 103k | 8d ago | MIT |
| FreeHire Tech Job Search Skill | 63 · Recommended | ★ 45k | 3d ago | MIT |
| AMC Sample Dataset Calibration ✓ NVIDIA · Official | 55 · Use with care | ★ 3.5k | 3d ago | Apache-2.0 |
| step.parts Catalog Skill | 55 · Use with care | ★ 19k | 1d ago | MIT |
How did FollowSkills review this skill?
The skill clearly describes security-related API design conventions such as RBAC roles, CSRF protection, session handling, and OpenAPI sync, but does not provide specific security audit details or execution verification. Since the publisher is unverified and no malicious behavior or mishandling of sensitive data is found, a mid-range score is given. Deductions: lack of in-depth explanations on permission granularity, exception handling, and data-flow transparency.
The skill provides clear trigger conditions and endpoint lists, but lacks executable test cases or error-handling examples. Static review cannot perform execution verification, so reliability is low. Deductions: absence of failure feedback and quality assurance evidence.
The skill defines clear applicability and boundaries (e.g., adding/modifying REST API endpoints, namespace coordinate logic), and includes Chinese language support. However, it does not fully demonstrate non-fit scenarios and trigger precision. Deductions: boundaries are clear but environment-fit evidence is limited.
Documentation structure is clear, with sections on triggers, coordinate system, API design, common pitfalls, etc., but lacks installation/dependency notes, version changelog, and detailed known limitations. Deductions: information architecture is complete but governance details are insufficient.
The skill aims to guide API and namespace design, but its directly usable outputs (e.g., code or config) are not verified, and evidence of marginal value is limited. Deductions: static review cannot confirm actual effectiveness.
Some CI and workflow files are provided as evidence, but static review cannot independently verify their effectiveness. Deductions: single source of evidence, lacking third-party verification.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →