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

> Reusable agent instructions with observability — from SKILL.md to production analytics.

Skills are structured, reusable instructions that tell AI agents **how to perform specific tasks**. DecimalAI adds observability on top: tracking which skills activate, how effective they are, and how they change over time.

This is a long guide. Jump to what you need:

<CardGroup cols={3}>
  <Card title="What's a skill?" icon="circle-question" href="#what-is-a-skill">
    The SKILL.md format and frontmatter fields.
  </Card>

  <Card title="Get skills in" icon="upload" href="#getting-skills-into-decimalai">
    Auto-discovery from disk, SDK sync, or platform-first authoring.
  </Card>

  <Card title="Routing & sync" icon="route" href="#skill-routing">
    Smart routing, bidirectional sync, skill-specific evaluators.
  </Card>

  <Card title="Registry" icon="store" href="#community-registry">
    Publish to the public registry with SkillScore effectiveness.
  </Card>

  <Card title="Agents" icon="gear" href="#agent-skill-assignment">
    Per-agent skill assignment, dashboard, manifest tracking.
  </Card>

  <Card title="Playground" icon="flask" href="#testing-skill-changes-in-the-playground">
    Test skill edits against real production traces before saving.
  </Card>

  <Card title="Benchmark (eval.yaml)" icon="chart-line" href="/guides/skillevaluation">
    A/B benchmark the skill via the open `skillevaluation` spec.
  </Card>
</CardGroup>

## What Is a Skill?

A skill is a directory containing a `SKILL.md` file and optional supporting files:

```
code-review/
├── SKILL.md              ← The main instruction file
├── scripts/
│   └── scan.py           ← Helper script the agent can execute
└── references/
    └── owasp-top-10.md   ← Reference material the agent can read
```

Skills follow the open [agentskills.io](https://agentskills.io) specification. When an AI agent (Claude Code, Cursor, Copilot, etc.) encounters a matching task, it reads the `SKILL.md` and follows the instructions.

<Note>
  Skills are **not** tools. Tools are functions the agent can call (search, calculate, etc.). Skills are *instructions* that tell the agent *how* to approach a task — they're composable behavior units.
</Note>

### SKILL.md Format

Every skill has YAML frontmatter and a markdown body:

```markdown theme={null}
---
name: code-review
description: Reviews code for security vulnerabilities and bugs
license: MIT
allowed-tools:
  - bash
  - python
---

# Code Review

When asked to review code, follow this process:

## Step 1: Security Scan
Check for:
1. SQL injection vulnerabilities
2. Cross-site scripting (XSS)
3. Unvalidated input

## Step 2: Output Format
Present findings as a table:
| Issue | Severity | File | Line |
```

| Field           | Required | Description                                                                                                                                                                                                                                                                                                    |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | ✅        | Unique identifier (lowercase, hyphens)                                                                                                                                                                                                                                                                         |
| `description`   | ✅        | Short description (used for routing and registry)                                                                                                                                                                                                                                                              |
| `license`       |          | MIT, Apache-2.0, etc.                                                                                                                                                                                                                                                                                          |
| `allowed-tools` |          | Tools the skill may invoke                                                                                                                                                                                                                                                                                     |
| `category`      |          | Grouping category                                                                                                                                                                                                                                                                                              |
| `stability`     |          | `stable`, `experimental`, or `deprecated`                                                                                                                                                                                                                                                                      |
| `skill-type`    |          | Does the base model lack the ability (`capability`) or just the form (`preference`)? Drives the registry type badge and, with `skill-scope`, tells you when the skill should retire — see [Authoring Skills](/guides/authoring-skills#the-two-axes). Legacy `model-gap`/`proprietary`/`convention` still parse |
| `skill-scope`   |          | Is the knowledge a `public` standard the base may learn, or `private` house knowledge it never will? Only `capability` + `public` skills expire                                                                                                                                                                |
| `invocation`    |          | Who fires the skill: `model` (Automatic — the model triggers it from the description), `user` (On-demand — only when explicitly called), or `any`. Default `model`                                                                                                                                             |

<Note>
  **On-demand skills cost zero context until called.** A skill with `invocation: user` is excluded from the ambient skill menu and smart routing — it never occupies your agent's context until you explicitly invoke it (e.g. `router.get_skill_body(name)`). Claude Code's `disable-model-invocation: true` means the same thing; DecimalAI round-trips both spellings on import and export.
</Note>

***

## Getting Skills Into DecimalAI

There are two separate questions, and it helps to keep them apart:

1. **How does a skill get into your workspace?** Three sources, covered below: auto-discovery from disk, install from the public registry, or manual creation.
2. **How does a skill reach a running agent?** Once it's in your workspace, pick **one** delivery path per runtime: hosted routing via the [Skill Router](/api-reference/skills/router) (your SDK agent asks the platform which skills to load on each query — this is the path that measures effectiveness and powers the leaderboard) **or** disk export (DecimalAI writes the open-format `SKILL.md` into the directories Claude Code / Cursor / etc. already scan, and the runtime loads it itself).

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart TD
  A[Auto-discovery from disk] --> W[Your workspace]
  B[Install from public registry] --> W
  C[Manual creation] --> W
  W --> G{Pick ONE delivery<br/>path per runtime}
  G -->|SDK-driven agents| R[Hosted routing<br/>Skill Router]
  G -->|File-based runtimes| D[Disk export<br/>SKILL.md]
```

<Warning>
  Running both delivery paths for the same runtime double-injects the skill into the system prompt. Pick one. See the [Skill Router — Router vs disk auto-loading](/api-reference/skills/router#router-vs-disk-auto-loading-pick-one) section for the full decision matrix; the SDK logs a one-shot warning when it detects this configuration.
</Warning>

### 1. Auto-Discovery (Bring Your Own)

If you already have SKILL.md files, DecimalAI discovers them automatically:

```python theme={null}
import decimalai
decimalai.init(api_key="dai_sk_...")

from decimalai.openai_agents import install
install()  # auto-discovers SKILL.md files from disk
```

The SDK scans standard directories:

| Location            | Scope                                    |
| ------------------- | ---------------------------------------- |
| `.agents/skills/`   | Universal (Cursor, Copilot, Cline, Warp) |
| `.claude/skills/`   | Claude Code                              |
| `.windsurf/skills/` | Windsurf                                 |
| `.continue/skills/` | Continue                                 |
| `~/.claude/skills/` | Global / personal                        |

<Tip>
  **Your files are never modified or moved.** DecimalAI acts as a passive observer — it reads SKILL.md files to build the registry but never alters them.
</Tip>

### 2. From the Public Registry

Browse community skills and install them:

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

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

# Install "pdf" skill for Claude Code and Cursor
result = router.install("pdf", agents=["claude-code", "cursor"])
```

This forks the skill into your org, writes `SKILL.md` + attachments to disk, and creates a lockfile at `.decimal/skills.lock`.

### 3. Manual Creation

Create skills directly via the SDK or API:

```python theme={null}
router.create_skill(
    name="my-custom-skill",
    description="Does something specific",
    body_markdown="# My Skill\n\nInstructions...",
    category="automation",
)
```

***

## How Skills Are Tracked

### Auto-Versioning

Every time you edit a SKILL.md and restart your app, the SDK:

1. Re-discovers the file
2. Computes a content hash
3. If the hash changed → creates a new version automatically

No manual tagging needed. The dashboard shows version history with [SkillScore](/guides/skillscore) trends:

| Version          | Date   | Pass rate | Trend             |
| ---------------- | ------ | --------- | ----------------- |
| **v3** (current) | Apr 17 | 88%       | ↗ Improved by 4%  |
| v2               | Apr 10 | 84%       | ↗ Improved by 12% |
| v1               | Apr 1  | 72%       | —                 |

### Activation Detection

The SDK detects which skills were activated by comparing the LLM's rendered prompt against known skill bodies. This works automatically across all frameworks — no code changes needed.

Each trace includes `active_skills` metadata:

```json theme={null}
{
  "trace_id": "abc-123",
  "active_skills": [
    {"name": "code-review", "hash": "a1b2c3d4e5f6"}
  ]
}
```

### Effectiveness Scoring

The platform correlates skill activations with trace evals to compute:

* **Pass rate**: % of traces with the skill that evaluated as "pass"
* **Effectiveness**: The skill's [SkillScore](/guides/skillscore) — a 0–100 composite from benchmark lift (the with-vs-without improvement), live eval pass rates, AI-judge quality, and cross-org adoption
* **Trend**: Improvement or regression over time

<Accordion title="How activation detection works internally">
  The SDK uses a three-tier approach:

  1. **Prompt-diff matching** — Compares the rendered LLM prompt against known skill bodies using fuzzy content matching
  2. **Span attribute detection** — Checks for `decimal.active_skills` span attributes (OTel frameworks)
  3. **Explicit declaration** — `trace.log_skill_activation(name="code-review")` for manual control

  Priority: explicit > span attributes > prompt-diff. Multiple tiers can be active simultaneously.
</Accordion>

***

## Skill Routing

When your agent needs to select which skills to load, DecimalAI offers two routing strategies:

### Menu Injection (Simple)

Dump all skill names + descriptions into the system prompt and let the LLM decide:

```python theme={null}
router = SkillRouter(api_key="dai_sk_...")

menu = router.get_menu()
system_prompt += menu["prompt_fragment"]
```

Best for agents with \< 20 skills.

### Smart Routing (Semantic)

For larger skill sets, smart routing uses **semantic search + performance-weighted re-ranking**:

```python theme={null}
router = SkillRouter(api_key="dai_sk_...", strategy="auto")

prompt_fragment = router.get_menu_prompt(
    query="Review this PR for security issues"
)
system_prompt += prompt_fragment
```

This embeds the user query, matches against skill descriptions via cosine similarity, then re-ranks by [SkillScore](/guides/skillscore). Skills with higher measured quality on similar queries get boosted.

<Note>
  `get_menu_prompt(query=...)` returns just the ready-to-inject prompt string. If you want the ranked skills plus the fragment together, call `router.smart_route(query=...)` — same semantic + effectiveness ranking, but it returns the full result dict (`skills`, `prompt_fragment`, `strategy`). The [pricing page](/pricing) and [Skill Router reference](/api-reference/skills/router) use `smart_route()`; both are real.
</Note>

### Progressive Disclosure (Bodies on Demand)

Both strategies above surface skill **descriptions** — a one-line menu row per skill. The full instructions (the `SKILL.md` body) load on demand: on the `openai_agents` and `pydantic_ai` adapters, enabling the skill loader auto-registers a `load_skill(name)` tool on every agent. The model reads the menu, decides a skill applies, calls `load_skill("skill-name")`, and the body arrives as a tool result — then it executes with the full instructions in context.

Descriptions stay cheap (budgeted at \~1,500 estimated tokens / 30 rows) and bodies are budgeted too (at most 3 per turn, \~6,000 tokens total, 8 KB per body), so a growing registry can't blow the context window. Adapters without a tool loop (`anthropic`, `langchain`) deliver bodies by prompt injection instead (`inject_skill_body=True`), with the same trim and budget.

<Note>
  The routing menu only offers skills the calling user may see: `personal` skills surface only to their creator and `workspace` skills only to members of the owning workspace (plus explicit shares); `org` and `public` skills surface org-wide. API-key-authenticated agents see the org-wide set.
</Note>

Building a whole agent as a lean main prompt plus a routed skill bundle? See [Assemble an agent from skills](/guides/agents-from-skills).

***

## Bidirectional Sync

Skills sync automatically between your local files and the platform:

```python theme={null}
from decimalai.openai_agents import install
install(agent_name="claude-code")
# ↑ pushes local skills TO platform
# ↑ pulls platform-only skills TO disk
# ↑ updates local skills that changed on the platform
```

| Disk State      | Platform State | Action                           |
| --------------- | -------------- | -------------------------------- |
| SKILL.md exists | Same hash      | Nothing (in sync)                |
| SKILL.md exists | Different hash | **Platform wins** — disk updated |
| SKILL.md exists | Doesn't exist  | Push disk → platform             |
| No SKILL.md     | Skill exists   | **Pull platform → disk**         |

<Warning>
  All sync operations run in background threads and never block startup. However, if the platform is unreachable, the SDK falls back to local-only mode — skills are still discovered from disk.
</Warning>

***

## Community Registry

Browse, install, fork, and publish skills in the public registry. The full
lifecycle — discover, install, receive upstream updates, publish your own
— is covered in its own guide:

<Card title="Community Registry guide" icon="store" href="/guides/registry">
  Browse without signing up · install in one call · receive upstream
  updates · publish your own with effectiveness data attached.
</Card>

***

## Agent Skill Assignment

Once a skill is in your organization (created manually or installed from the registry), you need to **assign** it to specific agents. This gives you fine-grained control over which agents use which skills.

### Assigning from the Skill Settings Tab

Navigate to any skill detail page → **Settings** tab → **Agent Assignments** section:

* **Select an agent** from the dropdown and click "Assign"
* **Remove** an assignment by clicking the "Remove" button next to an assigned agent
* Each assignment shows the version mode: **Latest** (auto-updates) or **Pinned** (locked to a specific version)

### Assigning from the Agent Skills Tab

Navigate to any agent → **Skills** tab:

* Click **"+ Add Skill"** in the table header → a picker modal shows all org skills not yet assigned
* Search, multi-select, and click **"Assign"** to batch-assign skills
* Click **"Browse Registry →"** to discover and install new skills from the public registry

### How Assignment Works at Runtime

When an agent runs, the Skill Router checks which skills are subscribed to that agent:

```python theme={null}
# The SDK handles this automatically:
# 1. Fetch subscribed skills for this agent
# 2. Build the skill menu (prompt fragment)
# 3. Inject into the system prompt
# 4. Track which skills activate per trace
```

Skills assigned to an agent are injected into its prompt context at runtime. The platform then tracks which skills actually activated on each trace for analytics.

***

## Agent Skills Dashboard

The **Skills** tab on each agent's dashboard provides full observability into how skills perform for that specific agent.

### Summary Cards

Four metrics at the top:

| Metric                | Description                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| **Skills Used**       | Number of distinct skills that have activated on this agent's traces                      |
| **Total Activations** | Cumulative skill activation count across all traces (30d)                                 |
| **Avg Pass Rate**     | Mean eval pass rate across all skills                                                     |
| **Avg Effectiveness** | Mean [SkillScore](/guides/skillscore) across all skills — a quality composite, not volume |

### Activation Timeline (30d Heatmap)

A GitHub-style heatmap grid showing daily activation intensity for each skill over the last 30 days:

* **Rows** = skills (top 6 by effectiveness)
* **Columns** = days (30 cells, left = 30 days ago, right = today)
* **Color intensity** = activation volume (darker green = more activations)
* **Hover** = exact date, activation count, and pass rate

This lets you quickly spot:

* Which skills are used most frequently
* Whether a skill's usage is increasing or declining
* Days with unusually high or low activity

### Skill Insights

Auto-generated insight cards based on the data:

* 🏆 **Top Skill** — The skill with the highest [SkillScore](/guides/skillscore), shown with its pass rate and usage count
* 📈 **Improving** — Skills whose pass rate is trending upward over the last 15 days
* ⚠️ **Degrading** — Skills whose pass rate is declining, with a suggestion to review the latest version

### Leaderboard Table

All skills ranked by effectiveness with columns:

| Column              | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **Uses**            | Activation count for this agent (30d)                                    |
| **% Evals Passed**  | Percentage of evals that passed on traces using this skill               |
| **% Trace Success** | Percentage of traces that completed without errors                       |
| **Effectiveness**   | Composite score with color-coded bar (green ≥70%, amber ≥40%, red \<40%) |
| **Trend**           | Direction indicator: ↑ improving, → stable, ↓ degrading                  |

***

## Skills and Manifests

Skills are tracked as a `skill_registry` surface in your agent's version manifest. When the skill registry changes, a new manifest version is registered:

| What Changes                             | New Manifest? | Why                                |
| ---------------------------------------- | ------------- | ---------------------------------- |
| Skill registry updated (add/remove/edit) | ✅ Yes         | Different available behaviors      |
| Different skills activated per task      | ❌ No          | Same agent, different runtime path |
| Skill content edited (body changed)      | ✅ Yes         | Available instructions changed     |

Skill changes follow the same compatibility policy as other surfaces (keep/repair/replay/drop). See [Manifests & Versioning](/guides/manifests) for details.

***

## Testing Skill Changes in the Playground

Before saving a skill edit, test it against real production traces in the Playground — open a skill detail page, click **"Test in Playground"**, edit the body, and run it side-by-side against the original output. See the [Playground guide](/guides/playground) for the full procedure.

***

## Writing Effective Skills

The five tips that matter most:

1. **Only teach what the model can't infer.** Skills lift when they supply knowledge the model doesn't have — your house conventions, a spec's exact rules, a new API. Generic advice ("write clean code", "be thorough") measures zero lift.
2. **Write the description as the trigger.** State what the skill does *and* when to use it, in third person, with one "Do NOT use for …" clause. Both search retrieval and the model's skill menu read this one string — it decides whether the skill ever fires.
3. **Directives, not essays.** "Always use `client.interactions.create()` for chat. Never use `generate_content` (it drops session state)" beats a paragraph of background. One worked before→after example beats five paragraphs.
4. **If a program can check it, make it a validator; if exact steps are required, write a script.** Put deterministic checks in your eval's `validators`, and fragile step-by-step operations in `scripts/` — code is exact, prose pretending to be code is not.
5. **Every line costs tokens on every activation.** Apply the no-op test: remove the line — does output change? No → delete it. Shed real depth into `references/` instead of bloating the body.

<Card title="Authoring Skills — the full guide" icon="pen-ruler" href="/guides/authoring-skills">
  Classify your skill on two axes (capability / preference, public / private), write the description as the trigger, build an honest eval suite with trigger cases, and know when the skill should retire.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Skills Observability tutorial" icon="microscope" href="/tutorials/skills-observability">
    See per-skill activation counts, pass rates, and smart routing in action.
  </Card>

  <Card title="Skills API" icon="code" href="/api-reference/skills/overview">
    REST reference for create, sync, fork, publish, version diff.
  </Card>

  <Card title="Skills & Data Pipeline" icon="book-open" href="/concepts/skills-and-data">
    Conceptual model — skills vs tools, activation tracking, effectiveness.
  </Card>

  <Card title="Public registry" icon="store" href="https://app.decimal.ai/skills">
    Browse community skills ranked by SkillScore — measured quality from live activations, not install counts.
  </Card>
</CardGroup>