# Skills Registry — how a rule or command reaches a dev's machine

`tawa skills sync` pulls Claude Code rules and slash-commands onto every dev's
machine. This is where that content comes from, and how to change it.

## The pipeline

```
tawa-docs (git, PR-reviewed)          ← SOURCE OF TRUTH
  conventions/*.md  →  rules/tawa-*.md
  commands/*.md     →  commands/tawa-*.md
        │
        │  scripts/seed-skills.ts   (in iec-builder, run manually)
        ▼
iec-builder skills registry (MongoDB)
        │
        │  tawa skills sync
        ▼
~/.claude/rules/  and  ~/.claude/commands/   on every dev's machine
```

> **The database is not the source of truth.** It is a distribution cache. Editing
> a skill directly in the registry works right up until the next seed run
> overwrites it.

## Two kinds of skill

| Kind | Source | Lands at | Becomes |
|---|---|---|---|
| **rule** | `conventions/<slug>.md` | `~/.claude/rules/tawa-<slug>.md` | Always-on guidance |
| **command** | `commands/tawa-<name>.md` | `~/.claude/commands/tawa-<name>.md` | A `/tawa-<name>` slash command |

Rules are loaded into context automatically. Commands are invoked deliberately.
Write a rule when the guidance should always apply; write a command when it is a
procedure someone runs.

## Changing a skill

1. Edit the file in `tawa-docs` — `conventions/` for a rule, `commands/` for a command.
2. Open a PR. This is the review step; there is no other one.
3. After merge, re-seed:

```bash
cd ~/dev/iec-builder
INTERNAL_SERVICE_KEY=<key> npx tsx scripts/seed-skills.ts
```

4. Devs pick it up with `tawa skills sync`.

Seeding is **manual and deliberate** — merging a doc change does not publish it.
That is intentional: it keeps "we edited the docs" separate from "we changed what
every agent on the team is told to do."

## Versions are derived, never hand-written

```
version = 1.0.<sha256(content)[0:6] as int % 100000>
```

A version is a function of the content, so:

- **Identical content always produces an identical version.** A verbatim file move
  should leave every version unchanged — that is how you verify a refactor changed
  nothing.
- **Never hand-pick a version.** Bumping it manually (say to `1.1.0`) will be
  overwritten by the next seed and, worse, may not match the content it claims to
  describe.
- The builder's manifest hashes `name:version`, so a static version would hide
  updates from `tawa skills sync` entirely.

## Naming

A convention seeds as `tawa-<slug>` with `['platform']` tags unless it appears in
`CONVENTION_MAP` in the seed script. Add an entry there when the rule name should
differ from the file name — for example `conventions/auth.md` seeds as
`tawa-oauth`.

Command files must be named `tawa-*.md`; anything else in `commands/` is ignored.

## Gotchas

- **Editing `~/.claude/commands/` directly is a dead end.** It is the *output* of
  the pipeline. Your change survives until the next `tawa skills sync`, then
  disappears.
- **Skills are global, not per-repo.** Everything seeded here reaches every dev on
  every project. Repo-specific guidance belongs in that repo's `CLAUDE.md`.
- **A stale `last_updated` is a lie with a date on it.** Update it when you change
  a doc; it is the only signal a reader has about whether the content is current.

## History

Until 2026-08-28 the five slash-commands (`tawa-auth`, `tawa-domains`, `tawa-pm`,
`tawa-scaffold`, `tawa-troubleshoot`) were seeded from `~/.claude/commands` on a
single machine — no backup, no review, no history. They now live in
`tawa-docs/commands/` alongside the conventions.