@fastagent-sh/fastagent 0.12.0

package/dist/scaffold/init.js

@@ -0,0 +1,249 @@
+/**
+ * Init: scaffold a runnable fastagent workspace, offline. Default = a COMPLETE agent (persona.md +
+ * the writing-great-skills skill + a fetch-url code tool + fastagent.config.mjs + package.json +
+ * .gitignore); `--minimal` drops the code tool and package.json. persona.md is the agent's identity
+ * (prompt segment ①); an existing AGENTS.md is never written or touched — it is project context (②),
+ * kept as-is. skills/ and tools/ are the agent's self-editable capabilities (re-read each turn).
+ *
+ * Layout (the jurisdiction rule — core.md scenario grid): the agent kit goes FLAT into `dir` ("a
+ * directory is an agent") UNLESS an existing system already CLAIMS the tree — a toolchain config that
+ * sweeps files by pattern (tsconfig/framework configs), a deploy manifest (Dockerfile/fly/railway/…),
+ * or fastagent's own convention names already occupied (non-empty tools//channels//skills/). Any such
+ * signal → the kit defaults into `./agent` (its own namespace; `config.agentDir` points there), so the
+ * host's toolchain and the agent's surface never sweep each other. {@link detectHostSignals} detects;
+ * the CLI decides (flags override) and reports the reason.
+ *
+ * Scope: init is best-effort atomic for ORDINARY inputs — it never overwrites existing files,
+ * preflights non-directory scaffold parents, and rolls back a partial write (one exception: the
+ * .gitignore APPEND is not rolled back — idempotent, harmless residue). It does not defend against
+ * every pathological target state (TOCTOU, FIFOs, disk-full): recover by delete-and-retry.
+ *
+ * Sibling scaffold modules: add-channel.ts (`add <channel>`), vendor-skill.ts (`add skill`). The files
+ * this module writes are real templates under templates/, read through templates.ts.
+ */
+import { access, appendFile, lstat, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { WORKSPACE_CONFIG_NAMES } from "../engines/pi/config.js";
+import { detectRuntime, readPackageJson } from "../runtime.js";
+import { loadRootIgnore } from "../workspace.js";
+import { baseTemplate, configTemplate, packageJson, personaTemplate, toPackageName } from "./templates.js";
+import { fastagentVersion } from "../version.js";
+/** Filename marks of a system that claims files by pattern (a build toolchain — F2 in the jurisdiction
+ *  rule). Not JS-only: a Python/Go/Rust/JVM/Ruby/PHP project's build system claims its tree exactly the
+ *  same way — an AGENTS.md-carrying Go repo must not get a flat kit (with a package.json!) in its root.
+ *  Deliberately absent: `Makefile` (too generic — notes/dotfiles repos carry one without a toolchain). */
+const TOOLCHAIN_RE = /^(tsconfig\.json|(next|vite|astro|svelte|nuxt|remix|webpack|rollup)\.config\.[cm]?[jt]s|go\.mod|Cargo\.toml|pyproject\.toml|setup\.py|requirements\.txt|Gemfile|pom\.xml|build\.gradle(\.kts)?|composer\.json|CMakeLists\.txt)$/;
+/** Filename marks of a deploy manifest — the tree ships as a non-agent unit (F4). */
+const DEPLOY_RE = /^(Dockerfile|fly\.toml|railway\.toml|vercel\.json|netlify\.toml)$/;
+/**
+ * Jurisdiction signals: evidence that an existing system already claims this tree, so a flat agent kit
+ * would put each side's files under the other's jurisdiction (host tsc sweeps agent .ts; fastagent
+ * scans host tools/). Three classes, derived from the actual failure modes — a toolchain config, a
+ * deploy manifest, or fastagent's convention names already occupied. Any hit → the kit defaults into
+ * `./agent`. Deliberately NOT signals: "dir is non-empty", "has package.json", "has src/" — markdown
+ * and loose scripts are claimed by nobody, and "a directory is an agent" stays the default. Known
+ * tradeoff, decided for visibility: a HAND-BUILT agent dir (skills//tools/ authored for the agent, no
+ * config yet) also hits the occupation signal and defaults to ./agent — wrong for that case, but the
+ * reason is printed and `--flat` overrides; the reverse default would silently mis-scan a host's dirs.
+ */
+export async function detectHostSignals(dir) {
+    // Only ENOENT/ENOTDIR mean "nothing there" (fresh dir → flat). A real IO failure (EACCES…) must
+    // surface, not silently decide the layout — init is about to write into this directory anyway.
+    const absent = (err) => {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return [];
+        throw err;
+    };
+    const signals = [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(absent);
+    for (const e of entries) {
+        if (e.isFile() && (TOOLCHAIN_RE.test(e.name) || DEPLOY_RE.test(e.name)))
+            signals.push(e.name);
+    }
+    for (const name of ["tools", "channels", "skills"]) {
+        const st = await lstat(join(dir, name)).catch((err) => {
+            absent(err);
+            return undefined;
+        });
+        // Dotfiles (.DS_Store, .gitkeep) are not agent surface — the loaders would never scan them, so
+        // they must not count as "occupied" either (the signal mirrors what fastagent would actually scan).
+        const occupants = st?.isDirectory()
+            ? (await readdir(join(dir, name)).catch(absent)).filter((f) => !f.startsWith("."))
+            : [];
+        if (occupants.length > 0)
+            signals.push(`${name}/`);
+    }
+    return signals.sort();
+}
+/** The `cd` target to show in `init`'s next-steps: the relative path when the target is inside `cwd`,
+ *  the absolute path when it climbs out (a `../../..` is noise), or undefined when already in `cwd`. */
+export function nextStepCd(cwd, dir) {
+    const rel = relative(cwd, dir);
+    if (rel === "")
+        return undefined;
+    // "Climbs out" is a path-SEGMENT check — rel is ".." or starts with "../" (or "..\" on Windows). A
+    // bare startsWith("..") would wrongly flag an in-cwd directory literally named "..agent".
+    const escapes = rel === ".." || /^\.\.[/\\]/.test(rel);
+    return escapes ? dir : rel;
+}
+/** Does a path exist? (async; shared with the sibling scaffold modules). */
+export async function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+/**
+ * Scaffold a runnable workspace into {@link dir} (created if missing). Default is a complete agent
+ * (persona.md + the writing-great-skills skill + a code tool + package.json); `--minimal` drops the
+ * code tool and package.json. The kit goes flat into `dir`, or into {@link ScaffoldOptions.agentDir}
+ * (config at the root pointing there). Refuses only an existing fastagent.config.* (the ownership
+ * marker — already a workspace); every other pre-existing file (AGENTS.md, .gitignore, package.json)
+ * is kept, never overwritten — an existing AGENTS.md is the project's context, adopted as-is.
+ */
+export async function scaffoldWorkspace(dir, options = {}) {
+    const minimal = options.minimal ?? false;
+    const kit = options.agentDir ?? "."; // where the agent's own surface lands
+    const skill = (name) => ({
+        rel: join(kit, "skills", "writing-great-skills", name),
+        content: baseTemplate(`skills/writing-great-skills/${name}`),
+    });
+    const files = [
+        // ① identity. AGENTS.md is deliberately NOT scaffolded: a fresh agent has no project context, and
+        // an existing repo already owns its AGENTS.md (kept untouched, read as ② context from cwd).
+        { rel: join(kit, "persona.md"), content: personaTemplate(options.agentDir) },
+        // The example skill: how to author skills well — the core of self-iteration. Markdown, so it
+        // ships in --minimal too. Vendored verbatim from mattpocock/skills (MIT); LICENSE sits beside it.
+        skill("SKILL.md"),
+        skill("GLOSSARY.md"),
+        skill("LICENSE"),
+        // Run-root pieces: the config (carrying agentDir when the kit is a subdir), secrets hygiene, env template.
+        { rel: "fastagent.config.mjs", content: configTemplate(options.agentDir) },
+        { rel: ".gitignore", content: baseTemplate(options.agentDir ? "gitignore.agentdir-root" : "gitignore") },
+        { rel: ".env.example", content: baseTemplate("env.example") },
+    ];
+    if (!minimal) {
+        files.push({ rel: join(kit, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") }, 
+        // The kit's own manifest: in the agentDir layout the agent self-contains its deps, so the host's
+        // package.json/lockfile is never touched. The name says WHOSE agent it is (the workspace's), not
+        // which subdirectory it happens to live in.
+        {
+            rel: join(kit, "package.json"),
+            content: packageJson(options.agentDir ? `${toPackageName(dir)}-agent` : toPackageName(dir), await fastagentVersion()),
+        }, ...(options.agentDir ? [{ rel: join(kit, ".gitignore"), content: baseTemplate("gitignore.kit") }] : []));
+    }
+    // Guard on the ownership marker: a config means "already a fastagent workspace". Fail visibly
+    // rather than double-initialize. (AGENTS.md is NOT a marker — it is context, adopted untouched.)
+    const conflicts = [];
+    for (const name of WORKSPACE_CONFIG_NAMES)
+        if (await exists(join(dir, name)))
+            conflicts.push(name);
+    if (conflicts.length > 0) {
+        throw new Error(`"${dir}" already has ${conflicts.join(", ")} — already a fastagent workspace`);
+    }
+    // Never merge the kit into an existing NON-EMPTY directory (a host repo may own an unrelated `agent/`
+    // — common in AI products): wx would keep its files, but persona.md/skills/ landing inside someone
+    // else's code dir is a silent mix. Refuse with the way out. Dotfiles (.DS_Store, .gitkeep) don't
+    // count — same rule as detectHostSignals' occupation check. A SYMLINKED kit path slips past this
+    // readdir (it follows links) — deliberate: the parent preflight below lstat-rejects it before any write.
+    if (options.agentDir) {
+        const occupants = (await readdir(join(dir, kit)).catch(() => [])).filter((f) => !f.startsWith("."));
+        if (occupants.length > 0) {
+            throw new Error(`"${kit}" already exists and is not empty — if it is unrelated to the agent, pick another name ` +
+                `(--agent-dir <name>) or go flat (--flat); to adopt it as the kit, empty it first`);
+        }
+    }
+    // Was the target non-empty BEFORE we wrote anything? (missing dir = empty).
+    const intoNonEmpty = (await readdir(dir).catch(() => [])).length > 0;
+    // Preflight scaffold parent dirs: a pre-existing non-directory there would make mkdir fail mid-loop
+    // AFTER the first write, leaving a half-scaffold. Detect it before any write (lstat, not stat: a
+    // symlinked parent must be rejected, not followed — it would write outside the workspace).
+    const parents = new Set();
+    for (const file of files) {
+        let p = dirname(file.rel);
+        while (p !== "." && p !== "") {
+            parents.add(p);
+            p = dirname(p);
+        }
+    }
+    for (const rel of parents) {
+        const st = await lstat(join(dir, rel)).catch(() => undefined);
+        if (st && !st.isDirectory()) {
+            throw new Error(`cannot scaffold: "${rel}" exists and is not a directory (a regular file or symlink) — remove it, or init elsewhere`);
+        }
+    }
+    await mkdir(dir, { recursive: true });
+    const created = [];
+    const skipped = [];
+    const patched = [];
+    const warnings = [];
+    // ONE rollback scope: any failure removes files written THIS run (guard + wx guarantee they are
+    // ours), so scaffoldWorkspace is atomic — except the .gitignore APPEND below, which is not rolled
+    // back (the residue is idempotent, harmless ignore lines; removing someone else's file's tail is riskier).
+    try {
+        for (const file of files) {
+            const abs = join(dir, file.rel);
+            await mkdir(dirname(abs), { recursive: true });
+            try {
+                await writeFile(abs, file.content, { flag: "wx" }); // wx: never clobber
+                created.push(file.rel);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    skipped.push(file.rel);
+                else
+                    throw error;
+            }
+        }
+        // Ignore ownership follows layout jurisdiction. Run-root state/secrets live at `dir`, so the ROOT
+        // .gitignore owns `.env` + `.fastagent`. The kit's npm deps live where the kit lives: flat → root
+        // `node_modules/`; agentDir → `<agentDir>/.gitignore` owns its own `node_modules/`. This avoids
+        // patching a host repo's root ignore with agent-internal dependency paths while still preventing the
+        // post-init 25k-file untracked flood.
+        const coveredBy = (ig, p) => (ig?.ignores(p) ?? false) || (ig?.ignores(`${p}/`) ?? false);
+        const rootIgnore = await loadRootIgnore(dir);
+        const rootRequired = [
+            { path: ".env", pattern: ".env" },
+            { path: ".fastagent", pattern: ".fastagent" },
+            ...(!minimal && !options.agentDir ? [{ path: "node_modules", pattern: "node_modules/" }] : []),
+        ];
+        const rootNeed = rootRequired.filter((e) => !coveredBy(rootIgnore, e.path));
+        if (rootNeed.length > 0) {
+            await appendFile(join(dir, ".gitignore"), `\n# fastagent\n${rootNeed.map((e) => e.pattern).join("\n")}\n`);
+            patched.push(".gitignore");
+            // A .fastagentignore is applied LAST and can re-include what .gitignore excludes — the append
+            // cannot fix that, so re-check and keep it a visible warning instead of false assurance.
+            const after = await loadRootIgnore(dir);
+            const still = rootNeed.filter((e) => !coveredBy(after, e.path)).map((e) => e.path);
+            if (still.length > 0) {
+                warnings.push(`your .gitignore/.fastagentignore does not exclude ${still.map((s) => `"${s}"`).join(", ")} — a deploy that copies the directory may ship secrets/state`);
+            }
+        }
+        if (!minimal && options.agentDir) {
+            // Deliberately checks ONLY the kit's own ignore, not the root: the kit is the portable agent
+            // directory, and its dependency ignore must travel WITH it (a fresh kit .gitignore carries
+            // node_modules/ unconditionally for the same reason) — a root-level `node_modules/` that happens
+            // to cover it today doesn't survive the kit being copied out of the host repo.
+            const kitIgnore = await loadRootIgnore(join(dir, kit));
+            if (!coveredBy(kitIgnore, "node_modules")) {
+                const rel = join(kit, ".gitignore");
+                await appendFile(join(dir, rel), `\n# fastagent\nnode_modules/\n`);
+                patched.push(rel);
+            }
+        }
+        // A kept package.json won't carry the tool's deps — the example tool would not resolve. The install
+        // command matches the workspace's runtime (bun.lock → bun add).
+        const keptPkg = join(kit, "package.json");
+        if (!minimal && skipped.includes(keptPkg)) {
+            const kitAbs = join(dir, kit);
+            const add = detectRuntime(kitAbs, await readPackageJson(kitAbs)).runtime === "bun" ? "bun add" : "npm install";
+            warnings.push(`kept the existing ${keptPkg} — run \`${add} @fastagent-sh/fastagent\` there so the example tool resolves`);
+        }
+    }
+    catch (error) {
+        // Best-effort rollback of a partial scaffold: a file that won't delete is left behind (the original
+        // error below is the one worth surfacing — a cleanup failure must not mask it).
+        for (const rel of created.reverse())
+            await rm(join(dir, rel), { force: true }).catch(() => { });
+        throw error;
+    }
+    return { dir, complete: !minimal, agentDir: options.agentDir, created, skipped, patched, intoNonEmpty, warnings };
+}

package/dist/scaffold/templates/env.example

@@ -0,0 +1,24 @@
+# Environment for this agent. Copy to .env (gitignored) and uncomment what you need.
+# Everything here is OPTIONAL — the defaults work without a .env.
+
+# --- Model auth ---
+# Pick auth once: `fastagent login` (a subscription/OAuth provider like openai-codex, or an API key),
+# or set a provider API key here — the variable name is provider-specific (e.g. OPENAI_API_KEY,
+# ANTHROPIC_API_KEY). `fastagent dev` then lets you choose a model from whatever you're logged into.
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# --- Model selection (overrides fastagent.config) ---
+# Precedence: --model flag > FASTAGENT_MODEL > config. `fastagent dev` writes your first-run pick to
+# fastagent.config; set it here to override per-environment.
+# FASTAGENT_MODEL=openai-codex/gpt-5.5
+
+# --- Serving (fastagent start) ---
+# Port precedence: --port > PORT > config.http.port > 8787
+# PORT=8787
+# Machine-state root: sessions, auth.json, and channel state all derive from it.
+# Default: <dir>/.fastagent. Point it at a mounted volume so a redeploy that replaces the
+# directory keeps conversations and credentials.
+# FASTAGENT_STATE_DIR=/data/fastagent
+# Override just the sessions path (default: <state root>/sessions):
+# FASTAGENT_SESSIONS_DIR=/data/sessions

package/dist/scaffold/templates/fastagent.config.mjs

@@ -0,0 +1,19 @@
+// fastagent.config.mjs — deployment choices only (model / http; code tools auto-discover from tools/).
+// Your agent's identity lives in persona.md; its capabilities in skills/ + tools/ — never here.
+// An AGENTS.md at the workspace root (yours or the host repo's) is read as project context.
+// Model precedence: `--model` flag > FASTAGENT_MODEL env > this default.
+// No model is preset: `fastagent dev` prompts you to pick one from the providers you're logged into
+// (run `fastagent login` first) and writes your choice below. Or set it by hand to a "provider/modelId"
+// you have access to (`fastagent models` lists them).
+export default {
+  // model: "openai-codex/gpt-5.5",
+  http: { port: 8787 },
+  // selfSchedule: true, // mount the built-in `wake` tool: the agent schedules its own follow-up turns
+  //                     // ("check the deploy in 10 min"). Cron jobs need no opt-in — drop a schedules/<name>.ts.
+  // deploy: what the agent needs on the box (so `fastagent deploy` doesn't need a hand-written Dockerfile
+  // or hand-set host variables). Uncomment as needed:
+  // deploy: {
+  //   secrets: ["GH_TOKEN"], // extra secret env vars your tools use — deploy carries them from your local env
+  //   apt: ["git"],          // extra apt packages baked into the image (git, ripgrep, …; default repos only)
+  // },
+};

package/dist/scaffold/templates/gitignore

@@ -0,0 +1,8 @@
+# secrets — never commit (kept out of git and any deploy copy)
+.env
+
+# dependencies (reinstalled at deploy)
+node_modules/
+
+# fastagent machine state (dev/start sessions + project-level auth.json credentials)
+.fastagent/

package/dist/scaffold/templates/gitignore.agentdir-root

@@ -0,0 +1,5 @@
+# secrets — never commit (kept out of git and any deploy copy)
+.env
+
+# fastagent machine state (dev/start sessions + project-level auth.json credentials)
+.fastagent/

package/dist/scaffold/templates/gitignore.kit

@@ -0,0 +1,2 @@
+# dependencies (reinstalled at deploy)
+node_modules/

package/dist/scaffold/templates/persona.md

@@ -0,0 +1,10 @@
+# Persona
+
+You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart. Your `read` / `write` / `edit` / `bash` tools operate at the workspace root you were started in; if the workspace has an `AGENTS.md`, it is project context — read it to learn the project's conventions.
+
+You can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
+
+- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
+- A standing instruction or fact → edit this file.
+
+Keep both lean: include only what changes your behavior, and delete what no longer earns its place.

package/dist/scaffold/templates/skills/writing-great-skills/GLOSSARY.md

@@ -0,0 +1,195 @@
+# Glossary — Building Great Skills
+
+The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md).
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

package/dist/scaffold/templates/skills/writing-great-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.