Native Skill Loaders

​

What DecimalAI records

1. the identity stamp in the delivered copy (metadata.decimalai-*), when the delivered body’s hash matches it;
2. otherwise the lock, by the delivered body’s hash;
3. otherwise any version this process has already seen with that hash.

• A skill loaded twice in one run is one activation.
• The skills the loader listed for the model are recorded as offered.
• The router steps aside. An agent whose own loader serves its skills gets no DecimalAI skill list and no DecimalAI load_skill tool; the SDK logs this once at INFO, or as a warning on an OpenAI Agents, Pydantic AI or Google ADK agent you also gave agent_config()’s skills. If both still reach the model, because the loader was attached where the adapter could not see it, a WARNING says so once.

​

Setup at a glance

​

decimalai.skills_dir()

import decimalai
from pathlib import Path

decimalai.skills_dir()                         # /home/me/support-bot/.agents/skills
decimalai.skills_dir(relative_to=Path.cwd())   # .agents/skills

• It finds the project from the working directory, as every decimalai skills command does, so it works from any subdirectory of the project. skills_dir(directory=...) starts the search somewhere else.
• It returns the absolute, symlink-resolved path. With relative_to=, it returns the path relative to that directory instead, for the two loaders that need one (OpenAI Agents and the Pydantic AI harness), and raises UsageError when the root is not under it.
• It raises SkillsNotInstalledError when the project has no lock or no root yet (run decimalai skills install), LegacyLockError for a lock from SDK 0.14 or older (run decimalai skills migrate), and IllegalEntryError when .agents or .agents/skills is a symlink.

​

The eight loaders

​

Claude Agent SDK and Claude Code

import asyncio

import decimalai
from claude_agent_sdk import ClaudeAgentOptions, query
from decimalai.claude_agent_sdk import skills_plugin

decimalai.init(claude_agent_sdk=True)

options = ClaudeAgentOptions(
    plugins=[skills_plugin()],   # the project's .agents, as an absolute path
    skills="all",                # offer every skill it finds, through the Skill tool
)


async def main():
    async for message in query(prompt="A customer wants a refund for $100 after 45 days.",
                               options=options):
        print(message)


asyncio.run(main())

claude --plugin-dir "$(git rev-parse --show-toplevel)/.agents"

• The plugin path must be absolute: a relative --plugin-dir .agents started from a subdirectory loads nothing, with exit status 0 and nothing on stderr. skills_plugin() returns an absolute one.
• Skills are listed as decimalai-skills:<install-name>. The plugin is not named decimalai, the marketplace plugin’s name, so the two load side by side.
• It reads name, description and the body, and acts on allowed-tools and disable-model-invocation. It pre-approves the tools a skill lists: a skill your organization authored can run its own bundled scripts with no prompt (Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/… *)), any other command needs permission, and a skill your organization did not author lists only Read, Grep and Glob, so its scripts always need permission. A user-only skill (disable-model-invocation: true) is listed but never offered to the model.
• The frontmatter never reaches your process, so the version comes from the lock, by the hash of the body the CLI delivered.

​

Google ADK

import decimalai
import decimalai.adk
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor
from google.adk.tools.skill_toolset import SkillToolset

decimalai.init(agent_name="support")

agent = LlmAgent(
    name="support",
    model="gemini-3.5-flash",
    instruction="Answer refund questions.",
    tools=[SkillToolset(skills=decimalai.adk.skills(), code_executor=UnsafeLocalCodeExecutor())],
)
app = App(name="support", root_agent=agent, plugins=[decimalai.adk.DecimalAIPlugin()])

• The plugin in the App traces each invocation and records each load (SDK 0.20+; through 0.19, decimalai.init(adk=True) added it to every runner).
• decimalai.adk.skills() loads each folder on its own and skips a bad one with a WARNING that names it. ADK’s own load_skills_from_dir raises on one bad folder and loads nothing at all.
• It reads each folder’s frontmatter, metadata included, and the body. The model first lists the skills, then loads one.
• ADK parses the skills when skills() runs, so an agent built before decimalai skills update keeps serving the old version until you build it again. The activation says which version that was.
• Without a code_executor, ADK offers no run_skill_script. UnsafeLocalCodeExecutor runs scripts on your machine with no sandbox; use it only for skills you trust.

​

CrewAI

import decimalai
import decimalai.crewai
from crewai import Agent, Crew, Task

decimalai.init(crewai=True)

agent = Agent(role="Support", goal="Answer refund questions", backstory="A support agent.",
              llm=llm, skills=decimalai.crewai.skills(), tools=decimalai.crewai.skill_tools())
task = Task(description="Refund for $100 after 45 days?", expected_output="an answer",
            agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()

• CrewAI’s own skill tool is load_skill, which delivers the body. CrewAI has no resource reader and no script runner of its own, so skill_tools() adds two: load_skill_resource reads a skill’s references/, assets/ or scripts/ file, and run_skill_script runs one of its scripts/ (Python with your interpreter, shell scripts with bash, no shell expansion, with a timeout). Both accept only installed skills and paths inside them. run_skill_script does not enforce a skill’s allowed-tools; skill_tools(scripts=False) leaves it out.
• It has the strictest metadata parser of the eight: every value must be a string. A bad folder is skipped with a SkillLoadFailedEvent and a log line, not an exception.
• CrewAI reads a skill’s body from disk on every load, so it serves the new version right after decimalai skills update.

​

OpenAI Agents (SandboxAgent)

import asyncio

import decimalai
from agents import RunConfig, Runner
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient
from decimalai.openai_agents import sandbox_skills

decimalai.init(openai_agents=True)

agent = SandboxAgent(
    name="support",
    instructions="Answer refund questions.",
    capabilities=[Shell(), sandbox_skills()],   # run from the project root
    default_manifest=Manifest(),
)
config = RunConfig(sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()))
asyncio.run(Runner.run(agent, "Refund for $100 after 45 days?", run_config=config))

• sandbox_skills() is the sandbox’s Skills(lazy_from=LocalDirLazySkillSource(...)) over skills_dir(relative_to=Path.cwd()). Run from the project root: a source outside the working directory, reached through a symlink or through the macOS /tmp alias, lists zero skills.
• It adds two guards the plain capability lacks. The sandbox skips a symlinked skill folder without a word, so sandbox_skills() warns when it would list nothing. And the sandbox’s load_skill aborts the whole run on a name it cannot find; the helper’s answers the model with the names it can load instead.
• Keep default_manifest=Manifest(); without it the skills vanish.
• When the model loads a skill, the sandbox copies its folder to .agents/<install-name> and drops the exec bit on the way, so run scripts through their interpreter (python3 scripts/compute_refund.py), never as ./scripts/.... DecimalAI identifies the load from that copy, the bytes the model reads.
• On macOS, commands run under sandbox-exec.

​

Deep Agents

import decimalai
import decimalai.deepagents
from deepagents import create_deep_agent

decimalai.init(langchain=True)

agent = create_deep_agent(model=model, **decimalai.deepagents.skills())
agent.invoke({"messages": [{"role": "user", "content": "Refund for $100 after 45 days?"}]})

• decimalai.deepagents.skills() returns the two arguments Deep Agents needs together: skills=[<your skills folder>] and a backend that can see it. The default backend is a FilesystemBackend(root_dir=<project>, virtual_mode=False), which reads files but has no shell, so a skill’s scripts cannot run. To run them, pass one: decimalai.deepagents.skills(backend=LocalShellBackend(root_dir=project, virtual_mode=False)). LocalShellBackend runs commands on your machine.
• virtual_mode=False. With True, the prompt advertises virtual /skills/... paths that execute cannot open.
• The skills middleware lists each skill in the system prompt with the path of its SKILL.md; the model reads it with read_file. A read that stops short of the whole file delivers part of the body, and the activation then carries no version, because that body is no version.
• A namespaced or uppercase name: is listed under that name, with a warning on the deepagents logger, rather than under its folder’s.

​

Microsoft Agent Framework

import asyncio

import decimalai
from agent_framework import Agent
from agent_framework.observability import enable_sensitive_telemetry
from decimalai.agent_framework import skills

decimalai.init(otel=True, agent_name="support")
enable_sensitive_telemetry()   # tool arguments and results on the trace

agent = Agent(client=client, instructions="Answer refund questions.",
              context_providers=[skills()])
asyncio.run(agent.run("Refund for $100 after 45 days?"))

• skills() is SkillsProvider.from_paths(...) over your skills folder, with three things added on the same object: the observer, a script runner (MAF ships none; without one a script answers that it requires a runner), and an approval rule. MAF makes every skill tool wait for approval by default; the helper lets skill loads and file reads run unasked, and keeps scripts waiting for approval unless you pass skills(auto_approve_scripts=True).
• It caches skills by default, so a long-running provider keeps serving the old version after decimalai skills update, and the activation says so. Restart the process to serve the new one.
• Without enable_sensitive_telemetry(), the activation is still recorded, but the trace does not show what each tool call read or returned.
• A bad folder is skipped, with an ERROR line on the agent_framework logger.

​

Pydantic AI harness

import decimalai
import decimalai.pydantic_ai_harness
from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai_harness import FileSystem, Shell

decimalai.init(otel=True, agent_name="support")
Agent.instrument_all()               # Pydantic AI's own spans: one trace per agent run

project = decimalai.skills_dir().parents[1]
agent = Agent(model, capabilities=[
    LocalWorkspace(project),
    decimalai.pydantic_ai_harness.skills(project),
    FileSystem(),
    Shell(),
])
agent.run_sync("Refund for $100 after 45 days?")

• decimalai.pydantic_ai_harness.skills(project) is the harness’s Skills over your skills folder, relative to the workspace as the harness requires: a skills folder outside it still lists, but read_file refuses its files.
• No DecimalAI adapter is involved (SDK 0.19+). Don’t also give this agent decimalai.pydantic_ai.agent_config()’s capability: the harness’s catalog already serves its skills, so the capability adds neither DecimalAI’s skill list nor load_skill, and one warning says so.
• The harness keeps a skill’s name, description and body; metadata is parsed and dropped, so the version comes from the lock, by the hash of the delivered body.
• It keeps a user-only skill (disable-model-invocation: true) out of the model’s catalog. It does not enforce allowed-tools, and says so on every run with a UserWarning: Ignoring unsupported Agent Skill behavioral frontmatter fields.
• A bad folder goes into the catalog’s skipped list with a UserWarning, never an exception.

​

Strands Agents

import decimalai
from decimalai.strands import skills
from strands import Agent
from strands.vended_tools import file_editor, shell

decimalai.init(otel=True, agent_name="support")

agent = Agent(
    model=model,
    system_prompt="Answer refund questions.",
    tools=[file_editor, shell],
    plugins=[skills()],
)
agent("Refund for $100 after 45 days?")

• skills() is AgentSkills(skills=<absolute skills folder>, strict=True) with the observer attached, still the one plugin Strands knows as agent_skills. The skills tool answers with the body and a Location: line; the model then reads files with file_editor and runs scripts with shell. file_editor refuses relative paths, which is why the root is absolute.
• Strands puts tool arguments and results in span events, which the exporter does not read. Set OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,gen_ai_span_attributes_only before the first agent is built to have them on the trace; the activation is recorded either way.
• Strands loads an agent’s skills once, so the same agent keeps serving the old version after decimalai skills update.
• strict=True on the plugin does not raise: it logs “failed to load skill” and skips that folder. Skill.from_file(path, strict=True) is the call that raises.
• Always pass model=. Strands’ default model is Amazon Bedrock.

​

Known upstream gaps

​

What a loader does with a bad folder

• Google ADK raises for a name or a list-typed field that breaks the format, and then loads nothing at all (decimalai.adk.skills() skips that folder instead).
• Microsoft Agent Framework, CrewAI, Strands and the Pydantic AI harness skip the folder and log a warning, which is easy to miss.
• OpenAI Agents and Deep Agents rename: a namespaced or uppercase name: is listed under that name instead of the folder’s. OpenAI Agents also skips a symlinked skill folder without a word.
• Claude Code lists a skill whose name: differs from its folder under the other name.

​

How the SDK checks this

• the loader lists exactly the installed skills, under their install names;
• its own warning channel stays quiet;
• the model receives the skill’s own body, and its hash equals the stamp;
• a bundled file reads back byte for byte, and a bundled script runs and prints what it should, through the loader’s own tools;
• the identity stamp reads back and equals the lock;
• user-only skills are hidden (Claude Code, the Pydantic AI harness), or the upstream gap above holds;
• the script keeps its exec bit in the copy the loader runs.

• the listing;
• one activation carrying the installed version’s exact ids;
• the resource read and the script run;
• after the update, the version whose body the model actually received.

​

Without a helper

import decimalai

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