tai/skills.md

# skills.md

The skill system and the bundled default skills: discovery contract,
frontmatter subset, the six shipped skills with their upstream provenance
and tai adaptations, install semantics, and maintenance.

## The system

Skills are directories containing a `SKILL.md` file with `name` plus
`description` frontmatter, optionally with `scripts/`, `references/`, and
`assets/` alongside (the open Agent Skills layout). Discovery
(`discover_skills`) scans four roots and the most tai-specific one wins a
name collision: `~/.claude/skills` and `<project>/.claude/skills` /
`<project>/.agents/skills` first (external, read-only interop), then
`~/.tai/skills` and `<project>/.tai/skills` (managed).

`load_skill` returns the body plus a provenance note plus the absolute
paths of the top-level entries under `scripts/`, `references/`, and
`assets/` (`skill_extra_files`, not recursive: a nested directory shows up
as its own path and the agent descends from there). Descriptions ride the
system-prompt catalog truncated to 300 characters; bodies load on demand.

Frontmatter is a deliberate subset, not YAML (`parse_skill_front`): one
`key: value` per line, double-quoted values have their outer quotes
stripped, unknown keys are ignored, and only bare `>` (fold with spaces)
and `|` (join with newlines) continue a value onto indented lines.
Chomping variants (`>-`, `|-`, `>+`, `|+`) do NOT parse: a `>-`
description reads back as the literal string `">-"` and the folded lines
are dropped. Shipped skills must use single-line descriptions.

Missing skills with a `SKILL_BLUEPRINTS` entry are researched and built on
first `load_skill` (`bot-creator`, `api-client`, `web-researcher`,
`pdf-forms`, `data-wrangler`, `home-sysadmin`); anything else is an
"unknown skill" error listing what exists.

## Bundled skills

Six skills ship inside `tai.py` itself (`BUNDLED_SKILLS`, 21 files) so a
bare copy installs them anywhere. Upstream provenance per skill lives in
`BUNDLED_SKILL_UPSTREAM` and is copied into each installed sidecar.

| Skill | Files | Upstream | Status |
|---|---|---|---|
| `deep-research` | 6 (`SKILL.md`, 4 `references/`, `UPSTREAM.md`) | author's Muse user skill (itself from `wanqingying/debian-railway`, see `UPSTREAM.md`) | adapted |
| `seriousdevelopment` | 10 (`SKILL.md`, `CHANGELOG.md`, 8 `assets/templates/`) | author's Muse user skill v1.7.1 | verbatim |
| `git` | 2 (`SKILL.md`, `scripts/workspace-recovery.sh`) | Muse's bundled set | adapted |
| `plan` | 1 (`SKILL.md`) | Muse's bundled set | adapted |
| `requirements-clarification` | 1 (`SKILL.md`) | Muse's bundled set | adapted |
| `taste` | 1 (`SKILL.md`) | Muse's bundled set | one word |

`seriousdevelopment` is byte-identical to upstream: it carries no host
references and no em dashes. Everything else changed only where the host
leaks through; the method prose is untouched.

## Adaptation rules

Each rule below was applied everywhere its token appeared, and
`BundledSkillsTests.test_embedded_content_guards` fails if any of them
regresses:

| Upstream token | Tai equivalent | Why |
|---|---|---|
| `read_skill` | `load_skill` | tai's loader is named `load_skill` |
| `request_user_input` / `request_user_input_async` (+ `auto_resolution_ms`) | `ask_user` (question plus options, blocks; unavailable to workers and autonomous mode, decide and state the assumption there) | tai's only question tool blocks and has no async form |
| subagent / `Task` / `explore` workers, wait-call mechanics | `fork` (task plus timeout up to one hour) / `poll` (up to two minutes per call, loop until done); workers get 12 steps, no questions, nesting depth 2, 8 live max | tai's orchestration primitives and their real caps |
| `curl` recipes, `curl` commands | `web_fetch` GET with the same URL and headers | tai forbids curl and wget via shell; every recipe is a plain GET so nothing is lost (`auth_secret` covers the token case) |
| `webfetch` / `websearch` | `web_fetch` / `web_search` | tai's tool names |
| `/plan`, `/skill plan` | prose request or `load_skill` | tai has no slash-command skill routes |
| `>-` folded description | single-line description | the frontmatter subset (above) |
| em dash (U+2014) | hyphen | project prose rule, no exceptions |

Two judgment calls beyond mechanical mapping:

- `git` got an "Authorization in tai" paragraph: its never-commit rule
  would otherwise veto the user's standing auto-commit rule, so history
  writes follow the session's approval setting while the recovery
  snapshot, lock discipline, and named-files rules still apply as
  written. The `<git-skill-dir>` placeholder became `<recovery>`, bound
  to the absolute script path from the bundled-files list.
- `deep-research` briefs still hand workers literal URLs even though tai
  workers could read the skill directory: inline URLs keep briefs
  self-contained under the 12-step budget.

## Install target

`skills` is the twelfth `INSTALL_TARGETS` entry, implemented by
`op_skills` on top of `write_bundled_skill` / `remove_bundled_skill`,
included in bare `./tai.py --install` and refreshable via the `install`
tool or `/install`. All six land in home scope (`~/.tai/skills`); project scope
never receives bundled skills. After any non-status action through the
tool, the live session re-runs discovery so the skills are usable without
a restart.

| Action | Semantics |
|---|---|
| `install` | writes missing skills only; a present `SKILL.md` means "already present", never an overwrite |
| `upgrade` | rewrites files that are missing or already equal; differing files are kept untouched and named loudly (`kept modified`) |
| `reinstall` | force-rewrites every tracked file, including user edits; user-added extra files still survive |
| `uninstall` | removes tracked files that still match (plus orphan sidecars); user-modified and user-added files stay, named loudly, with their sidecar |
| `status` | one line: `skills: P/6 bundled present`, plus `missing:` and `modified:` lists when non-empty |

The `.installs/<name>.json` sidecar records `source: tai-bundled`,
`mode: bundled`, `scope: home`, the `upstream` locator, the
`bundled_version` that wrote it, per-file sha8 `files`, and
`installed_at`. `load_skill` renders this as `[installed bundled, home
scope, from tai-bundled]`. The sidecar is rewritten only when a write
leaves zero kept files, so user edits are never re-baselined as
pristine behind their back.

## Maintenance

The embedded copies ARE the source: fix typos and drift directly in
`BUNDLED_SKILLS`, never by re-copying upstream over them (re-copying
would silently drop the adaptations above). To pull a new upstream
version of one skill: diff upstream against the embedded copy, re-apply
the adaptation rules to the new text, re-embed, and confirm the guard
test plus a fresh install round-trip. Raw strings keep backslashes
byte-exact, so no embedded file may contain a triple-double-quote or
end in a backslash; the guard test enforces the quote half.