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 rely on built-in discovery with builtinSkills / builtin_skills. Either way the 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(), {
  builtinSkills: true,
  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);

// Option B: invoke a skill directly as a callable tool.
// Canonical args: { skill_name, prompt? }.
const result = await session.tool('Skill', {
  skill_name: 'code-review',
  prompt: 'Review this patch for correctness and regressions.',
});
console.log(result);

await session.close();

from a3s_code import Agent, SessionOptions

agent = Agent.create(open('agent.acl').read())
opts = SessionOptions()
opts.builtin_skills = True
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)

# Option B: invoke a skill directly as a callable tool.
# Canonical args: { skill_name, prompt? }.
result = session.tool('Skill', {
    'skill_name': 'code-review',
    'prompt': 'Review this patch for correctness and regressions.',
})
print(result)

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.

Skill Tool

Skill Tool

On this page