Skills (SKILL.md)

aide adopts the open agentskills.io standard. A skill is a directory holding a SKILL.md manifest plus optional scripts/, references/, assets/ subdirectories. The same skill packaging is consumed today by Claude Code, OpenAI Codex, Gemini CLI, Cursor, Cline, Windsurf, and others — aide is the governance / audit / safety / cross-domain routing layer layered on top of that ecosystem, not a competing format.

Skill layout

my-skill/                          # dir name MUST equal SKILL.md `name`
├── SKILL.md                       # REQUIRED — YAML frontmatter + Markdown body
├── scripts/                       # optional executable code (any language)
│   └── run.sh
├── references/                    # optional documentation (REFERENCE.md, …)
└── assets/                        # optional templates / schemas / images

Minimal `SKILL.md`

---
name: hello
description: Print a greeting and exit.
---

# hello

Run via `aide skill exec hello`. Add usage notes here.

Frontmatter fields

Field	Required	Constraint
`name`	yes	1-64 chars, `^[a-z0-9]+(-[a-z0-9]+)*$`, MUST equal parent dir name
`description`	yes	1-1024 chars, non-empty
`license`	no	free-form short string
`compatibility`	no	1-500 chars (e.g. `"Requires Python 3.14+"`)
`metadata`	no	flat `map<string, string>`
`allowed-tools`	no	space-separated tool patterns (captured but not enforced yet)

The body is free-form Markdown. The spec recommends keeping it under ~500 lines.

`aide skill` commands

aide skill list   [--root PATH]              # discover skills under search paths
aide skill show   <name> [--with-body]       # print manifest, optionally body
aide skill validate <skill-dir>              # exit 0/1, lists ALL errors
aide skill exec   <name> [--agent A] [-- ARGS...]   # run, stream output
aide skill events [--limit N] [--skill N] [--agent A]   # tail skill-events.jsonl

Search-path resolution

aide skill exec <name> resolves the skill in this order:

~/.aide/skills/<name>/
<agent_dir>/.aide-skills/<name>/ (only when --agent is supplied)
~/.claude/skills/<name>/

First hit wins. aide skill list (without --root) scans both #1 and #3.

Execution semantics (aide's defaults)

The agentskills.io spec deliberately leaves execution undefined. aide's runner picks safe defaults:

Working directory: the skill's own skill_dir, so relative paths in scripts/, references/, assets/ work.
Entry point: first match of scripts/run.sh → scripts/run.py → scripts/main.sh → scripts/main.py. No match = error.
Environment exported:
- AIDE_HOME — $AIDE_HOME override or ~/.aide
- AIDE_SKILL_NAME — the skill name
- AIDE_SKILL_DIR — absolute path to the skill root
- AIDE_RUN_ID — nanos-based unique id
- AIDE_AGENT — the --agent value, if provided
- PATH — inherited
Args: anything after -- is passed verbatim as positional args.
Timeout: 5 minutes default. Override with AIDE_SKILL_TIMEOUT_SECS. On timeout: SIGTERM → 10 s grace → SIGKILL.
Stdout/stderr capture: written to ~/.aide/skill-runs/<skill>/<run_id>.{out,err}, capped at 1 MiB per stream. Overflow is dropped from the file but counted, and the finished event is marked truncated=true.
Exit code: 0 = success; non-zero is logged, not bailed — aide skill exec itself exits with the skill's exit code.

`~/.aide/skill-events.jsonl` schema

Two event kinds, one line per event, append-only.

// started
{
  "ts": "2026-04-18T12:34:56.789Z",
  "kind": "started",
  "run_id": "1750000000000000000",
  "skill": "hello",
  "agent": null,
  "args": []
}
// finished
{
  "ts": "2026-04-18T12:34:57.123Z",
  "kind": "finished",
  "run_id": "1750000000000000000",
  "skill": "hello",
  "agent": null,
  "exit_code": 0,
  "duration_ms": 334,
  "stdout_bytes": 6,
  "stderr_bytes": 0,
  "truncated": false,
  "timed_out": false
}

This is aide's pillar #1 (FS-first audit) for skills. Read it with aide skill events. A future PR will use it for behavior shaping (forbidden tables / penalties), like the existing dispatch event log.

Aidefile integration

[skills]
include = ["code-review", "git-ops"]

Names listed under [skills].include resolve through the same search order documented above. The legacy skills/<name>.md flat-file layout still works for context injection, but new skills should use the SKILL.md directory layout so that aide skill exec (and any other agentskills.io-compatible runner) can run them.

Migrating an existing aide-skill repo

Run the bundled migrator (dry-run by default):

./scripts/migrate-aide-skill-to-skillmd.sh                  # dry-run
./scripts/migrate-aide-skill-to-skillmd.sh --apply          # mutate
./scripts/migrate-aide-skill-to-skillmd.sh --root /path     # custom root

For each <skill>/ containing a top-level run.sh:

Generates <skill>/SKILL.md (name from dir, description from the first # comment in run.sh).
Moves run.sh to scripts/run.sh and marks it executable.
Skips dirs that already contain a SKILL.md, or that don't have a run.sh (not recognized as a legacy skill).

After migration, validate one with aide skill validate <skill-dir> and test with aide skill exec <name>.

aide.sh