#Skill Tool

Skills surface to the model as two core tools: search_skills (find a skill by intent) and Skill (invoke a skill by name). A tool-kind skill runs its handler; an instruction-kind skill returns its body for the model to apply. You can let the model call these tools during a run, or invoke a skill directly from the SDK with session.tool('Skill', ...).

Register a skill directory (a folder of SKILL.md files) via skillDirs / skill_dirs, or pass inline skills through session options. A3S Code no longer ships default embedded skills, so builtinSkills / builtin_skills is only a compatibility flag. Registered skills become visible through Skill and search_skills.

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.acl');
const session = agent.session(process.cwd(), {
  skillDirs: ['./skills'], // a folder of SKILL.md files
});

// Skill and search_skills are core tools — confirm they're on the surface.
console.log(session.toolNames());

// Option A: let the model search for and apply a skill during a run.
const run = await session.run(
  'Search available skills, then apply the most relevant one.',
);
console.log(run.text);

// Option B: invoke a skill directly as a callable tool.
// Canonical args: { skill_name, prompt? }.
const result = await session.tool('Skill', {
  skill_name: 'release-review',
  prompt: 'Review this release patch for blockers and verification gaps.',
});
if (result.exitCode !== 0) {
  throw new Error(result.output);
}
console.log(result.output);

session.close();

from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.acl")
opts = SessionOptions()
opts.skill_dirs = ['./skills']  # a folder of SKILL.md files
session = agent.session('.', opts)

# Skill and search_skills are core tools — confirm they're on the surface.
print(session.tool_names())

# Option A: let the model search for and apply a skill during a run.
run = session.run('Search available skills, then apply the most relevant one.')
print(run.text)

# Option B: invoke a skill directly as a callable tool.
# Canonical args: { skill_name, prompt? }.
result = session.tool('Skill', {
    'skill_name': 'release-review',
    'prompt': 'Review this release patch for blockers and verification gaps.',
})
if result.exit_code != 0:
    raise RuntimeError(result.output)
print(result.output)

session.close()

A SKILL.md declares its kind in frontmatter (tool, instruction, or agent). For a tool-kind skill, the Skill tool runs the skill's handler and returns its output; for an instruction-kind skill, it returns the body for the model to apply. Skill administration is handled by SDK registration, skill directories, or project files — not by a model-visible management tool.

A runnable version ships at crates/code/sdk/node/examples/skills/test_custom_skills_agents.ts.