> ## Documentation Index > Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a skill > Create a new skill with its first version. Ownership is set automatically: - `creator_user_id` from the authenticated user - `owning_workspace_id` from the payload or auth context Name must be lowercase alphanumeric with hyphens/underscores (1-200 chars). Visibility must be one of: `org`, `workspace`, `personal`, `public`. Stability must be one of: `stable`, `experimental`, `deprecated`. Supports `X-Idempotency-Key` for safe retries — within 60s, a request with the same key returns the original response instead of creating a duplicate. ## OpenAPI ````yaml /openapi.json post /api/v1/skills openapi: 3.1.0 info: title: DecimalAI Platform description: Agent Dataset Lifecycle Platform — Backend API version: 0.1.0 servers: [] security: - BearerAuth: [] tags: - name: traces description: >- Ingest, search, and inspect agent execution traces. A trace is the atomic unit of the platform — every other feature (evaluation, compatibility scoring, dataset building) operates on traces. Each trace is auto-tagged with the manifest hash of the agent that produced it. - name: eval-scores description: >- Push, fetch, and aggregate per-trace evaluation scores. Scores carry source provenance (built-in, DeepEval, LangSmith, custom) and feed the unified decision engine, which produces a keep / repair / replay / drop verdict per trace. - name: skills description: >- Manage reusable instruction blocks (SKILL.md files) that modify agent behavior. Skills are first-class manifest components — changes to a skill appear in your regression-check impact reports. Use these endpoints to create, version, fork, and sync skills with your local SKILL.md files. - name: manifests description: >- Register and inspect manifest versions. A manifest is a snapshot of your agent's structural identity (tools, prompts, models, skills) at a point in time. The SDK registers manifests automatically; these endpoints expose the underlying records. - name: datasets description: >- Build versioned SFT/DPO training datasets from manifest-classified, eval-scored traces. Datasets are reproducible — each version locks the manifest and filter set used to build it. Export as JSONL, Parquet, or push to HuggingFace Hub. - name: replay description: >- Re-execute historical traces against a new manifest version. Replay is the deferred-future capability for behavioral verification of agent changes. The SDK creates a replay batch, your worker executes each task, then submits results back here for eval scoring. - name: registry description: >- Browse and install community skills from the public skills registry. Each registry skill carries a SkillScore — an evidence-tiered quality composite computed from real-world evals, benchmarks, and ratings across organizations. Installing creates a fork in your org — edits don't affect the public version. - name: agents description: >- List and inspect agents, plus their multi-agent topology (orchestrator → sub-agent edges discovered from traces). Agents are identified by a stable agent_name string set in your SDK init() call. - name: import description: >- Bulk-import historical traces from another observability platform or a JSONL backup. Useful for migrating from LangSmith / Braintrust / Langfuse. Duplicate trace IDs are silently skipped — re-running an import is safe. paths: /api/v1/skills: post: tags: - skills summary: Create a skill description: >- Create a new skill with its first version. Ownership is set automatically: - `creator_user_id` from the authenticated user - `owning_workspace_id` from the payload or auth context Name must be lowercase alphanumeric with hyphens/underscores (1-200 chars). Visibility must be one of: `org`, `workspace`, `personal`, `public`. Stability must be one of: `stable`, `experimental`, `deprecated`. Supports `X-Idempotency-Key` for safe retries — within 60s, a request with the same key returns the original response instead of creating a duplicate. operationId: create_skill_api_v1_skills_post parameters: - name: Authorization in: header required: false schema: type: string title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id - name: X-Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Idempotency-Key - name: decimal_session in: cookie required: false schema: anyOf: - type: string - type: 'null' title: Decimal Session requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSkillRequest' examples: minimal: summary: Minimal — name, description, body value: name: search-flights description: Search available flights body_markdown: |- # Search Flights ## When to activate Use this when the user asks about flight availability. full: summary: Full — with category, stability, trigger phrases value: name: search-flights description: >- Search available flights given origin, destination, and dates. body_markdown: > # Search Flights ## When to activate Use this when the user asks about flight availability between two cities. ## Process 1. Parse origin, destination, and date range from the user's request. 2. Call the flight search API. 3. Rank results by price ascending, then by departure time. category: tools stability: stable trigger_phrases: - find flights - search for flights responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateSkillResponse' example: status: ok skill_id: sk_abc123 name: search-flights version: 1 '409': description: A skill with this name already exists in the org. '422': description: Validation failed (invalid name, body too short, etc.). x-codeSamples: - lang: Python label: Python SDK source: |- from decimalai.skill_router import SkillRouter router = SkillRouter(api_key="dai_sk_...") router.create_skill( name="search-flights", description="Search available flights", body_markdown="# Search Flights\n\n## When to activate\nUse when the user asks about flight availability.", ) components: schemas: CreateSkillRequest: properties: name: type: string maxLength: 200 minLength: 1 title: Name description: URL-safe slug. Lowercase alphanumeric with hyphens/underscores/dots. examples: - search-flights display_name: anyOf: - type: string maxLength: 200 - type: 'null' title: Display Name description: >- Human registry title shown instead of the slug `name`. Optional — the registry humanizes the slug when omitted. examples: - Search Flights description: type: string maxLength: 1024 minLength: 1 title: Description description: Short one-line description shown in the skill registry. examples: - Search available flights given origin, destination, and dates. body_markdown: anyOf: - type: string minLength: 1 - type: 'null' title: Body Markdown description: Full SKILL.md body. At least 50 characters of substantive content. body: anyOf: - type: string minLength: 1 - type: 'null' title: Body description: Alias for body_markdown — accepted for backwards compatibility. visibility: type: string title: Visibility description: 'One of: org, workspace, personal, public.' default: org examples: - org stability: type: string title: Stability description: 'One of: stable, experimental, deprecated.' default: stable examples: - stable category: anyOf: - type: string maxLength: 100 - type: 'null' title: Category description: Optional grouping label, e.g. 'tools', 'policies', 'workflows'. examples: - tools skill_type: anyOf: - type: string - type: 'null' title: Skill Type description: >- Taxonomy class: capability or preference. Defaults to the frontmatter `skill-type:` when omitted (legacy model-gap/proprietary/convention labels still accepted). examples: - preference skill_scope: anyOf: - type: string - type: 'null' title: Skill Scope description: >- Knowledge scope: public or private. Pairs with skill_type; defaults to the frontmatter `skill-scope:` when omitted (or the scope a legacy skill-type implies). examples: - public invocation_mode: anyOf: - type: string - type: 'null' title: Invocation Mode description: >- Who may fire the skill: model, user, or any. Defaults to the frontmatter `invocation:` when omitted, else 'model'. examples: - model trigger_phrases: anyOf: - items: type: string type: array - type: 'null' title: Trigger Phrases description: Phrases that hint the skill should activate. Used by smart routing. examples: - - find flights - search for flights frontmatter: anyOf: - additionalProperties: true type: object - type: 'null' title: Frontmatter description: Raw frontmatter dict parsed from the SKILL.md header. change_summary: anyOf: - type: string - type: 'null' title: Change Summary description: Optional message attached to the first version. author: anyOf: - type: string - type: 'null' title: Author description: Optional author label for the first version. project_id: anyOf: - type: string - type: 'null' title: Project Id description: Scope the skill to a specific project. workspace_id: anyOf: - type: string - type: 'null' title: Workspace Id description: Owning workspace ID. Defaults to the caller's current workspace. type: object required: - name - description title: CreateSkillRequest description: >- Validated request for POST /skills. Uses relaxed name validation (allows underscores, dots, up to 200 chars). CreateSkillResponse: properties: status: type: string const: ok title: Status skill_id: type: string title: Skill Id description: Stable ID, always prefixed 'sk_' name: type: string title: Name version: type: integer title: Version description: Starts at 1; increments on each body change type: object required: - status - skill_id - name - version title: CreateSkillResponse securitySchemes: BearerAuth: type: http scheme: bearer description: Enter your API key (e.g. dai_sk_test_key_001) ````