⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
api-and-namespace-design
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
SkillHub is a self-hosted platform that gives teams a private, governed place to share agent skills. Publish a skill package, push it to a namespace, and let others find it through search or install it via CLI. Built for on-premise deployment behind your firewall, with the same polish you'd expect from a public registry.
⭐ If SkillHub fits your team, star the repo to help other teams find it, and Watch → Custom → Releases to get notified when a new version ships.
Share Great Skills
Great Skills become more valuable when they are shared. If you have a Skill that has proved useful in real work or everyday life, share it with the SkillHub community and help grow an open, practical Skill ecosystem. We welcome Skills for daily life, office work, learning and research, travel and events, content creation, data analysis, and software development—not only engineering workflows.
High-quality community contributions may join the curated starter collection, making new SkillHub deployments useful from day one. You do not need to finish the full adaptation before joining in: open an issue with the Skill's source and the problem it solves, or submit a PR by following the Skill sharing guide.
Documentation
- User Guide — 中文 / English: find, install, and use skills in your agent
- CLI reference — Authentication, installation, upgrades, namespace synchronization, and local inventory
- Skill Suites — Install a versioned collection and use its entry skill; Suite Bundle import is the separate authoring workflow
- Self-hosting — Docker Compose configuration and upgrades; Kubernetes for clusters
- Developer workflow — Source development, checks, and documentation maintenance; operations reference for deployment details
- Generated code overview — Supplementary architecture exploration; repository source and versioned documentation define current behavior
- Python Examples — Search, download, and publish skills via the REST API
Governance and Safety
- Privacy and Data Governance — Data categories, operator responsibilities, retention, portability, and incident handling for public and self-hosted instances
- Content Safety — Package safety expectations, review and reporting controls, appeals, and child-safety responsibilities
- Code of Conduct — Community standards and the private reporting channel
- Security Policy — Private vulnerability reporting and coordinated disclosure
Highlights
- Self-Hosted & Private — Deploy on your own infrastructure.
Keep proprietary skills behind your firewall with full data
sovereignty. One
make dev-allcommand to get running locally. - Publish & Version — Upload agent skill packages with semantic
versioning, custom tags (
beta,stable), and automaticlatesttracking. - Discover — Full-text search with filters by namespace, downloads, ratings, and recency. Visibility rules ensure users only see what they're authorized to.
- Team Namespaces — Organize skills under team or global scopes. Each namespace has its own members, roles (Owner / Admin / Member), and publishing policies.
- Review & Governance — Team admins review within their namespace; platform admins gate promotions to the global scope. Governance actions are audit-logged for compliance.
- Social Features — Star skills, rate them, and track downloads. Build a community around your organization's best practices.
- Account Merging — Consolidate multiple OAuth identities and API tokens under a single user account.
- API Token Management — Generate scoped tokens for CLI and programmatic access with prefix-based secure hashing.
- CLI-First — Native REST API plus a compatibility layer for existing ClawHub-style registry clients. Native CLI APIs are the primary supported path while protocol compatibility continues to expand.
- Pluggable Storage — Local filesystem for development, S3 / MinIO for production. Swap via config.
- Internationalization — Multi-language support with i18next: English, Simplified Chinese, Russian, and Korean.
Quick Start
To host your own registry using release images, start with:
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
The default command pulls the latest stable release images. Use --version edge if you want the newest build from main.
Configure public URL (recommended for production):
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com
The --public-url parameter sets the public access URL for your SkillHub instance. This ensures:
- CLI install commands show the correct registry URL
- Agent setup instructions display the correct skill.md URL
- OAuth callbacks and device auth links work properly
For users in China (Aliyun mirror):
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url h
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.agents/skills/api-and-namespace-design/SKILL.md5.0 KBupstream ↗
--- name: api-and-namespace-design description: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling. license: Apache-2.0 --- # 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 ### Request/Response Patterns - DTOs in `com.iflytek.skillhub.dto/` - `ReviewTaskRequest` / `ReviewTaskResponse` for review workflow - Response wrapping handled at controller layer - Validation errors use `DomainBadRequestException` with i18n message keys ### Session and CSRF - Session-based auth with cookie storage - CSRF protection via `XSRF-TOKEN` cookie and `X-XSRF-TOKEN` header - Smoke tests validate the full register → login → CSRF → action → logout flow - Mock auth uses `X-Mock-User-Id` header in local dev ### Well-known Discovery `/.well-known/clawhub.json` returns `{ "apiBase": "/api/v1" }` for ClawHub CLI auto-discovery. ## OpenAPI Contract Sync When backend API contracts change: ```bash make generate-api ``` This runs `openapi-typescript http://localhost:8080/v3/api-docs -o src/api/generated/schema.d.ts`. Commit the updated `web/src/api/generated/schema.d.ts` with the PR. To verify no drift: ```bash ./scripts/check-openapi-generated.sh ``` This starts local dependencies, boots the backend, regenerates the schema, and fails if the checked-in SDK is stale. ## Versioning and Tags - Semantic versioning for skill versions (`major.minor.patch`) - `latest` tag is system-reserved, read-only, auto-follows `Skill.latestVersionId` - Custom tags (`stable`, `beta`) are manually maintained - `latest` cannot be moved manually - Auto-generated versions use `yyyyMMdd.HHmmss` format when no version is specified in SKILL.md ## Key API Endpoints | Method | Path | Purpose | |--------|------|---------| | `GET` | `/api/v1/auth/me` | Current user info (401 if unauthenticated) | | `POST` | `/api/v1/auth/local/login` | Local account login | | `POST` | `/api/v1/auth/local/register` | Local account registration | | `POST` | `/api/v1/auth/logout` | Logout (302/200/204) | | `POST` | `/api/v1/auth/local/change-password` | Password change | | `GET` | `/api/v1/namespaces` | List namespaces | | `GET` | `/api/v1/labels` | List visible labels (public) | | `POST` | `/api/v1/admin/labels` | Create label definition (admin) | | `DELETE` | `/api/v1/admin/labels/{slug}` | Delete label definition (admin) | | `GET` | `/actuator/health` | Health check | | `GET` | `/actuator/prometheus` | Prometheus metrics | ## Common Pitfalls - Forgetting CSRF token on POST/PUT/DELETE requests (needs `X-XSRF-TOKEN` header) - Using numeric user IDs in API — all user identities are **String** - Not regenerating OpenAPI types after adding/changing endpoints - Putting business logic in controllers instead of domain/app services - Assuming namespace slugs follow a specific prefix pattern — they are arbitrary valid slugsREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/iflytek-skillhub-agents-skills-api-and-namespace-design.md