Skills

A skill is a focused procedure a harness can discover or load when the task calls for it. Keep long or situational guidance in a skill instead of the always-on instruction file.

Author a file-based skill

Create a directory under skills/ with a SKILL.md:

---
name: diff-review
description: Review a unified diff for correctness and regressions.
allowed-tools: [Read, Grep, Bash]
risk-tier: high
---

# Diff review

Read the full diff, trace affected callers, and report only actionable findings.

The directory name supplies the default skill name. name, description, allowed-tools, and onUnsupported are normalized into portable fields. Other frontmatter passes through unchanged.

Keep supporting files beside the skill

Every sibling file is collected automatically:

skills/
└── diff-review/
    ├── SKILL.md
    ├── rubric.md
    └── scripts/
        └── changed-files.mjs

Adapters that support skill resources place those files beside the emitted skill. Other targets report an explicit translation or drop.

Define a skill in TypeScript

Use defineSkill when instructions are generated or shared with another module:

import { defineSkill, file } from "soubi";

export default defineSkill({
  description: "Prepare and verify a release.",
  instructions: file("./release.md"),
  assets: ["./release-checklist.md"],
});

The filename supplies the name when name is omitted. Asset and file() paths resolve relative to the module.

Control incompatible targets

Set onUnsupported to "drop", "degrade", or "fail" when the default Fallback Tier is not appropriate:

export default defineSkill({
  name: "release",
  instructions: "Prepare and verify a release.",
  onUnsupported: "fail",
});

Run soubi check to see the exact result for every selected harness.