Core concepts

Skills

Skills teach the default agent orchestrator how to work in your local workspace: list files, run shell commands, read/write/patch files, and use bundled scripts or templates shipped with the skill.

How it works

  1. RAYS scans skill directories and loads every folder that contains SKILL.md.
  2. The orchestrator selects required skill names for each prompt.
  3. The planner emits spawn steps with a spawn_reason per skill.
  4. Each skill runs as a dynamic sub-agent until status: completed.

Where skills live

  • <project>/skills/<name>/ — this repo only.
  • ~/.rays/skills/<name>/ — all projects on this machine.

Layout

skills/
└── my-skill/
    ├── SKILL.md         # required — instructions + frontmatter
    ├── scripts/         # optional — shell helpers
    ├── templates/       # optional — doc templates
    └── LICENSE.txt      # optional

SKILL.md frontmatter

---
name: my-skill
description: One line explaining what this skill does.
---

# My Skill

Instructions, constraints, examples.