api-and-namespace-design

API and Namespace Design Skill

Trigger

Use this skill when:

• Adding or modifying REST API endpoints
• Changing namespace, skill, or user coordinate logic
• Working on ClawHub CLI compatibility layer
• Modifying OpenAPI specifications or generated types
• Adding new admin or governance endpoints

Namespace Coordinate System

SkillHub uses a two-axis coordinate model:

@{namespace_slug}/{skill_slug}

• @global/my-skill — Global namespace skill
• @my-team/my-skill — Team namespace skill (namespace slug is any valid slug)
• @department-ops/my-skill — Department namespace skill

Namespace Model

Namespaces (domain/namespace/):

• Slug: unique identifier, validated by SlugValidator
• Status: ACTIVE, FROZEN, ARCHIVED
• Roles: OWNER, ADMIN, MEMBER
• Frozen or archived namespaces cannot publish skills

RBAC Roles

Namespace-level (domain/namespace/NamespaceRole):

• OWNER — Full control over namespace and all skills
• ADMIN — Can manage members, archive skills, publish
• MEMBER — Can publish skills to the namespace

Platform-level:

• SUPER_ADMIN — Bypasses all permission checks, can publish directly without review

ClawHub Compatibility Layer

ClawHub CLI uses a single-slug model (no / allowed in slugs). Mapping:

SkillHub Coordinate	Canonical Slug	Notes
@global/my-skill	my-skill	Global namespace omits prefix
@team-name/my-skill	team-name--my-skill	Double-dash separator

Conflict resolution: -- split takes priority. @global/team-name--my-skill would conflict with @team-name/my-skill, resolved to the team namespace skill. Global skill slugs must NOT contain --.

API Design

Controllers

• Controllers in skillhub-app (com.iflytek.skillhub.controller/) are transport only
• Responsibilities: extract auth context, bind request params, wrap responses
• Complex business logic belongs in domain services (skillhub-domain) or app services
• Use Springdoc OpenAPI annotations (@Operation, @ApiResponse) for API documentation
• User identity is always String in API inputs and outputs