Skald-Circle/docs/skills.md

Skills System

Skills are reusable capability packages that extend what the agent can do without modifying the core source code.

Structure

skills/
  index.md              ← registry of all available skills
  <skill-name>/
    SKILL.md            ← documentation: purpose, usage, script API
    <script>.py         ← one or more Python scripts

How the agent uses skills

1. skills/index.md is injected into the agent's system prompt automatically as a <skills_index> block, so every agent discovers available skills without reading it explicitly. Controlled by the inject_skills meta.json flag (default true; see agents.md) — set it to false for background agents that don't need skills. The block is skipped silently when no skills are installed.
2. It reads the relevant SKILL.md to understand how to invoke the script.
3. It runs the script via a shell command (e.g. python3 skills/pdf/scripts/...).
4. It uses the script's stdout as the result.

Path note: the injected <skills_index> shows the index path relative to the session's working directory when it lives under it, absolute otherwise. In a project chat (working directory = project root) it shows as absolute, since skills live under Skald's own cwd. Invoking a skill from a project session still needs care — execute_cmd runs with the project working directory, so scripts referenced cwd-relative (python3 skills/...) won't resolve; use an absolute path or cd to Skald's root.

Adding a skill

1. Create skills/<name>/SKILL.md — document purpose, required inputs, expected output, and example invocation.
2. Add the Python script(s) alongside it.
3. Register the skill in skills/index.md by adding a row to the table.

No code changes or restarts are required — the agent discovers skills at runtime by reading the index.

Conventions

• Scripts must be runnable with python3 and accept arguments from the command line.
• Scripts should write their result to stdout and errors to stderr, exiting with code 0 on success.
• Keep each script focused on one task. Compose multiple skills via the agent, not within a single script.