> ## 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.

# Skills API

> Create, version, fork, and publish reusable instruction blocks (SKILL.md). First-class manifest components.

Skills are reusable instruction blocks (typically SKILL.md files) that modify how an agent thinks. Unlike tools — which add capability — skills shape behavior. They're first-class manifest components, so a change to a skill appears in your regression-check impact report.

The runtime that picks the right skill for the right query is the **[Skill Router](/api-reference/skills/router)** — read that first if you haven't.

## Lifecycle

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart LR
    A[create / sync] --> B[list]
    B --> C[get]
    C --> D[update]
    D --> E[versions]
    D -.->|re-sync| A
    C --> X[delete]
    E --> F[publish to registry]
    F --> G[SkillScore]
    G --> H[install fork]
    H --> I[fork in another org]
```

The `SkillRouter` Python class wraps every CRUD operation; the REST endpoints below are what it calls under the hood.

## Common patterns

<CardGroup cols={2}>
  <Card title="Routing at runtime" icon="route" href="/api-reference/skills/router">
    The Skill Router picks which skills to load on every query — and produces the telemetry that scores them.
  </Card>

  <Card title="Bulk-sync from disk" icon="folder-tree" href="/sdk/python/skills">
    Watch `./skills/*.md`, send the whole batch on every change. The platform diffs by content hash — unchanged files are no-ops.
  </Card>

  <Card title="Publish to registry" icon="store" href="/api-reference/registry/overview">
    Skills with `visibility=public` appear in the [registry](/api-reference/registry/overview). SkillScore (0–100, quality-only: live eval pass + AI-judge rating) is computed from real activations.
  </Card>

  <Card title="Version history" icon="clock-rotate-left">
    Each body change creates a new version. The version history is the audit log — every version preserves its body markdown and content hash.
  </Card>
</CardGroup>

## Quick start

```python theme={null}
from decimalai.skill_router import SkillRouter

router = SkillRouter(api_key="dai_sk_...")

# Create a skill
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.",
)

# Sync many skills at once from a local directory
from decimalai.skills import discover_skills
router.sync_skills(skills=discover_skills(["./skills"]))

# Smart-route a query to the best skill (see /api-reference/skills/router for details)
result = router.smart_route(query="Find flights to Tokyo", top_k=5)
```

## Concepts

* **Skill** vs **tool**: a skill is a structured instruction; a tool is an executable function. See [Skills & Data Pipeline](/concepts/skills-and-data) for the distinction.
* **Skill activation**: a record of which skills were loaded for a given trace — used for effectiveness analytics. The [Router](/api-reference/skills/router) produces these.
* **Fork**: installing a registry skill creates a fork in your org. Edits to your fork don't affect the public version.

## Related

* [Skill Router](/api-reference/skills/router) — the runtime concept + telemetry it produces
* [Skills Guide](/guides/skills) — hands-on tutorial
* [Skills & Data Pipeline](/concepts/skills-and-data) — conceptual model
* [Registry API](/api-reference/registry/overview) — browse / fork public skills