Skills & Custom Agents
Load project skills and custom subagents from filesystem conventions.
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 skillDirs for
Markdown skills and agentDirs for worker/subagent definitions. registerAgentDir
can add more agent definition directories after the session exists; skill
directories are loaded when the session is created.
import { Agent } from '@a3s-lab/code';
const agent = await Agent.create('agent.acl');
// Built-in skills are available by default. Add project skills and agents.
const session = agent.session('/path/to/project', {
skillDirs: ['./.a3s/skills'],
agentDirs: ['./.a3s/agents'],
});
// You can register more agent definition 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.text);
session.close();from a3s_code import Agent, SessionOptions
agent = Agent.create("agent.acl")
# Built-in skills are available by default. Add project skills and agents.
opts = SessionOptions()
opts.skill_dirs = ['./.a3s/skills']
opts.agent_dirs = ['./.a3s/agents']
session = agent.session('/path/to/project', opts)
# You can register more agent definition 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.text)
session.close()Built-in skill behavior
In the current Node and Python SDKs, built-in skills are part of the default
effective skill registry. builtinSkills: true / builtin_skills = True is
accepted for compatibility, but false does not remove the default built-ins.
If you need a deliberately lean registry, use the Rust core API with an explicit
custom SkillRegistry and then add only the skills you want.
For day-to-day projects, treat built-ins as the baseline and add project skills
with skillDirs / skill_dirs.
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.