⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

api-and-namespace-design

iflytek@iflytek⭐ 5.4k stars· last commit 2d ago· 32 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 5.4k on GitHubGitHub ↗

Very popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

DeepWiki Docs Discord License Build Docker Java React

GitHub Stars GitHub Watchers

  

English | 中文


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

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-all command to get running locally.
  • Publish & Version — Upload agent skill packages with semantic versioning, custom tags (beta, stable), and automatic latest tracking.
  • 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 slugs
    
  • README.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

// REPO STATS

5.4k stars
32 open issues
Last commit: 2d ago