#skills/ Skill Directory

skills/ stores reusable skills. Skills express stable process, checklists, domain terms, and tool-use guidance. A skill is not a worker agent and does not start an independent session.

The conventional location is:

repo/.a3s/skills/          # workspace-level skills

Skill directories are never scanned implicitly. Load them through ACL skill_dirs (shared by every session of the agent) or session skillDirs. Worker definitions use agentDirs; do not put skill directories in agentDirs.

#Skill File

---
name: release-readiness
description: Check whether a repository is ready to release
allowed-tools: read(*), search(*), bash(pnpm test*), bash(cargo test*)
---

Always inspect:

- package or crate version changes
- migration compatibility
- release notes
- required verification commands

Return blockers first, then risks, then follow-up work.

Frontmatter helps discovery and filtering. The body describes how to execute. Keep allowed-tools minimal. When the skill is invoked through the Skill tool, omitted allowed-tools grants no tools, so the invocation remains fail-secure. Skills guide the model; they should not widen permissions.

#When To Use skills/

Use skills for repeated review checklists, product or protocol process, release and migration workflows, recommended tool order, and shared background for several worker agents.

Do not use skills for independent roles that should be invoked by task; put those in .a3s/agents/. Do not use skills to declare external capabilities; register MCP servers or SDK tools instead. Recurring work is a host scheduler outside Core.

#Loading

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

skill_dirs = ["./.a3s/skills"]

Each directory is walked recursively. A skill is either a *.md file or a SKILL.md inside a subdirectory, so both layouts work:

.a3s/skills/release-readiness.md
.a3s/skills/migration/SKILL.md

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.

The model can use search_skills to find relevant skills. File skills and inline skills share discovery semantics. As directories grow, keep name and description searchable and unambiguous.

#Maintenance

• Keep skill files short and stable.
• Use minimal runnable examples, not long logs.
• Put repository-wide skills in .a3s/skills/ and document their boundary in AGENTS.md.