---
name: snappy-skill
role: Meta-skill scaffolder for the snappy-* namespace. One verb creates or backfills any snappy skill.
loaded-by: PreToolUse hook (auto-injected when "snappy-skill" is mentioned)
---

# snappy-skill — Agent Loader

The scaffolder for Snappy. One verb, idempotent, templates as files.
Full reference in `SKILL.md`.

## The three-file contract

Every snappy skill has exactly `SKILL.md`, `AGENTS.md`, `api.ts`. Missing any
one is a spec violation — this skill's job is to prevent that.

## The one verb

```bash
npx tsx ~/.claude/skills/snappy-skill/api.ts scaffold snappy-<name>
```

Idempotent. Creates the dir if missing, writes only the files that don't
already exist, runs the SKILL-INDEX regen at the end. Re-running on a clean
skill produces zero writes. Templates live in `templates/` — edit them, not
the code.

## API

```typescript
import { scaffold } from "../snappy-skill/api.ts";
```

| Function | Purpose |
|---|---|
| `scaffold(name, {quiet?})` | Create or backfill a snappy-* skill. `quiet` suppresses index-generator output for JSON callers. Returns `{ path, created[], untouched[] }`. Throws if name doesn't start with `snappy-`. |
| `syncLoaderVerbTable(name, contract, {quiet?})` | Call `scaffold`, then idempotently insert or replace the one contract-owned AGENTS.md verb block. This is the only generated-loader writer. |
| `renderLoaderVerbTable(contract)` | Pure rendering used by snappy-tool-design to detect loader drift without writing. |
| `contractExample(contract, verb)` | Derive the shortest valid first CLI call from required contract arguments. |

## CLI

```bash
npx tsx ~/.claude/skills/snappy-skill/api.ts scaffold snappy-foo   # create or backfill
npx tsx ~/.claude/skills/snappy-skill/validate.ts snappy-foo       # delegates to skill-check.sh
```

## Rules

1. **Never overwrite.** Existing files are always left alone. Delete them first if you want a re-render.
2. **No placeholder exports.** The `api.ts` template exports nothing — this prevents DRY collisions (X1) across skills.
3. **Run the DRY gate first.** Before scaffolding a NEW name, run `dry-check.sh` from `snappy-settings/scripts/`. Extend, don't fragment.
4. **Validation is not reimplemented here.** `validate.ts` spawns `skill-check.sh` — the static lint IS the spec.
5. **Credentials via `env("KEY")`** from `../snappy-settings/load.ts`. Never hardcode, never bash-fallback.
6. **One loader writer.** Generated verb tables are owned here; callers use `syncLoaderVerbTable` rather than editing or templating the marked block themselves.

## Uses

| Skill | Why |
|---|---|
| `snappy-settings` | Owns `skill-spec.md` + `skill-check.sh` (the enforcer) |
| `snappy-client-template` | Per-client variant — use scaffold to instantiate |
| `snappy-gateway` | Publishes finished skills to skills.snappy.ai |
| `skill-builder` | Generic ancestor for non-snappy targets |

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `scaffold` | `name` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-skill/api.ts scaffold "<name>"` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---

## Self-correcting loader (PID feedback)

The system spec lives at `~/.claude/skills/snappy-settings/skill-spec.md`. It defines the entire Snappy operating system. You enforce it.

### Before you finish, do two things:

**1. Fix gaps (P — proportional). MANDATORY.** If this AGENTS.md didn't cover your case — if you had to read another file, run a command not documented here, work around a wrong selector, or discover a quirk — you MUST attempt an `Edit` before you can log.

- **Default action: edit this AGENTS.md.** Surgical. Add the missing line, table row, or code example where it belongs. No restructuring.
- **Only LOGGED is allowed when:** the fix needs >10 lines, spans multiple files, or requires a structural rewrite (in which case the drain-skill-regen.sh queue picks it up).
- "I didn't have time" / "it's minor" / "the next agent will figure it out" are NOT valid reasons to skip the Edit. The whole point of this loop is that minor gaps compound.
- Concrete example of a valid P-fix: lesson-2 ship agent discovered `agent-browser screenshot <path>` takes path positionally, not as `--output <path>`. That's one line in a table. Edit it in. Do not just log it.
- The goal: the next agent never has to leave the loader.

**2. Validate structure.** Check this skill against the spec:
- `api.ts` exists with typed exports, CLI mode, `import { env } from "../snappy-settings/load.ts"`
- `api.ts` calls APIs directly (no Xano proxy, unless this skill IS a Xano DB skill)
- `AGENTS.md` has API module section with import + function table + CLI
- No bash fallbacks, no hardcoded tokens anywhere
- **Every action row carries a `certificate:` block** (premises / action / trace / evidence / conclusion). Same-session toasts are NOT evidence — must be a fresh independent read. Missing or weak certificates are a gap: P-fix them inline and log to `~/.claude/logs/verification-gaps.log`.
- **DRY:** before you add a new function or new skill, run `~/.claude/skills/snappy-settings/scripts/dry-check.sh <name-or-keyword>`. If it matches an existing skill, extend that one instead. Fragmentation is the enemy.
- If any check fails → fix it or log it

**2b. If you just reported an action as successful, verify your certificate.** You may not claim PASS unless the `evidence:` line is a fresh independent read (reload, new session, server round-trip). If your evidence is a toast, a return value, or a same-session DOM read, downgrade the claim to INCONCLUSIVE and log to `verification-gaps.log`.

**3. Log always.**
```bash
echo "[$(date -u +%FT%TZ)] <skill-name>: <what was missing or fixed> [FIXED|LOGGED]" >> ~/.claude/logs/agents-md-feedback.log
```
`FIXED` = you patched it. `LOGGED` = too large for inline fix, queued for drain-skill-regen.sh.

**Do not skip this.** Every agent run must leave the system better than it found it.


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-skill Index]|root: ~/.claude/skills/snappy-skill|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}|templates:{SKILL.md}
<!-- SKILL-INDEX-END -->

---
name: snappy-skill
instruction-only: true
reports_to: tool
head: false
description: >
  Meta-skill for the snappy-* namespace. One verb, `scaffold(name, options?)`, that
  creates a new skill or fills in missing files on an existing one. Idempotent
  by design: running it on a clean skill is a no-op. Templates live as real
  files on disk under `templates/`. Validation delegates to skill-check.sh,
  the single source of truth for "is this skill valid."
  Triggers on: create snappy skill, new snappy skill, scaffold snappy, extend snappy skill,
  snappy meta skill, snappy three-file, snappy scaffolder, snappy drift.
---

# snappy-skill

The scaffolder for the Snappy operating system. Its CLI has one verb; its API
also owns the single idempotent writer for contract-derived AGENTS.md verb
tables. Templates are real files you can edit. No state, no hidden magic, no
`doTheThing()` stubs.

---

## The contract: what a snappy skill *is*

Every directory under `~/.claude/skills/snappy-*` contains exactly three
files. A skill missing any of them is broken:

| File | Job |
|---|---|
| **`SKILL.md`** | Full reference. Prose-heavy. The canonical explanation of what this skill does, why it exists, and how it fits into the rest of Snappy. Under 500 lines; split into sibling `.md` files when it gets longer. |
| **`AGENTS.md`** | Compressed loader auto-injected into any agent whose prompt mentions the skill name (via the PreToolUse hook). Short — about 60 lines. Import surface, CLI examples, rules. Ends with the self-correcting footer. |
| **`api.ts`** | The only programmatic interface. Typed exports plus a CLI guarded by `import.meta.url`. Credentials via `env("KEY")` from `../snappy-settings/load.ts`. Direct API calls — no Xano proxy unless this skill IS the Xano DB skill. |

Those are the rules every other snappy skill inherits, and they're the rules
this meta-skill enforces.

---

## The one verb

```bash
npx tsx ~/.claude/skills/snappy-skill/api.ts scaffold snappy-<name>
```

That's it. Whether the directory already exists or not, whether some of the
three files are already there or not, `scaffold` brings the skill into
compliance. It never overwrites content. Running it on a clean skill produces
zero writes (the output says `untouched: SKILL.md, AGENTS.md, api.ts` and
`git status` is clean).

**That idempotency is the whole point.** The same code path handles three
cases that used to be separate:

1. **Greenfield.** New name → dir created, all three files written.
2. **Drift backfill.** Existing directory with e.g. only SKILL.md → missing
   AGENTS.md and api.ts get filled in, SKILL.md is left untouched.
3. **Re-run on a clean skill.** Nothing to do, no-op.

There's no `upgrade` verb, no `--force`, no destructive flags. If you want to
replace a file, delete it and re-run `scaffold`.

### The generated-loader writer

`syncLoaderVerbTable(name, contract)` calls `scaffold(name)` first, then inserts
or replaces only the block between `SNAPPY-CONTRACT-VERBS-START/END`. It derives
the verb names, ordered argument words, effects, and shortest first calls from
the contract. Re-running an unchanged contract writes nothing. Tool-design lint
uses the pure `renderLoaderVerbTable(contract)` twin to detect drift, so there is
one representation and one writer.

### How purpose inference works

When `scaffold` writes a new `SKILL.md`, it needs a one-line purpose for the
YAML description. It picks one, in order:

1. **An existing `SKILL.md`'s `purpose:` line.** (Only relevant when scaffold
   is re-scaffolding a file that already exists — which it won't, since it
   never overwrites. In practice this branch reads an existing file from a
   previous aborted run.)
2. **The first non-empty paragraph of the largest top-level `.md` file in the
   directory.** This is how drift skills that shipped with rich prose but no
   frontmatter-style SKILL.md get a sensible description auto-extracted —
   snappy-dashboard and snappy-swarm both worked this way.
3. **Fallback:** `"The <name> skill — purpose TBD."` You fix it by editing
   the file.

No LLM involved. All three branches are local filesystem reads. Determinism
is free.

---

## Templates are files, not string literals

The three templates live under `templates/` in this skill:

```
templates/
  SKILL.md      (the frontmatter + section skeleton)
  AGENTS.md     (import surface + rules)
  api.ts        (minimal CLI, env() import, no exports)
```

Each template is a real file you can `cat`, edit, and preview. The scaffold
verb reads them, substitutes three tokens (`{{NAME}}`, `{{PURPOSE}}`,
`{{TRIGGERS}}`), and writes the result. **If you want to change what a new
snappy skill looks like, edit the templates — not `api.ts`.** That's the
Karpathy-ish nano-* contract: the template is the thing, and the code that
renders it fits on one screen.

The `api.ts` template deliberately exports *nothing*. A scaffolded skill
starts with a CLI that prints "replace me" and zero public functions. This
kills a whole class of cross-skill collisions: if every new skill exported a
placeholder `hello()`, the DRY check (X1) would fail on the second scaffold.
The lesson — don't ship code you don't need.

---

## Validation is not rewritten here

`validate.ts` in this directory is 22 lines and does one thing: it spawns
`~/.claude/skills/snappy-settings/scripts/skill-check.sh <name>`. The static
lint IS the validation. This skill does not reimplement rules, does not keep
its own checklist, does not drift from the spec. The spec is
`snappy-settings/skill-spec.md`; the enforcer is `skill-check.sh`; `validate`
is a thin handle for invoking the enforcer through the snappy-skill verb
family.

```bash
npx tsx ~/.claude/skills/snappy-skill/validate.ts snappy-foo
```

Exit 0 = pass. Exit non-zero = see the rule codes in the output and fix
them.

---

## Before you create a new skill: the DRY gate

Fragmentation is the system's worst failure mode. Before `scaffold`, run:

```bash
~/.claude/skills/snappy-settings/scripts/dry-check.sh snappy-<name> <keywords...>
```

It greps every existing skill for name overlap, exported function-name
collisions, and trigger/description keyword overlap. **A new skill is only
justified when all of the following are true:**

1. `dry-check.sh` exits 0.
2. The capability does not fit any cluster listed in
   `snappy-settings/skill-spec.md` §7.
3. You logged the decision with tag `[NEW-SKILL]` in
   `~/.claude/logs/agents-md-feedback.log`.

If there's a close match — **extend that skill instead**. A new verb on an
existing `api.ts` is almost always the right answer.

---

## When to use this skill (and when not to)

Use `snappy-skill` when:

- You're creating a new `snappy-*` skill from scratch
- A drift skill (content-only directory) needs `AGENTS.md` + `api.ts`
  filled in without disturbing its existing prose
- You want to verify a skill you just edited still passes the spec

Don't use it when:

- The target isn't in the `snappy-*` namespace — use generic `skill-builder`
- You want to *rewrite* files that already exist — delete them first, or
  edit directly; `scaffold` will never clobber
- You want to add a capability to an existing skill — just edit `api.ts`,
  run `validate.ts`, done

---

## Related

| Skill | Why |
|---|---|
| `snappy-settings` | Owns `skill-spec.md` (the contract) and `skill-check.sh` (the enforcer). Also owns `load.ts` and the `.env.cache` single source of truth. |
| `snappy-client-template` | Per-client skill variant. Use this meta-skill's scaffold verb to instantiate new per-client skills. |
| `snappy-gateway` | Publishes finished skills to skills.snappy.ai. |
| `skill-builder` | Generic ancestor for non-snappy skills. Use it when the target is outside the namespace. |

---

**Skill Status**: COMPLETE

## Near neighbours

Skills whose description overlaps this one enough that a reader could pick the
wrong door. Each row is that skill's own first sentence about itself, so the
choice is made on its words, not on a summary written here.

| Skill | Reach for it instead when |
|---|---|
| `snappy-freshbooks` | Snappy FreshBooks -- authoritative source for DRAFT invoicing, billing, time tracking, expens… |

#!/usr/bin/env npx tsx
/**
 * snappy-skill/api.ts — Meta-skill scaffolder for the Snappy namespace.
 *
 * One verb: scaffold(name). Idempotent.
 *   - Creates the dir if missing, fills in any of SKILL.md/AGENTS.md/api.ts
 *     that don't already exist. Never overwrites content.
 *   - Appends the self-correcting footer to a freshly-written AGENTS.md.
 *   - Purpose is inferred from an existing SKILL.md, or the first non-empty
 *     paragraph of the largest top-level .md in the dir, or the skill name.
 *
 * Templates live as real files in ./templates/ — edit those to change the
 * shape of a skill, not the string literals in this file.
 */
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "fs";
import { spawnSync } from "child_process";
import { join, dirname } from "path";
import { fileURLToPath } from "url";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const HERE = dirname(realpathSync(fileURLToPath(import.meta.url)));
const SKILLS_ROOT = dirname(HERE);
const FOOTER_PATH = join(dirname(SKILLS_ROOT), "hooks/agents-md-footer.md");
const REGEN_INDEX = join(SKILLS_ROOT, "snappy-settings/scripts/regenerate-skill-indices.sh");
// A NEW SKILL DECLARES WHOSE IT IS ⟨lane base-set, 2026-09-09⟩. `.snappy-meta.json`
// carries `tier` — the word `snappy-gateway` has published under since April —
// and `scripts/gates/base-set.mjs` reads exactly that one field to decide what a
// second person's clone may contain. The default is `base`: a new skill is the
// product's until someone says otherwise, and a skill that carries a real
// client's anything changes it to `personal` in the same commit. Before this, 69
// of 98 metas had no tier at all and there was no one representation of
// "this is his, not the product's".
const TEMPLATES = ["SKILL.md", "AGENTS.md", "api.ts", ".snappy-meta.json"] as const;

import type { HandSpec } from "../snappy-settings/spec-read.ts";
export type { HandSpec };

export interface ScaffoldResult {
  path: string;
  created: string[];
  untouched: string[];
}

export interface HandVerb {
  args?: readonly string[];
  effect?: string;
  flags?: Readonly<Record<string, string>>;
  class?: "read" | "additive-write" | "destructive" | "spend" | "send-to-a-person";
  execution?: "call" | "job";
  idempotent?: boolean;
  openWorld?: boolean;
  latency?: Readonly<{ p50Ms?: number; maxMs?: number }>;
  annotations?: Readonly<Record<string, boolean | string>>;
  inputSchema?: Readonly<Record<string, unknown>>;
}

export interface HandContract {
  skill: string;
  description?: string;
  kind?: string;
  requires?: readonly string[];
  refusals?: Readonly<Record<string, unknown>>;
  verbs: Readonly<Record<string, HandVerb>>;
  /**
   * THE VENDOR DOCUMENT THIS HAND SITS ON ⟨R61, 2026-09-09⟩.
   *
   * A hand is a contract between us and somebody else's API, and that half of
   * it changes without a commit here. Naming the spec is what makes the change
   * mechanically noticeable: `kind` "openapi"/"discovery" can be diffed,
   * "docs" is checked more weakly, and "mini"/"none" are declarations WITH a
   * reason so the lint can tell a deliberate gap from an unexamined one.
   *
   * The shape and its reader live together in
   * `snappy-settings/spec-read.ts` — one representation, and this is the
   * import of it rather than a second copy.
   */
  spec?: HandSpec;
}

export interface LoaderSyncResult {
  path: string;
  changed: boolean;
  verbs: number;
}

const VERBS_START = "<!-- SNAPPY-CONTRACT-VERBS-START -->";
const VERBS_END = "<!-- SNAPPY-CONTRACT-VERBS-END -->";

export function scaffold(name: string, opts: { quiet?: boolean } = {}): ScaffoldResult {
  if (!name.startsWith("snappy-")) throw new Error(`name must start with "snappy-": ${name}`);
  const dir = join(SKILLS_ROOT, name);
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });

  const purpose = inferPurpose(dir, name);
  const triggers = `${name}, ${name.replace(/^snappy-/, "")}`;
  const vars = { NAME: name, PURPOSE: purpose, TRIGGERS: triggers };

  const created: string[] = [];
  const untouched: string[] = [];
  for (const f of TEMPLATES) {
    const dst = join(dir, f);
    if (existsSync(dst)) { untouched.push(f); continue; }
    writeFileSync(dst, render(readFileSync(join(HERE, "templates", f), "utf-8"), vars));
    if (f === "AGENTS.md" && existsSync(FOOTER_PATH)) {
      appendFileSync(dst, "\n" + readFileSync(FOOTER_PATH, "utf-8"));
    }
    created.push(f);
  }
  if (existsSync(REGEN_INDEX)) {
    spawnSync("bash", [REGEN_INDEX, name], {
      stdio: opts.quiet ? "ignore" : "inherit",
      env: { ...process.env, SNAPPY_SKILLS_DIR: SKILLS_ROOT },
    });
  }
  return { path: dir, created, untouched };
}

/** Render the contract-owned loader block. Keep this writer in snappy-skill so
 * consumers can request regeneration without inventing a second template. */
export function renderLoaderVerbTable(contract: HandContract): string {
  const rows = Object.entries(contract.verbs).map(([verb, spec]) => {
    const args = spec.args?.length ? spec.args.map((arg) => `\`${arg}\``).join(", ") : "—";
    return `| \`${verb}\` | ${args} | \`${spec.effect ?? "unspecified"}\` | \`${contractExample(contract, verb)}\` |`;
  });
  const table = rows.length
    ? [
        "| Verb | Contract arguments | Effect | First call |",
        "|---|---|---|---|",
        ...rows,
      ].join("\n")
    : "This skill declares no executable verbs. Its `instruction-only` label is intentional.";

  return [
    VERBS_START,
    "## Contract verbs",
    "",
    "Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.",
    "",
    table,
    "",
    "## Show the result",
    "",
    "When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.",
    "See `/snappy-faces` for face selection. Human-facing images must crop to the",
    "element, render at 2x on Retina, and fill the destination channel instead of",
    "placing a small card in a full-page screenshot.",
    VERBS_END,
  ].join("\n");
}

/** Create missing skill files through scaffold(), then replace or insert only
 * the contract-owned loader block. Re-running an unchanged contract is a no-op. */
export function syncLoaderVerbTable(
  name: string,
  contract: HandContract,
  opts: { quiet?: boolean } = {},
): LoaderSyncResult {
  if (contract.skill !== name) {
    throw new Error(`contract skill mismatch: expected ${name}, got ${contract.skill}`);
  }
  scaffold(name, { quiet: true });
  const path = join(SKILLS_ROOT, name, "AGENTS.md");
  const before = readFileSync(path, "utf-8");
  const block = renderLoaderVerbTable(contract);
  const marked = new RegExp(`${escapeRegExp(VERBS_START)}[\\s\\S]*?${escapeRegExp(VERBS_END)}`);
  let after: string;
  if (marked.test(before)) {
    after = before.replace(marked, block);
  } else {
    const footer = "\n---\n\n## Self-correcting loader";
    const at = before.indexOf(footer);
    after = at >= 0
      ? `${before.slice(0, at).trimEnd()}\n\n${block}\n${before.slice(at)}`
      : `${before.trimEnd()}\n\n${block}\n`;
  }
  const changed = after !== before;
  if (changed) writeFileSync(path, after);
  if (!opts.quiet) console.log(`${changed ? "updated" : "unchanged"}: ${path}`);
  return { path, changed, verbs: Object.keys(contract.verbs).length };
}

/** The safest useful first call: required contract words get inert placeholders;
 * optional words and flags are omitted. */
export function contractExample(contract: HandContract, verb: string): string {
  const spec = contract.verbs[verb];
  if (!spec) throw new Error(`verb "${verb}" is not in ${contract.skill}.verbs`);
  const required = (spec.args ?? []).filter((arg) => !arg.endsWith("?"));
  const values = required.map(exampleValue);
  return [
    "npx tsx",
    `~/.claude/skills/${contract.skill}/api.ts`,
    verb,
    ...values,
  ].join(" ");
}

function exampleValue(raw: string): string {
  const arg = raw.replace(/\?$/, "");
  if (/json$/i.test(arg) || /^(ids|items|options)$/i.test(arg)) return "'[\"<" + arg.replace(/-json$/i, "") + ">\"]'";
  if (/^(text|body|message|query|subject|caption|prompt|title|name)$/i.test(arg)) return `"<${arg}>"`;
  return `<${arg}>`;
}

function escapeRegExp(value: string): string {
  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}

function render(tmpl: string, vars: Record<string, string>): string {
  return tmpl.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
}

function inferPurpose(dir: string, name: string): string {
  const skillMd = join(dir, "SKILL.md");
  if (existsSync(skillMd)) {
    const m = readFileSync(skillMd, "utf-8").match(/^purpose:\s*(.+)$/m);
    if (m) return m[1].trim();
  }
  const mds = existsSync(dir)
    ? readdirSync(dir).filter(f => f.endsWith(".md") && f !== "AGENTS.md" && f !== "SKILL.md")
    : [];
  if (mds.length) {
    mds.sort((a, b) => statSync(join(dir, b)).size - statSync(join(dir, a)).size);
    const text = readFileSync(join(dir, mds[0]), "utf-8");
    const body = text.replace(/^---[\s\S]*?---\n/, "").replace(/^#.*\n/gm, "").trim();
    const first = body.split(/\n\s*\n/)[0]?.replace(/\s+/g, " ").trim();
    if (first) return first.slice(0, 140);
  }
  return `The ${name.replace(/^snappy-/, "")} skill — purpose TBD.`;
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-skill",
  description: "Meta-skill for the snappy-* namespace. One verb, `scaffold(name, options?)`, that creates a new skill or fills in missing files on an existing one. Idempotent by design: running it on a clean skill is a no-op. Templates live as real files on disk under `templates/`. Validation delegates to skill-check.sh, the single source of truth for \"is this skill valid.\" Triggers on: create snappy skill, new snappy skill, scaffold snappy, extend snappy skill, snappy meta skill, snappy three-file, snappy scaffolder, snappy drift.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("missing_argument", "unknown_verb"),
  verbs: {
    scaffold: {
      args: ["name"], effect: "write-reversible", class: "additive-write", openWorld: false,
      annotations: annotationsForClass("additive-write", { openWorld: false }),
      inputSchema: { properties: { name: { type: "string", description: "Name of the thing to act on" } } },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}

if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const [, , cmd, name] = process.argv;
  if (!cmd || cmd === "help") {
    console.log("Usage: npx tsx api.ts scaffold <snappy-name>");
    process.exit(0);
  }
  if (cmd === "scaffold") {
    if (!name) { console.error("scaffold needs a name"); process.exit(1); }
    const r = scaffold(name);
    console.log(`${r.path}`);
    if (r.created.length) console.log(`created:   ${r.created.join(", ")}`);
    if (r.untouched.length) console.log(`untouched: ${r.untouched.join(", ")}`);
    process.exit(0);
  }
  console.error(`unknown: ${cmd}`);
  process.exit(1);
}

/**
 * COVERAGE FOR SNAPPY-SKILL'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-skill declares. */
const DECLARED = [
  "missing_argument",
  "unknown_verb",
] as const;

test("snappy-skill declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("missing_argument is grounded: at least one verb has a required word", () => {
  const required = Object.values(HAND_CONTRACT.verbs as Record<string, { args?: readonly string[] }>)
    .flatMap((v) => (v.args ?? []).filter((a) => !a.endsWith("?")));
  assert.ok(required.length > 0, "no verb has a required argument, so missing_argument can never fire");
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});

---
name: {{NAME}}
description: {{PURPOSE}}
---

# {{NAME}} — Agent Loader

{{PURPOSE}}

## Purpose

<!-- When to use this skill, and when NOT to. The description's own words. -->

## Rules

- Credentials via `env("KEY")` from `../snappy-settings/load.ts`
- Direct API calls only — no Xano proxying unless this IS a Xano DB skill
- No hardcoded tokens, no bash fallbacks
- Every exported function returns a real value or throws; no silent "TODO"s

## Agents

<!-- One `### <name>` per agent this skill defines, when it defines any. A skill
     with one set of verbs and no named agent leaves this empty — that is the
     ordinary hand and is not a defect. Two agents in one skill is ONE loader
     with two `###` blocks, never two AGENTS.md files ⟨spec §3.2⟩:

### reader
Reads the thing and reports it. Never writes.
- verbs: `list`, `get`
- reaches: `snappy-faces`
-->

## Uses

<!-- The other skills this one reaches, one per line, e.g.

- `snappy-mac` — the Mac's own services as one API (screen, clipboard, apps)
- `snappy-faces` — draws every read

     `## Used by` is the other direction and is GENERATED from everyone else's
     `## Uses` (`node scripts/agents-md-migrate.mjs --used-by`) — never written
     by hand, because a back-link a person types is wrong the first time the
     other end changes and nothing tells them. -->

## API module

```typescript
// No verbs exported yet. Add exports in api.ts, then document them here:
// import { someVerb } from "../{{NAME}}/api.ts";
//
// | Function | Purpose |
// |---|---|
// | `someVerb(...)` | what it does |
```

```bash
npx tsx ~/.claude/skills/{{NAME}}/api.ts help
```

---
name: {{NAME}}
description: >
  {{PURPOSE}}
  Triggers on: {{TRIGGERS}}.
---

# {{NAME}}

## Purpose

{{PURPOSE}}

## When to Use This Skill

Describe the concrete situations that should activate this skill: what the
user is trying to do, what other skills have just run, what data is on hand.

## Quick Start

```bash
npx tsx ~/.claude/skills/{{NAME}}/api.ts help
```

## Workflow

**Inputs**
- `snappy-settings` — credentials via `env()`
- (list upstream skills that feed this one)

**Outputs**
- (what this produces, where it lands)

**Orchestrator**
- (who invokes this — `snappy-ops`, a cron, a chain handler)

## Related Skills

| Skill | Why |
|---|---|
| `snappy-settings` | credential loader |

#!/usr/bin/env npx tsx
/**
 * {{NAME}}/api.ts — {{PURPOSE}}
 *
 * This is a scaffolded stub. Replace the CLI below with real verbs.
 * Credentials load via `env("KEY")` from `../snappy-settings/load.ts`.
 *
 * THE CONTRACT COMES NEXT, and it is what makes this callable by a button, a
 * trigger or an AI (`skill-spec.md` §2b is the one shape). Measured 2026-09-09:
 * this template emits no `HAND_CONTRACT`, so every scaffolded hand is written
 * by hand from that section — this comment is the pointer to it, not a second
 * copy of it.
 *
 * NAME THE VENDOR DOCUMENT while you are there:
 *
 *   spec: {
 *     kind: "openapi",   // openapi | discovery | docs | mini | none
 *     url: "",           // the JSON document itself; a public spec, no credential
 *     operations: {},    // this hand's verb -> the vendor's operation id
 *     // reason: "",     // REQUIRED for docs | mini | none, one sentence
 *   },
 *
 * A hand with no `spec` is not graded on it (rule 61 DEFERs) — but it is also
 * the hand nobody notices when the vendor ships something new.
 */
import { realpathSync } from "fs";
import { env } from "../snappy-settings/load.ts";

// --- CLI ---
if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const [, , cmd] = process.argv;
  if (!cmd || cmd === "help") {
    console.log("Usage: npx tsx api.ts <help>");
    console.log("Scaffolded skill — replace this CLI with real verbs.");
    process.exit(0);
  }
  console.error(`Unknown: ${cmd}`);
  process.exit(1);
}

#!/usr/bin/env npx tsx
/**
 * snappy-skill/validate.ts — Delegates to skill-check.sh.
 *
 * The static lint lives in snappy-settings/scripts/skill-check.sh and is the
 * single source of truth for "is this skill valid." This file exists so you
 * can invoke validation through the snappy-skill verb family:
 *
 *   npx tsx validate.ts <snappy-name>
 */
import { spawnSync } from "child_process";
import { realpathSync } from "fs";
import { join } from "path";

const CHECKER = join(process.env.HOME!, ".claude/skills/snappy-settings/scripts/skill-check.sh");

if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  const name = process.argv[2];
  if (!name) { console.error("Usage: validate.ts <snappy-name>"); process.exit(2); }
  const r = spawnSync("bash", [CHECKER, name], { stdio: "inherit" });
  process.exit(r.status ?? 1);
}