Skills

Skills are reusable instruction packs loaded on demand by the agent runtime. Only the skill name and description are placed in the base prompt. When a task matches a skill, the agent calls load_skill(skill_name) and receives the full SKILL.md body.

Skills live under the directory configured by SKILLS_DIR (default: skills/). The Docker deployment mounts that directory at /app/skills.

Directory Layout

Each skill is a directory containing SKILL.md:

skills/
  systematic-debugging/
    SKILL.md
  test-driven-development/
    SKILL.md
  writing-plans/
    SKILL.md

The loader ignores directories without a SKILL.md.

Frontmatter

The current parser supports these frontmatter fields:

Field	Required	Description
`name`	No	Skill name. Defaults to the directory name.
`description`	No, but recommended	One-line description shown in the skill index.
`version`	No	Optional version string.
`context`	No	Set to `fork` to execute the skill through a subagent.
`agent`	No	Subagent type to use when `context: fork`.
`allowed-tools`	No	List or comma-separated string of tools allowed for the skill.
`disable-model-invocation`	No	Boolean flag for skills that should not call a model directly.
`user-invocable`	No	Boolean flag controlling whether users can invoke it directly.

Example:

---
name: systematic-debugging
description: Debug failures by reproducing, isolating, hypothesizing, and verifying.
version: "1.0"
allowed-tools:
  - bash
  - read_file
  - grep
---

# Systematic Debugging

Use this before proposing fixes for bugs, test failures, or unexpected behavior.

On-Demand Loading

At startup, SkillLoader reads all skill frontmatter and builds an index:

- systematic-debugging: Debug failures by reproducing, isolating...
- test-driven-development: Write a failing test before implementation...

The full body is returned only when the agent calls load_skill. This keeps the base prompt small while still allowing detailed procedures.

If a skill declares context: fork, load_skill dispatches the instructions to the configured subagent type and returns the subagent result instead of returning the raw body.

Creating a Skill

Add a directory under skills/.
Add SKILL.md with frontmatter and clear workflow instructions.
Restart agent-runtime so the loader rebuilds the index.

mkdir -p skills/release-notes

---
name: release-notes
description: Produce concise release notes from git history and issue context.
allowed-tools: [bash, grep, read_file]
---

# Release Notes

1. Inspect commits since the requested base.
2. Group changes by user-facing area.
3. Call out migrations, risks, and verification.

Descriptions should be specific. A vague description such as "general helper" does not give the model enough signal to choose the skill.

Built-In Skill Families

The repository includes skills for planning, plan execution, subagent-driven development, debugging, test-driven development, code review, verification before completion, memory management, document QA, wiki curation, and UI work.

Exact availability depends on the mounted skills/ directory and any enabled Codex plugins.

Operational Notes

Skill changes require an agent-runtime restart; hot reload is not currently supported.
Skills are instructions, not permission grants. Tool execution is still governed by runtime policy and the tools registered for the current agent.
Subagents are configured separately in deploy/config/subagents/*.md. A skill can request a subagent through frontmatter, but the target type must exist.

Directory Layout​

Frontmatter​

On-Demand Loading​

Creating a Skill​

Built-In Skill Families​

Operational Notes​