Creator · iflytek
Last updated · Sep 1, 2026
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Creator · iflytek
Last updated · Sep 1, 2026
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Creator · iflytek
Last updated · Sep 1, 2026
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Creator · iflytek
Last updated · Sep 1, 2026
API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling.
Sandbox only
Install targets
Codex install prompt
Install the "api-and-namespace-design" agent skill from https://github.com/iflytek/skillhub/tree/main/.agents/skills/api-and-namespace-design. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {"event_id":"install_<unique-id>","skill_slug":"iflytek-api-and-namespace-design","task":"Install api-and-namespace-design","agent":"codex","outcome":"success","install_used":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.Supply asset profile
Code review, repo analysis, testing, CI, GitHub, DevOps, and developer workflow skills.
Scenario
GitHub automation
I need my agent to triage GitHub issues, review pull requests, and summarize repository changes.
Agent fit
Claude Code + CLI + Codex
Codex, Claude Code, Cursor, CLI, or custom agents.
Install
Ready
npx skills add iflytek/skillhub --skill api-and-namespace-design
Maintenance
fresh
3d since push
Risk
Needs review
Dependency or permission surface needs review
GitHub quality
4.9K
84/100 Quality · 77/100 Trust
Coverage tags
Review notes
Dependency or permission surface needs review · Permission surface may require sandboxing
Agent adoption scorecard
These scores combine public repository metadata, OpenAgentSkill review signals, maintenance freshness, and install readiness. They are a shortlist signal, not a replacement for human review.
Quality
StrongSolid option that is likely worth shortlisting for production workflows.
Trust
Sandbox onlyUseful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
Audit
Needs reviewA machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
OpenAgentSkill Trust Score v5
Run only in a sandbox and compare close alternatives before using it for real work.
Stars
4.9K GitHub stars
Repo activity
4.9K stars, 821 forks
Maintenance
3d since push
License
Apache-2.0
Install
npx skills add iflytek/skillhub --skill api-and-namespace-design
Install safety
Agent-readable metadata
Use this block or the embedded JSON to decide whether an agent should install this skill, choose an alternative, or ask for human review first.
Suited tasks
Suited agents
Install decision
Trust and risk
Outcome loop
Install command
npx skills add iflytek/skillhub --skill api-and-namespace-designDo not use when
Agent safety v2
Sparse or mixed signals. Useful for discovery, but not for autonomous installation.
Test manually in an isolated workspace and compare against safer alternatives.
high
Skill metadata references terminal, CLI, shell, subprocess, or command execution workflows.
medium
Skill likely fetches remote pages, APIs, repositories, or external services.
high
Skill metadata references credentials, tokens, environment variables, or secret-bearing workflows.
medium
Skill may inspect schemas, query databases, or work with persistent stores.
Agent resolve plan
The Resolve API returns the selected skill, alternatives, safety policy, audit notes, install target, and copy-paste prompt an agent can follow without scraping this page.
Open JSON
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Resolve text
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
Agent should check
Copy prompt
Task: Use api-and-namespace-design in this workspace.
Resolve first: https://www.openagentskill.com/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Review install handoff: https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install
Install command: npx skills add iflytek/skillhub --skill api-and-namespace-design
Before running it, summarize audit warnings, required permissions, and the fallback skill if install is risky.Agent handoff
Use the public install endpoint to fetch the command, safety checklist, target prompts, and canonical links for this skill.
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
LLM text format
/api/skills/iflytek-api-and-namespace-design/install?format=text
Find alternatives
/api/skills/search?q=api-and-namespace-design&limit=3
Agent prompt
Use api-and-namespace-design for this task. Review https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install, then install with: npx skills add iflytek/skillhub --skill api-and-namespace-designRegistry metadata
This page exposes the same decision, trust, audit, use-case, and install signals through the Registry API, so agents can rank this skill without scraping the UI.
Manifest
/api/registry/manifest/iflytek-api-and-namespace-design
LLM text
/api/registry/manifest/iflytek-api-and-namespace-design?format=text
Install alias
/api/registry/install/iflytek-api-and-namespace-design
Recommend
/api/registry/recommend?task=Use%20api-and-namespace-design%20in%20an%20agent%20workflow&limit=3
Agent fit
RAG and knowledge
Platforms
Claude Code
Audit report
A machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
Agent decision cockpit
Use this as a leading candidate, then validate the README and install path in your own agent stack.
Role in stack
Primary pick
Primary fit
RAG and knowledge
Trust label
Production-ready
Install path
Command ready
Use when
Evidence
review first
Implementation path
Trust profile
Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
GitHub adoption
PASS4.9K GitHub stars
Stars/forks activity
PASS4.9K stars, 821 forks; issue activity unavailable in current metadata
Recent maintenance
PASS3d since push
License clarity
PASSApache-2.0
Good signals
Review before install
Recommended action
Run only in a sandbox and compare close alternatives before using it for real work.
Quality profile
Solid option that is likely worth shortlisting for production workflows.
Workflow fit
Search private knowledge
I need my agent to build a RAG workflow over documents and retrieve reliable context.
Parse messy files
I need my agent to read PDFs, extract tables, and turn documents into structured data.
Operate web apps
I need my agent to control a browser, fill forms, and verify web app workflows.
Workflow fit
Ingest, retrieve, and cite
A workflow for document-heavy agents that ingest files, create searchable knowledge, retrieve relevant context, and answer with grounded sources.
Operate and verify web apps
A workflow for agents that navigate products, fill forms, take screenshots, and verify real user flows across web applications.
Design, build, test, and ship interfaces
A practical workflow for agents that turn product briefs or Figma designs into polished frontend code, review the result, test it in a browser, and prepare a safe deployment.
--- 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
Source provenance
Decision snapshot
4,937 GitHub stars
Audit
Install and adoption review
Agent-proven evidence
Outcome reports after resolve, review, install, and one narrow run.
No agent outcome data yet. The first agent run can report success, setup needs, risk blocks, failure, or not-relevant through /api/agent/outcome.
Install
Free and open source. Review the report before installing into production agents.
Growth loop
Scenario-led draft for api-and-namespace-design, ready for a manual X post.
api-and-namespace-design: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer,... 4.9K stars https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x
Listing + install path for api-and-namespace-design: https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x Install: npx skills add iflytek/skillhub --skill api-and-namespace-design
Listing source
This listing was indexed from public sources and is not marked official until a maintainer claim is approved.
Attribution links to the public repository or creator profile. Creators can claim the listing to update ownership signals.
Claim this skillOwner claim
This Registry indexed listing is attributed to iflytek but is not marked official yet. Claim it to add a verified owner signal and make future launch, install, and audit updates easier to trust.
Creator backlink kit
Show the canonical listing, current trust and audit signals, and real Agent-Proven evidence where developers evaluate the repository.
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design/audit)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)iflytek
@iflytek
Share whether this skill looks useful for your agent workflow. Aggregated feedback improves rankings over time.
Sandbox only
Sandbox only
Install targets
Codex install prompt
Install the "api-and-namespace-design" agent skill from https://github.com/iflytek/skillhub/tree/main/.agents/skills/api-and-namespace-design. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {"event_id":"install_<unique-id>","skill_slug":"iflytek-api-and-namespace-design","task":"Install api-and-namespace-design","agent":"codex","outcome":"success","install_used":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.Supply asset profile
Code review, repo analysis, testing, CI, GitHub, DevOps, and developer workflow skills.
Scenario
GitHub automation
I need my agent to triage GitHub issues, review pull requests, and summarize repository changes.
Agent fit
Claude Code + CLI + Codex
Codex, Claude Code, Cursor, CLI, or custom agents.
Install
Ready
npx skills add iflytek/skillhub --skill api-and-namespace-design
Maintenance
fresh
3d since push
Risk
Needs review
Dependency or permission surface needs review
GitHub quality
4.9K
84/100 Quality · 77/100 Trust
Coverage tags
Review notes
Dependency or permission surface needs review · Permission surface may require sandboxing
Agent adoption scorecard
These scores combine public repository metadata, OpenAgentSkill review signals, maintenance freshness, and install readiness. They are a shortlist signal, not a replacement for human review.
Quality
StrongSolid option that is likely worth shortlisting for production workflows.
Trust
Sandbox onlyUseful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
Audit
Needs reviewA machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
OpenAgentSkill Trust Score v5
Run only in a sandbox and compare close alternatives before using it for real work.
Stars
4.9K GitHub stars
Repo activity
4.9K stars, 821 forks
Maintenance
3d since push
License
Apache-2.0
Install
npx skills add iflytek/skillhub --skill api-and-namespace-design
Install safety
Agent-readable metadata
Use this block or the embedded JSON to decide whether an agent should install this skill, choose an alternative, or ask for human review first.
Suited tasks
Suited agents
Install decision
Trust and risk
Outcome loop
Install command
npx skills add iflytek/skillhub --skill api-and-namespace-designDo not use when
Agent safety v2
Sparse or mixed signals. Useful for discovery, but not for autonomous installation.
Test manually in an isolated workspace and compare against safer alternatives.
high
Skill metadata references terminal, CLI, shell, subprocess, or command execution workflows.
medium
Skill likely fetches remote pages, APIs, repositories, or external services.
high
Skill metadata references credentials, tokens, environment variables, or secret-bearing workflows.
medium
Skill may inspect schemas, query databases, or work with persistent stores.
Agent resolve plan
The Resolve API returns the selected skill, alternatives, safety policy, audit notes, install target, and copy-paste prompt an agent can follow without scraping this page.
Open JSON
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Resolve text
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
Agent should check
Copy prompt
Task: Use api-and-namespace-design in this workspace.
Resolve first: https://www.openagentskill.com/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Review install handoff: https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install
Install command: npx skills add iflytek/skillhub --skill api-and-namespace-design
Before running it, summarize audit warnings, required permissions, and the fallback skill if install is risky.Agent handoff
Use the public install endpoint to fetch the command, safety checklist, target prompts, and canonical links for this skill.
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
LLM text format
/api/skills/iflytek-api-and-namespace-design/install?format=text
Find alternatives
/api/skills/search?q=api-and-namespace-design&limit=3
Agent prompt
Use api-and-namespace-design for this task. Review https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install, then install with: npx skills add iflytek/skillhub --skill api-and-namespace-designRegistry metadata
This page exposes the same decision, trust, audit, use-case, and install signals through the Registry API, so agents can rank this skill without scraping the UI.
Manifest
/api/registry/manifest/iflytek-api-and-namespace-design
LLM text
/api/registry/manifest/iflytek-api-and-namespace-design?format=text
Install alias
/api/registry/install/iflytek-api-and-namespace-design
Recommend
/api/registry/recommend?task=Use%20api-and-namespace-design%20in%20an%20agent%20workflow&limit=3
Agent fit
RAG and knowledge
Platforms
Claude Code
Audit report
A machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
Agent decision cockpit
Use this as a leading candidate, then validate the README and install path in your own agent stack.
Role in stack
Primary pick
Primary fit
RAG and knowledge
Trust label
Production-ready
Install path
Command ready
Use when
Evidence
review first
Implementation path
Trust profile
Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
GitHub adoption
PASS4.9K GitHub stars
Stars/forks activity
PASS4.9K stars, 821 forks; issue activity unavailable in current metadata
Recent maintenance
PASS3d since push
License clarity
PASSApache-2.0
Good signals
Review before install
Recommended action
Run only in a sandbox and compare close alternatives before using it for real work.
Quality profile
Solid option that is likely worth shortlisting for production workflows.
Workflow fit
Search private knowledge
I need my agent to build a RAG workflow over documents and retrieve reliable context.
Parse messy files
I need my agent to read PDFs, extract tables, and turn documents into structured data.
Operate web apps
I need my agent to control a browser, fill forms, and verify web app workflows.
Workflow fit
Ingest, retrieve, and cite
A workflow for document-heavy agents that ingest files, create searchable knowledge, retrieve relevant context, and answer with grounded sources.
Operate and verify web apps
A workflow for agents that navigate products, fill forms, take screenshots, and verify real user flows across web applications.
Design, build, test, and ship interfaces
A practical workflow for agents that turn product briefs or Figma designs into polished frontend code, review the result, test it in a browser, and prepare a safe deployment.
--- 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
Source provenance
Decision snapshot
4,937 GitHub stars
Audit
Install and adoption review
Agent-proven evidence
Outcome reports after resolve, review, install, and one narrow run.
No agent outcome data yet. The first agent run can report success, setup needs, risk blocks, failure, or not-relevant through /api/agent/outcome.
Install
Free and open source. Review the report before installing into production agents.
Growth loop
Scenario-led draft for api-and-namespace-design, ready for a manual X post.
api-and-namespace-design: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer,... 4.9K stars https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x
Listing + install path for api-and-namespace-design: https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x Install: npx skills add iflytek/skillhub --skill api-and-namespace-design
Listing source
This listing was indexed from public sources and is not marked official until a maintainer claim is approved.
Attribution links to the public repository or creator profile. Creators can claim the listing to update ownership signals.
Claim this skillOwner claim
This Registry indexed listing is attributed to iflytek but is not marked official yet. Claim it to add a verified owner signal and make future launch, install, and audit updates easier to trust.
Creator backlink kit
Show the canonical listing, current trust and audit signals, and real Agent-Proven evidence where developers evaluate the repository.
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design/audit)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)iflytek
@iflytek
Share whether this skill looks useful for your agent workflow. Aggregated feedback improves rankings over time.
Sandbox only
Sandbox only
Install targets
Codex install prompt
Install the "api-and-namespace-design" agent skill from https://github.com/iflytek/skillhub/tree/main/.agents/skills/api-and-namespace-design. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {"event_id":"install_<unique-id>","skill_slug":"iflytek-api-and-namespace-design","task":"Install api-and-namespace-design","agent":"codex","outcome":"success","install_used":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.Supply asset profile
Code review, repo analysis, testing, CI, GitHub, DevOps, and developer workflow skills.
Scenario
GitHub automation
I need my agent to triage GitHub issues, review pull requests, and summarize repository changes.
Agent fit
Claude Code + CLI + Codex
Codex, Claude Code, Cursor, CLI, or custom agents.
Install
Ready
npx skills add iflytek/skillhub --skill api-and-namespace-design
Maintenance
fresh
3d since push
Risk
Needs review
Dependency or permission surface needs review
GitHub quality
4.9K
84/100 Quality · 77/100 Trust
Coverage tags
Review notes
Dependency or permission surface needs review · Permission surface may require sandboxing
Agent adoption scorecard
These scores combine public repository metadata, OpenAgentSkill review signals, maintenance freshness, and install readiness. They are a shortlist signal, not a replacement for human review.
Quality
StrongSolid option that is likely worth shortlisting for production workflows.
Trust
Sandbox onlyUseful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
Audit
Needs reviewA machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
OpenAgentSkill Trust Score v5
Run only in a sandbox and compare close alternatives before using it for real work.
Stars
4.9K GitHub stars
Repo activity
4.9K stars, 821 forks
Maintenance
3d since push
License
Apache-2.0
Install
npx skills add iflytek/skillhub --skill api-and-namespace-design
Install safety
Agent-readable metadata
Use this block or the embedded JSON to decide whether an agent should install this skill, choose an alternative, or ask for human review first.
Suited tasks
Suited agents
Install decision
Trust and risk
Outcome loop
Install command
npx skills add iflytek/skillhub --skill api-and-namespace-designDo not use when
Agent safety v2
Sparse or mixed signals. Useful for discovery, but not for autonomous installation.
Test manually in an isolated workspace and compare against safer alternatives.
high
Skill metadata references terminal, CLI, shell, subprocess, or command execution workflows.
medium
Skill likely fetches remote pages, APIs, repositories, or external services.
high
Skill metadata references credentials, tokens, environment variables, or secret-bearing workflows.
medium
Skill may inspect schemas, query databases, or work with persistent stores.
Agent resolve plan
The Resolve API returns the selected skill, alternatives, safety policy, audit notes, install target, and copy-paste prompt an agent can follow without scraping this page.
Open JSON
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Resolve text
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
Agent should check
Copy prompt
Task: Use api-and-namespace-design in this workspace.
Resolve first: https://www.openagentskill.com/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Review install handoff: https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install
Install command: npx skills add iflytek/skillhub --skill api-and-namespace-design
Before running it, summarize audit warnings, required permissions, and the fallback skill if install is risky.Agent handoff
Use the public install endpoint to fetch the command, safety checklist, target prompts, and canonical links for this skill.
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
LLM text format
/api/skills/iflytek-api-and-namespace-design/install?format=text
Find alternatives
/api/skills/search?q=api-and-namespace-design&limit=3
Agent prompt
Use api-and-namespace-design for this task. Review https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install, then install with: npx skills add iflytek/skillhub --skill api-and-namespace-designRegistry metadata
This page exposes the same decision, trust, audit, use-case, and install signals through the Registry API, so agents can rank this skill without scraping the UI.
Manifest
/api/registry/manifest/iflytek-api-and-namespace-design
LLM text
/api/registry/manifest/iflytek-api-and-namespace-design?format=text
Install alias
/api/registry/install/iflytek-api-and-namespace-design
Recommend
/api/registry/recommend?task=Use%20api-and-namespace-design%20in%20an%20agent%20workflow&limit=3
Agent fit
RAG and knowledge
Platforms
Claude Code
Audit report
A machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
Agent decision cockpit
Use this as a leading candidate, then validate the README and install path in your own agent stack.
Role in stack
Primary pick
Primary fit
RAG and knowledge
Trust label
Production-ready
Install path
Command ready
Use when
Evidence
review first
Implementation path
Trust profile
Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
GitHub adoption
PASS4.9K GitHub stars
Stars/forks activity
PASS4.9K stars, 821 forks; issue activity unavailable in current metadata
Recent maintenance
PASS3d since push
License clarity
PASSApache-2.0
Good signals
Review before install
Recommended action
Run only in a sandbox and compare close alternatives before using it for real work.
Quality profile
Solid option that is likely worth shortlisting for production workflows.
Workflow fit
Search private knowledge
I need my agent to build a RAG workflow over documents and retrieve reliable context.
Parse messy files
I need my agent to read PDFs, extract tables, and turn documents into structured data.
Operate web apps
I need my agent to control a browser, fill forms, and verify web app workflows.
Workflow fit
Ingest, retrieve, and cite
A workflow for document-heavy agents that ingest files, create searchable knowledge, retrieve relevant context, and answer with grounded sources.
Operate and verify web apps
A workflow for agents that navigate products, fill forms, take screenshots, and verify real user flows across web applications.
Design, build, test, and ship interfaces
A practical workflow for agents that turn product briefs or Figma designs into polished frontend code, review the result, test it in a browser, and prepare a safe deployment.
--- 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
Source provenance
Decision snapshot
4,937 GitHub stars
Audit
Install and adoption review
Agent-proven evidence
Outcome reports after resolve, review, install, and one narrow run.
No agent outcome data yet. The first agent run can report success, setup needs, risk blocks, failure, or not-relevant through /api/agent/outcome.
Install
Free and open source. Review the report before installing into production agents.
Growth loop
Scenario-led draft for api-and-namespace-design, ready for a manual X post.
api-and-namespace-design: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer,... 4.9K stars https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x
Listing + install path for api-and-namespace-design: https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x Install: npx skills add iflytek/skillhub --skill api-and-namespace-design
Listing source
This listing was indexed from public sources and is not marked official until a maintainer claim is approved.
Attribution links to the public repository or creator profile. Creators can claim the listing to update ownership signals.
Claim this skillOwner claim
This Registry indexed listing is attributed to iflytek but is not marked official yet. Claim it to add a verified owner signal and make future launch, install, and audit updates easier to trust.
Creator backlink kit
Show the canonical listing, current trust and audit signals, and real Agent-Proven evidence where developers evaluate the repository.
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design/audit)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)iflytek
@iflytek
Share whether this skill looks useful for your agent workflow. Aggregated feedback improves rankings over time.
Sandbox only
Sandbox only
Install targets
Codex install prompt
Install the "api-and-namespace-design" agent skill from https://github.com/iflytek/skillhub/tree/main/.agents/skills/api-and-namespace-design. Read its SKILL.md or equivalent instructions first, install only the files needed for this workspace, and summarize any required setup before using it. Skill purpose: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer, OpenAPI contract sync rules, and CSRF/session handling. After the install attempt, report the result to https://www.openagentskill.com/api/agent/outcome with POST JSON {"event_id":"install_<unique-id>","skill_slug":"iflytek-api-and-namespace-design","task":"Install api-and-namespace-design","agent":"codex","outcome":"success","install_used":true}. Replace event_id with a unique value and outcome with success or failed. Report success only after the skill is installed and a minimal verification passes.Supply asset profile
Code review, repo analysis, testing, CI, GitHub, DevOps, and developer workflow skills.
Scenario
GitHub automation
I need my agent to triage GitHub issues, review pull requests, and summarize repository changes.
Agent fit
Claude Code + CLI + Codex
Codex, Claude Code, Cursor, CLI, or custom agents.
Install
Ready
npx skills add iflytek/skillhub --skill api-and-namespace-design
Maintenance
fresh
3d since push
Risk
Needs review
Dependency or permission surface needs review
GitHub quality
4.9K
84/100 Quality · 77/100 Trust
Coverage tags
Review notes
Dependency or permission surface needs review · Permission surface may require sandboxing
Agent adoption scorecard
These scores combine public repository metadata, OpenAgentSkill review signals, maintenance freshness, and install readiness. They are a shortlist signal, not a replacement for human review.
Quality
StrongSolid option that is likely worth shortlisting for production workflows.
Trust
Sandbox onlyUseful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
Audit
Needs reviewA machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
OpenAgentSkill Trust Score v5
Run only in a sandbox and compare close alternatives before using it for real work.
Stars
4.9K GitHub stars
Repo activity
4.9K stars, 821 forks
Maintenance
3d since push
License
Apache-2.0
Install
npx skills add iflytek/skillhub --skill api-and-namespace-design
Install safety
Agent-readable metadata
Use this block or the embedded JSON to decide whether an agent should install this skill, choose an alternative, or ask for human review first.
Suited tasks
Suited agents
Install decision
Trust and risk
Outcome loop
Install command
npx skills add iflytek/skillhub --skill api-and-namespace-designDo not use when
Agent safety v2
Sparse or mixed signals. Useful for discovery, but not for autonomous installation.
Test manually in an isolated workspace and compare against safer alternatives.
high
Skill metadata references terminal, CLI, shell, subprocess, or command execution workflows.
medium
Skill likely fetches remote pages, APIs, repositories, or external services.
high
Skill metadata references credentials, tokens, environment variables, or secret-bearing workflows.
medium
Skill may inspect schemas, query databases, or work with persistent stores.
Agent resolve plan
The Resolve API returns the selected skill, alternatives, safety policy, audit notes, install target, and copy-paste prompt an agent can follow without scraping this page.
Open JSON
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Resolve text
/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium&format=text
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
Agent should check
Copy prompt
Task: Use api-and-namespace-design in this workspace.
Resolve first: https://www.openagentskill.com/api/agent/resolve?task=Use%20api-and-namespace-design%20for%20an%20agent%20workflow&agent=codex&max_risk=medium
Review install handoff: https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install
Install command: npx skills add iflytek/skillhub --skill api-and-namespace-design
Before running it, summarize audit warnings, required permissions, and the fallback skill if install is risky.Agent handoff
Use the public install endpoint to fetch the command, safety checklist, target prompts, and canonical links for this skill.
Install handoff
/api/skills/iflytek-api-and-namespace-design/install
LLM text format
/api/skills/iflytek-api-and-namespace-design/install?format=text
Find alternatives
/api/skills/search?q=api-and-namespace-design&limit=3
Agent prompt
Use api-and-namespace-design for this task. Review https://www.openagentskill.com/api/skills/iflytek-api-and-namespace-design/install, then install with: npx skills add iflytek/skillhub --skill api-and-namespace-designRegistry metadata
This page exposes the same decision, trust, audit, use-case, and install signals through the Registry API, so agents can rank this skill without scraping the UI.
Manifest
/api/registry/manifest/iflytek-api-and-namespace-design
LLM text
/api/registry/manifest/iflytek-api-and-namespace-design?format=text
Install alias
/api/registry/install/iflytek-api-and-namespace-design
Recommend
/api/registry/recommend?task=Use%20api-and-namespace-design%20in%20an%20agent%20workflow&limit=3
Agent fit
RAG and knowledge
Platforms
Claude Code
Audit report
A machine-readable review of install readiness, security metadata, maintenance, and adoption risk.
Agent decision cockpit
Use this as a leading candidate, then validate the README and install path in your own agent stack.
Role in stack
Primary pick
Primary fit
RAG and knowledge
Trust label
Production-ready
Install path
Command ready
Use when
Evidence
review first
Implementation path
Trust profile
Useful candidate with missing or mixed trust signals. Keep it in an isolated workspace until the outcome loop proves task fit.
GitHub adoption
PASS4.9K GitHub stars
Stars/forks activity
PASS4.9K stars, 821 forks; issue activity unavailable in current metadata
Recent maintenance
PASS3d since push
License clarity
PASSApache-2.0
Good signals
Review before install
Recommended action
Run only in a sandbox and compare close alternatives before using it for real work.
Quality profile
Solid option that is likely worth shortlisting for production workflows.
Workflow fit
Search private knowledge
I need my agent to build a RAG workflow over documents and retrieve reliable context.
Parse messy files
I need my agent to read PDFs, extract tables, and turn documents into structured data.
Operate web apps
I need my agent to control a browser, fill forms, and verify web app workflows.
Workflow fit
Ingest, retrieve, and cite
A workflow for document-heavy agents that ingest files, create searchable knowledge, retrieve relevant context, and answer with grounded sources.
Operate and verify web apps
A workflow for agents that navigate products, fill forms, take screenshots, and verify real user flows across web applications.
Design, build, test, and ship interfaces
A practical workflow for agents that turn product briefs or Figma designs into polished frontend code, review the result, test it in a browser, and prepare a safe deployment.
--- 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
Source provenance
Decision snapshot
4,937 GitHub stars
Audit
Install and adoption review
Agent-proven evidence
Outcome reports after resolve, review, install, and one narrow run.
No agent outcome data yet. The first agent run can report success, setup needs, risk blocks, failure, or not-relevant through /api/agent/outcome.
Install
Free and open source. Review the report before installing into production agents.
Growth loop
Scenario-led draft for api-and-namespace-design, ready for a manual X post.
api-and-namespace-design: API design conventions, namespace coordinate system, RBAC roles, ClawHub compatibility layer,... 4.9K stars https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x
Listing + install path for api-and-namespace-design: https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=x Install: npx skills add iflytek/skillhub --skill api-and-namespace-design
Listing source
This listing was indexed from public sources and is not marked official until a maintainer claim is approved.
Attribution links to the public repository or creator profile. Creators can claim the listing to update ownership signals.
Claim this skillOwner claim
This Registry indexed listing is attributed to iflytek but is not marked official yet. Claim it to add a verified owner signal and make future launch, install, and audit updates easier to trust.
Creator backlink kit
Show the canonical listing, current trust and audit signals, and real Agent-Proven evidence where developers evaluate the repository.
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design/audit)
[](https://www.openagentskill.com/skills/iflytek-api-and-namespace-design?ref=github&utm_source=github&utm_medium=referral&utm_campaign=creator_badge)iflytek
@iflytek
Share whether this skill looks useful for your agent workflow. Aggregated feedback improves rankings over time.
Sandbox only
Permission surface
secrets or environment access, shell or command execution
Agent outcomes
No agent outcome data yet
Docs
Strong README/SKILL.md context
Risk summary
Install readiness
Permission surface
secrets or environment access, shell or command execution
Agent outcomes
No agent outcome data yet
Docs
Strong README/SKILL.md context
Risk summary
Install readiness
Permission surface
secrets or environment access, shell or command execution
Agent outcomes
No agent outcome data yet
Docs
Strong README/SKILL.md context
Risk summary
Install readiness
Permission surface
secrets or environment access, shell or command execution
Agent outcomes
No agent outcome data yet
Docs
Strong README/SKILL.md context
Risk summary
Install readiness