Skills

The SDK surface for skills. A skill is instructions that shape how the model behaves, and a tool is a function it can run: see How it works. How skills reach a model at run time is on How skills reach the model. The REST calls behind it are on the Skill router contract.

Install registry skills into your project

pip install "decimalai>=0.27"
decimalai skills add acme/refund-policy

What this does depends on whether the project is connected to DecimalAI. A project connects when agent_config() first runs with an API key in a git repository, which writes .decimal/link.toml.

Not connected: it writes the three things below, all meant to be committed. It creates no fork and no link on DecimalAI.
Connected, or with --to-agent <name>: it adds the skill to the agent on DecimalAI and writes no files. It needs an API key.

.agents/skills/acme-refund-policy/   the skill's folder: SKILL.md plus its scripts/ and references/
.decimal/skills.toml                 which skills the project wants, at which version
.decimal/skills.lock                 the exact version and the hash of every file written

The folder name is the skill’s install name: the registry name made safe for a folder, and also the name: in its SKILL.md. CI and Docker builds run decimalai skills install --frozen, which writes the locked bytes or fails. With an API key you can install your own skills, skills you’ve linked, and public ones. With no key, public skills only. Skills on disk has the files, commands, exit codes and CI recipes. The same engine is a Python API. It always writes files, connected or not:

from decimalai import skillpkg

result = skillpkg.add("acme/refund-policy")    # the file half of `decimalai skills add`
skillpkg.install(frozen=True)                  # decimalai skills install --frozen
skillpkg.update()                              # decimalai skills update
skillpkg.status()                              # decimalai skills status
skillpkg.remove("acme-refund-policy")          # decimalai skills remove

if not result.ok:
    print(result.exit_code, [str(p) for p in result.problems])

Each call returns a Result with changes, problems and exit_code, and a refusal is returned, not raised. The key comes from api_key= or DECIMAL_API_KEY. A skill whose safety review is caution or unreviewed is refused when there’s no terminal to ask on, unless you pass yes=True. To add a skill to an agent on DecimalAI from Python, use router.assign_skill().

Load installed skills with a framework loader

decimalai.skills_dir() returns the project’s root, .agents/skills, as an absolute path, from any subdirectory. Each framework with a skill loader of its own has a helper that points the loader at that root. Import its module first (import decimalai.adk), since import decimalai alone doesn’t load it:

Framework	The call
Claude Agent SDK	`ClaudeAgentOptions(plugins=[decimalai.claude_agent_sdk.skills_plugin()])`. See Claude Agent SDK
Claude Code (interactive)	`claude --plugin-dir "$(git rev-parse --show-toplevel)/.agents"`. See Claude Code
Google ADK	`SkillToolset(skills=decimalai.adk.skills(), code_executor=...)`. See ADK
OpenAI Agents (sandbox)	`SandboxAgent(..., capabilities=[Shell(), decimalai.openai_agents.sandbox_skills()], default_manifest=Manifest())`. See OpenAI Agents
CrewAI	`Agent(..., skills=decimalai.crewai.skills(), tools=decimalai.crewai.skill_tools())`. See CrewAI
Pydantic AI harness	`decimalai.pydantic_ai_harness.skills(project)` beside `LocalWorkspace(project)`. See Pydantic AI
Deep Agents	`create_deep_agent(model, **decimalai.deepagents.skills())`. See Deep Agents
Microsoft Agent Framework	`Agent(..., context_providers=[decimalai.agent_framework.skills()])`. See Microsoft Agent Framework
Strands	`Agent(..., plugins=[decimalai.strands.skills()])`. See Strands

skills_dir() raises SkillsNotInstalledError when the project has no .decimal/skills.lock or no .agents/skills, and LegacyLockError for a lock in an old format (run decimalai skills migrate). DecimalAI’s own skill list stays out of an agent whose loader serves its skills, so the model sees one list. See Don’t deliver a skill two ways.

Record what a native loader loaded

With DecimalAI’s instrumentation on, each skill a framework’s loader hands the model is recorded on the run’s trace as an activation, the Loaded step. It carries the skill id and the version the model received, decided from the delivered bytes rather than the folder on disk. See What DecimalAI records. Anywhere else, such as a framework with no DecimalAI adapter, record the load yourself in a run you trace with decimalai.start_trace():

import decimalai

decimalai.init(api_key="dai_sk_...")

with decimalai.start_trace(agent_name="support-agent"):
    # your framework loads acme-refund-policy and answers
    decimalai.log_skill_activation(name="acme-refund-policy")

Inside the project, the SDK sends a name it recognises as an installed folder under the skill’s registry identity: the install name, Claude Code’s decimalai-skills:acme-refund-policy, or the folder’s path. The trace carries acme/refund-policy, and the activation carries the skill id, version id and body hash from the lock. A folder you edited is credited to its skill, never to the locked version. The folder is hashed when the trace is sent, so after a skills update a loader that cached the old version is credited with the new one. The helpers above don’t have that problem. When the process runs somewhere the lock isn’t, pass the identity yourself. skill_id, version_id and body_sha256 are keyword arguments of both log_skill_activation() and log_skill_loaded(). The values sit in the installed SKILL.md’s metadata, and decimalai.skills.discover_skills() returns them on each descriptor:

import decimalai
from decimalai.skills import discover_skills

decimalai.init(api_key="dai_sk_...")
installed = {s["name"]: s for s in discover_skills() if s["managed"]}
skill = installed["acme-refund-policy"]

with decimalai.start_trace(agent_name="support-agent"):
    decimalai.log_skill_loaded(
        name=skill["registry_name"],
        skill_id=skill["skill_id"],
        version_id=skill["version_id"],
        body_sha256=skill["body_sha256"],
    )

Both functions raise DecimalConfigError outside a trace. log_skill_loaded() says the body reached the model. With an id or a hash, it also records an activation carrying them, unless you declared one for that name already.

Pull a public skill

For a loose copy of a published skill, pull needs no API key:

decimalai skills pull playwright-cli           # ./playwright-cli/: SKILL.md, bundled files, eval.yaml
decimalai skills pull pdf --stdout > pdf.md    # print SKILL.md, for piping into another tool

No lock records the copy and nothing updates it. A folder that already holds different files is left alone unless you pass --force. More: skills pull.

Sync skills from code to platform

Skills you wrote can be uploaded as your agent starts:

from decimalai.openai_agents import instrument

instrument(
    agent=agent,
    skill_dirs=["./skills/"],  # scans for SKILL.md files
)

skill_dirs is an argument of three instrument() calls, in decimalai.openai_agents, decimalai.langchain and decimalai.otel, and of decimalai.start_trace(). This upload is one-way: it sends the skills you wrote and writes nothing to disk. A folder decimalai skills installed is read but never uploaded, since that would make a private copy of a registry skill in your organization. To sync both ways from a terminal or CI, use decimalai skills sync. To upload a folder from a script, with no agent running, use sync_to_platform():

import os

from decimalai.skills import sync_to_platform

result = sync_to_platform(
    os.environ["DECIMAL_API_KEY"],
    search_paths=["./skills"],
    agent_name="support-agent",   # also adds the skills to this agent
)
print(result["created"], result["updated"], result["unchanged"])

The platform compares each skill’s text by hash: an unchanged skill does nothing, and a changed one gets a new version. Installed folders are left out here too. When the platform’s copy has changed as well, the newer one wins unless you pass conflict_policy="local_wins", which suits CI where the repository is the source of truth.

`SkillRouter`: manage skills from code

import decimalai
from decimalai import SkillRouter

decimalai.init(api_key="dai_sk_...", agent_name="support-agent")

# Uses init()'s key, base URL and agent. Arguments you pass win:
# SkillRouter(api_key=key, base_url=url, agent_name=name)
router = SkillRouter()

# What an agent is offered
menu = router.get_menu()
chosen = router.smart_route(query="How do I cancel my subscription?")

# Create a skill. agent_name= also adds it to that agent
created = router.create_skill(name="refund-policy", description="Refund policy",
                              body_markdown="Refunds within 30 days.", agent_name="support-agent")
skill_id = created["skill_id"]

# offer_scope= says which agents get it: "restricted" (the default) is only the agents
# you add it to, and "workspace" is every agent
router.create_skill(name="house-style", description="House style",
                    body_markdown="Answer in plain English.", offer_scope="workspace")

# Read and change
router.list_skills()
router.get_skill("refund-policy")
router.update_skill(skill_id, body_markdown="Refunds within 45 days.")
router.list_versions("refund-policy")    # newest first
router.get_version("refund-policy", 1)   # one version, with its body_markdown
router.delete_skill(skill_id)

# Add a skill to one agent, or take it off
router.assign_skill("support-agent", skill_id)      # pin_version_id= serves one version
router.unassign_skill("support-agent", skill_id)    # needs a key with admin permission

# Bulk: upload a list of skills, and add them to an agent
router.sync_skills([{"name": "refund-policy", "body_markdown": "Refunds within 30 days."}],
                   agent_name="support-agent")

# Registry skills in your workspace
router.use("pdf")     # a link that tracks the author's updates
router.fork("pdf")    # an editable copy, offered only to the agents you add it to

# Files: the same engine as the commands, with this router's key
router.export("pdf")     # the file half of `decimalai skills add`
router.update_skills()   # decimalai skills update
router.status()          # decimalai skills status

assign_skill() also takes a public registry skill’s id, which links it for that agent only. An agent DecimalAI hasn’t seen yet is created. Assigning again only updates the pin.
unassign_skill() takes away a "restricted" skill. A "workspace" skill is still offered, as to every agent.
delete_skill() deactivates the skill.
update_skill() makes a new version only when the text changes. Every version keeps its text and content_hash, so you can read two with get_version() and compare them.
A skill is part of your agent’s manifest, so a changed skill shows up in a regression check’s report.
router.export() writes .agents/skills/ and the lock, connected or not. export, update_skills and status take project_root=.

Which agents get a skill: Which agents get a new skill. Links and forks: Update, pin or fork. Making a skill public: Publish a skill. The REST routes: Common endpoints. Older methods and their replacements: Migrations.

On-demand bodies: the `load_skill` tool

agent_config() gives your agent a skill list and a load_skill tool, which How skills reach the model explains, along with what a load can reach and how to turn it off. This section is for a SkillRouter you drive yourself. Body loads are budgeted per turn so they can’t blow the context window:

`SkillRouter` knob	Default	Effect
`max_loaded_bodies`	3	Max distinct bodies per turn. Further loads get a refusal message
`body_token_budget`	6000	Estimated-token cap across all loaded bodies
`per_body_char_limit`	24,000 (`4 × body_token_budget`)	A longer body isn’t loaded and the model gets a refusal message. Bodies arrive complete or not at all
`body_load_deadline_s`	20	Wall-clock cap on body round trips within a turn

Loading a skill again in the same turn is free. Each load is recorded on the trace as skills_loaded_by_agent.

from decimalai import SkillRouter

router = SkillRouter(agent_name="support-agent")
user_message = "Can I get a refund after 45 days?"

router.load_skill("refund-policy")       # budgeted; returns a "## Skill: ..." block or a message for the model
router.get_skill_body("refund-policy")   # raw fetch, no budget; max_chars= asks the server to trim

# A hand-written loop that loads inside an agent run: name the run's decision,
# so the platform limits the load to what that decision offered.
fragment, routing_id = router.build_prompt_fragment(query=user_message)
record = router.get_skill_body_record("refund-policy", routing_id=routing_id or "")
body = record["body"] if record else None   # record also carries version and content_hash

load_skill() always returns a string and never raises. get_skill_body_record() returns the server’s whole record, or None when the skill isn’t served. routing_id="" means a run whose routing call returned no decision. On Pydantic AI and the raw provider SDKs, recording a load needs a run to attach to, which agent_run() opens and agent_config() opens for you. Outside one, those traces still ship, with no routing_id and no skill names. To put bodies in the prompt instead of using the tool, pass SkillRouter(inject_body=True). CrewAI’s adapter works this way, since it has no tool loop. A body is injected only when the platform ranked the result by this message, so a turn like “thanks!” gets the list alone. Offered priority_skills and an agent’s only skill get their body either way. A body that doesn’t fit the limits above is left out, not cut short.

Python SDK

Skills in your repo

CLI

REST

Install registry skills into your project

Load installed skills with a framework loader

Record what a native loader loaded

Pull a public skill

Sync skills from code to platform

`SkillRouter`: manage skills from code

On-demand bodies: the `load_skill` tool

​Install registry skills into your project

​Load installed skills with a framework loader

​Record what a native loader loaded

​Pull a public skill

​Sync skills from code to platform

​SkillRouter: manage skills from code

​On-demand bodies: the load_skill tool

Install registry skills into your project

Load installed skills with a framework loader

Record what a native loader loaded

Pull a public skill

Sync skills from code to platform

`SkillRouter`: manage skills from code

On-demand bodies: the `load_skill` tool