Toggle the built-in skills and load your own skills and subagents from project directories.

Skills & Custom Agents

A3S Code ships with a set of built-in skills, and you can extend a session with your own skills and subagents loaded from directories on disk. Use the builtinSkills option to turn the bundled skills on or off, and agentDirs (or registerAgentDir) to point the session at folders that contain your custom *.skill.md and agent definitions. This is the right approach when you want project-specific behavior without changing the runtime.

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

const agent = await Agent.create('agent.acl');

// Built-in skills ON, plus custom skills/agents from project dirs.
const session = agent.session('/path/to/project', {
  builtinSkills: true,
  agentDirs: ['./.a3s/skills', './.a3s/agents'],
});

// You can also register more directories after the session exists.
session.registerAgentDir('./team/shared-agents');

// Inspect what the session loaded.
console.log('Tools:', session.toolNames());
console.log('Commands:', session.listCommands());

// The agent now has access to both built-in and custom skills.
const result = await session.run(
  'Use the project conventions skill to scaffold a new module.',
);
console.log(result);

await session.close();

from a3s_code import Agent, SessionOptions

agent = Agent.create(open('agent.acl').read())

# Built-in skills ON, plus custom skills/agents from project dirs.
opts = SessionOptions()
opts.builtin_skills = True
opts.agent_dirs = ['./.a3s/skills', './.a3s/agents']

session = agent.session('/path/to/project', opts)

# You can also register more directories after the session exists.
session.register_agent_dir('./team/shared-agents')

# Inspect what the session loaded.
print('Tools:', session.tool_names())
print('Commands:', session.list_commands())

# The agent now has access to both built-in and custom skills.
result = session.run(
    'Use the project conventions skill to scaffold a new module.',
)
print(result)

session.close()

Disabling the built-in skills

Set builtinSkills / builtin_skills to false when you want a lean session that only uses the skills you explicitly provide. The bundled skills are no longer registered, so toolNames() / tool_names() reflects only your custom set plus the core tools.

const session = agent.session('/path/to/project', {
  builtinSkills: false,
  agentDirs: ['./.a3s/skills'],
});

opts = SessionOptions()
opts.builtin_skills = False
opts.agent_dirs = ['./.a3s/skills']
session = agent.session('/path/to/project', opts)

Custom subagents loaded from agentDirs can be referenced by name in session.parallel(...) and session.pipeline(...) alongside the built-in registry agents (explore, plan, general, verification, review).

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

Skills & Custom Agents

Skills & Custom Agents

Disabling the built-in skills

On this page