#Skills

Skills are reusable instructions that the harness can discover and rank. File-backed skill directories, inline skills, explicit registries, and search_skills share the same discovery path. A3S Code no longer ships default embedded skills; builtinSkills: true is accepted by the SDKs as a compatibility no-op.

#Compatibility Flag

const session = agent.session('/repo', {
  builtinSkills: true,
});

This flag does not add default skills. Put reusable behavior in project skill files, inline skills, or agent definitions.

#Skill Files

Store Markdown files with frontmatter in a skill directory:

---
name: release-review
description: Review release blockers and verification evidence
allowed-tools: 'read(*), search(*), bash(cargo test*)'
---

Check package metadata, changelog, release scripts, and CI status.
Return blockers first.

const session = agent.session('/repo', {
  skillDirs: ['/repo/.a3s/skills'],
});

Use skillDirs for skill files. Use agentDirs for worker/subagent definitions.

Skill directories are loaded only when configured: through skill_dirs in the agent ACL (shared by every session of that agent) or through session skillDirs / skill_dirs / SkillDirs. There is no implicit .a3s/skills scan. Each directory is walked recursively in sorted order; a skill is either a *.md file or a SKILL.md inside a subdirectory. Symlinks that resolve outside the directory are ignored, and a missing directory loads zero skills. When two files declare the same name, the later one replaces the earlier one and a warning is logged.

#Inline Skills

const session = agent.session('/repo', {
  inlineSkills: [
    {
      name: 'strict-release-review',
      kind: 'instruction',
      content: 'Always separate blockers from nice-to-have improvements.',
    },
  ],
});

#Skill Tool

search_skills finds relevant skills (limit is 1 to 20, default 5), and the model runs one with the Skill tool (skill_name, optional prompt):

await session.tool('search_skills', {
  query: 'release blockers',
  limit: 5,
});

Markdown skill files with allowed-tools frontmatter and inline skills are both discoverable. Skill administration is an SDK or filesystem concern rather than a model-visible management tool. On a live session, hosts add and remove inline skills with addSkill(skill) / removeSkill(name) / skillNames() (Python add_skill(name, content, kind) / remove_skill(name) / skill_names(), Go AddSkill / RemoveSkill / SkillNames). removeSkill only removes a skill installed through addSkill.

When a skill is invoked through the Skill tool, allowed-tools is fail-secure: omitted frontmatter grants no tools to that skill invocation. Declare the smallest needed allow-list. Ordinary session tool calls are not restricted by active skills unless enforceActiveSkillToolRestrictions / enforce_active_skill_tool_restrictions is explicitly enabled.