@sous-io/sous 0.1.0 → 0.2.0

package/docs/markdown/repositories.md

@@ -0,0 +1,303 @@
+# Repositories
+
+A **repository** publishes shared agent configuration that any project can subscribe to. It is
+an ordinary git repository holding a few manifest files and some markdown, and sous reads it
+the way a package manager reads a registry: an index says what exists, a project says what it
+wants, and a lockfile records exactly what it got.
+
+This page explains the model and the guarantees. The task-oriented guides are
+[Consuming recipes](repositories-consuming.md) and
+[Authoring a repository](repositories-authoring.md), and every file schema lives in
+[Repository file formats](repositories-file-formats.md).
+
+## Repositories, namespaces, recipes
+
+Three nouns carry the whole system.
+
+- A **repository** is the unit of trust and the unit of distribution. You add one to a project,
+  which is also how you trust it, and everything else flows from that.
+- A **namespace** groups related recipes inside a repository. It is a plain name, it is not
+  versioned, and a project can subscribe to a whole namespace at once.
+- A **recipe** is the unit you subscribe to and the unit that carries a version. It may hold
+  skills, memories, prompts, config layers, variable definitions, or any mixture of them.
+  Subscribing to a recipe gets everything in it.
+
+```text
+repository            github.com/sous-io/sous-recipes
+  namespace           workflow
+    recipe            task-files          1.2.0
+    recipe            github-projects     1.0.0
+  namespace           communication
+    recipe            control-flow        1.0.0
+```
+
+A recipe is named by a **ref**: `workflow` for a whole namespace, `workflow/task-files` for one
+recipe, `workflow/task-files@^1.2.0` to constrain the version, and
+`sous-recipes:workflow/task-files` when two added repositories publish the same ref and sous
+needs to be told which one you meant. Refs resolve across the cached indexes of every repository
+the project has added; a genuine conflict is an error asking for the qualified form, never a
+silent first match. The full grammar is in
+[Refs: how anything is named](repositories-file-formats.md#refs-how-anything-is-named).
+
+A ref of one word is a guess at a name, and sous works out what it meant: it looks for a
+namespace with that name first, and for a recipe with that name second, across every repository
+the project trusts. One match is used and reported by its full ref; several are a question. See
+[Subscribe to a recipe](repositories-consuming.md#subscribe-to-a-recipe).
+
+## Trust
+
+Adding a repository **is** trusting it. There is no separate trust command, no trusted-but-not-
+added state, and no way to look inside a repository before deciding: until a repository is added,
+sous downloads nothing from it, not even its index. That is deliberate. A trust decision made
+by browsing content sous fetched from an untrusted source is not really a trust decision; the
+decision rests on the URL and on who publishes it, and both of those are things you inspect
+outside sous. Trusting a repository trusts every namespace and every recipe in it, including
+recipes published later. Trusting alone executes nothing, but subscribing to something inside a
+trusted repository can and probably will run scripts on your machine, so the trust question is
+the last gate before that happens. Sous cannot tell you whether a repository deserves trust,
+and it says so rather than implying otherwise.
+
+`sous repo add` asks that question inline, with that wording. Resolution can also turn up a
+repository a recipe depends on that your project has not added; those are asked about in one
+consolidated question per round, each shown with its URL and the recipe that requires it. Any
+refusal aborts the whole install, because sous installs a dependency closure whole or not at all.
+
+```term
+$ sous repo add https://github.com/sous-io/sous-recipes
+// sous prints the repository, its location and what trusting it means
+Do you trust this repository? (y/N)
+```
+
+Where there is no terminal to ask on, such as continuous integration, the run fails and names
+both the repositories and the exact command that grants the trust. `--trust` acknowledges
+without being asked, and is the flag a script uses; it is one spelling of the shared
+confirmation flag, alongside `-y`, `--yes`, `-f` and `--force`:
+
+```bash
+sous repo add https://github.com/sous-io/sous-recipes --trust
+```
+
+Trust is project-level and lives in your project's config, so a colleague who clones the project
+inherits it along with everything else. Trust plus the lockfile is the supply-chain defense:
+nothing new enters a project except through an explicit, visible change to files under version
+control.
+
+!> Trust semantics do not soften for a repository that is already on your disk. A local path
+added through the `local` provider goes through the same ceremony, because its recipes still run
+on this machine.
+
+## The official repository, and `core`
+
+Sous publishes one official repository, [`sous-io/sous-recipes`](https://github.com/sous-io/sous-recipes).
+Its namespaces are drawn from the canonical [skill categories](skill-categories.md), plus one
+extra namespace called `core`.
+
+`core` is the exception to everything else on this page. It holds the skills that teach an agent
+what sous is, why generated files must not be edited by hand, and where the source of a managed
+file lives; without them an agent will cheerfully edit a compiled `CLAUDE.md` and wonder why the
+change keeps disappearing. So `core` is auto-subscribed in every project, at the version that
+matches the sous CLI you are running, and its source ships inside the sous package itself and
+seeds the machine-wide store on first run. A fresh install therefore works with no network at
+all, and the release pipeline pushes the same content to the official repository under the same
+version number, so the built-in copy and the published copy are the same bytes.
+
+Both wirings are ordinary config entries, and both can be switched off:
+
+```yaml
+subscriptions:
+  core:
+    enabled: false
+```
+
+Everything else in the official repository is opt-in, one `sous subscription add` at a time, and
+`sous subscription remove core` records that opt-out for you.
+
+?> Namespace subscriptions are a first-class feature and are worth reaching for on other
+repositories, especially a team repository whose namespace is genuinely one coherent set. In the
+official repository they are not what you want: any arrangement of its content yields either
+one-recipe namespaces or a namespace of unrelated recipes, so subscribe to official recipes one
+at a time. `core` is the deliberate exception.
+
+## `depends` versus `subscribes`
+
+A recipe manifest can declare two different relationships to other recipes, and the difference
+is exactly one thing: whose files end up in your project.
+
+| Relationship | Fetched and pinned | Trust-gated | Addressable from the declaring recipe | Files enter your project |
+|--------------|--------------------|-------------|---------------------------------------|--------------------------|
+| `depends` | yes | yes | yes | no |
+| `subscribes` | yes | yes | yes | yes |
+
+`depends` is a build dependency: shared partials, shared variable definitions, anything a recipe
+reads while rendering its own files. `subscribes` is a co-subscription: subscribing to the recipe
+subscribes your project to the listed targets with full semantics, so their questions run and
+their files land in your output. A curated bundle is simply a recipe made mostly of `subscribes`
+entries; there is no special bundle type.
+
+Both name their targets by LOCATION. A recipe in the same repository is a bare ref
+(`workflow/sat`); a recipe in another repository is a locator URL whose scheme is the provider
+(`github://sous-io/sous-recipes/workflow/sat@^1.1`), whose last two path segments are always the
+namespace and the recipe. A project's own short name for a repository never appears in a
+published manifest, because it is a label that project chose. The full grammar is in
+[Repository file formats](repositories-file-formats.md#dependencies-named-by-location).
+
+A release records what each version was published against, so installing a version installs the
+versions it was released with rather than whatever its ranges reach today.
+
+Both are declarative, and that is load-bearing rather than stylistic. Because the entire
+dependency closure is readable from manifests alone, sous can show you every repository an
+install would reach before it fetches any of them. Configuration that could subscribe by running
+code would break that, which is why manifests are YAML or JSON and never JavaScript.
+
+Removal is refcounted. Unsubscribing removes what that subscription alone brought in and leaves
+anything another subscription or another recipe still holds, and says which of those holders
+kept it.
+
+## The lockfile
+
+`.sous/sous.lock.json` records the exact version and content hash of everything the project uses,
+along with who holds each entry. It is committed. A fresh clone with no store on the machine
+rebuilds precisely what the lockfile describes, fetching those versions and no others, and asking
+nothing:
+
+```term
+$ git clone git@github.com:my-team/my-project.git
+>> 100%
+$ sous build
+Restoring recipes
+  This project's lockfile pins recipes that are not in the store on this machine,
+  so they are being fetched at exactly the versions it records.
+  restored: workflow/task-files
+```
+
+Restore decides nothing. It never resolves a range, never picks a newer version, and never
+prompts. Anything that would change what is installed changes the lockfile first, as a diff you
+can read in review.
+
+## Providers
+
+A provider is everything sous knows about one kind of repository host, and it is the only place
+a host-specific fact is allowed to live. Sous ships three: `github`, `gitlab` and `local`.
+
+A provider has two sides:
+
+- **The read side**, which every provider answers: recognize a repository URL, take it apart into
+  host, owner and name, hand back the repository's `sous.index.json`, and fetch one recipe's
+  subtree at one tag. Nothing here clones a whole repository.
+- **The write side**, which only a provider that can propose a change answers: report whether its
+  command line tool is installed and signed in, say whether you can push to the repository
+  itself, fork it onto your account, and open the proposal. Each call answers with plain data, so
+  the command driving it never learns what tool ran.
+
+Each provider declares the features it really has, `fetch` and `submit`, and sous consults that
+list rather than a provider's name. `local` declares `fetch` only: a repository on your own disk
+is edited directly, so asking sous to propose a change to it is refused with a message naming the
+provider and the feature. A provider that supports a feature only partly says so plainly rather
+than guessing; GitLab, for instance, reports that it cannot tell whether you may push instead of
+sending you down a fork path it cannot finish.
+
+?> Adding a provider is one file. A class extending `ProviderBase` inherits the subprocess, token
+and refusal plumbing, implements the read path, declares its features, and overrides the write
+calls it supports; adding it to the built-in list is the only other change. The interface is
+internal for now, not a published plugin API.
+
+## Where everything lives
+
+| Location | Holds | Committed |
+|----------|-------|-----------|
+| `.sous/sous.lock.json` | the exact versions and hashes in use | yes |
+| `.sous/conf.d/500-repos.jsonc` | the repositories the project trusts | yes |
+| `.sous/conf.d/510-subscriptions.jsonc` | what the project subscribes to | yes |
+| `.sous/conf.d/520-var-mappings.jsonc` | environment variable mapping records | yes |
+| `.sous/sous.links.json` | this project's linked working copies | no |
+| `.sous/repos/` | working copies cloned by `sous repo link` | no |
+| `~/.sous/cache/` | the machine-wide recipe store | not in a project at all |
+| `~/.sous/repos/` | working copies linked with `--global` | not in a project at all |
+| `~/.sous/sous.links.json` | the machine-wide links map | not in a project at all |
+
+The user-level directory is `~/.sous`, and `SOUS_HOME` moves it. Unlike `SOUS_CONFIG` and
+`SOUS_DIR`, `SOUS_HOME` does not decide which project is active, so it may be set in
+`.sous/.env.local` or `.sous/.env` as well as in the shell.
+
+The three files in the `500` to `599` band are written by sous, and the band exists precisely so
+that machine-written layers never collide with the config you wrote. Sous edits them by key, so
+your comments, your key order and your formatting survive a write, and you may edit them
+yourself. Sous never edits your primary config. You may
+hand-write `repos:`, `subscriptions:` and `varMappings:` there yourself, and by the time anything
+reads them the two are one merged map. See
+[Managed config layers](repositories-file-formats.md#managed-config-layers).
+
+Every directory sous creates for its own bookkeeping explains itself. The first time sous
+creates one (`.sous/conf.d/`, `.sous/repos/`, `~/.sous` and everything under it), it writes a
+short `README.md` there saying what the directory is, who writes to it, whether you may edit or
+delete what is inside, and whether it is committed, plus an `AGENTS.md` and a `CLAUDE.md` holding
+one line each pointing at that README. None of the three is ever overwritten, so anything you
+write in them stays. Directories that hold rendered output are deliberately left alone: what
+lands there is yours.
+
+The store is disposable by design. Every entry in it is re-fetchable from the pins in some
+project's lockfile, so deleting `~/.sous/cache` costs a download and nothing else. `sous repo gc`
+collects it back to a size cap, least recently used first, and never evicts an entry this
+project's lockfile still pins.
+
+## Including recipe files in your own templates
+
+A recipe's files are addressable from a template through the reserved `~` include sigil:
+
+```markdown
+@~workflow/task-files/_partials/shared.md
+```
+
+The `~` is required. A bare `@path` in an include is always a relative path or a declared alias,
+with no namespace fallback, so an include line can never quietly stop meaning a file on disk and
+start meaning a recipe. Inside a recipe's own files, `~<namespace>` resolves against that
+recipe's declared dependencies at their pinned versions; in your project's templates it resolves
+against your project's subscriptions.
+
+A `~namespace` reference addresses a recipe's own files and nothing else, so the path after the
+recipe name may not contain `.` or `..` segments and may not be absolute. One that tries to leave
+the recipe directory is refused with an error saying so, exactly as every other path sous reads
+refuses `..`.
+
+## Freshness, always-pull, and links
+
+By default a build uses what the lockfile pins and does not talk to the network. Two things
+change that.
+
+**Always-pull** installs a newer in-range version whenever one exists, rather than holding the
+locked one. It is set per repository or per subscription, or asked for once with
+`sous subscription add --always-pull`. It never widens the range a subscription or a dependency
+declared; it re-resolves within it. The lockfile is still regenerated every time, so it always
+records what the last build actually used, and a project using always-pull simply accepts
+routine lockfile diffs as the record of what changed.
+
+**The freshness window** decides how often sous bothers to look upstream at all: five minutes by
+default, configurable as `store.freshnessSeconds`, with `store.watchPollSeconds` doing the same
+job for watch mode. A check that fails never breaks a build. The last good index stands, the
+build says what happened, and it carries on.
+
+A **linked** repository sits outside all of this. `sous repo link` points one repository's
+resolution at a working copy on your machine, which is how a maintainer edits recipes; edits
+happen in a checkout, never in the store. A link bypasses versions, the lockfile and freshness
+checks, and those bypasses belong to one person's machine rather than to the team, so every
+build announces a linked repository loudly:
+
+```text
+One repository is LINKED to a working copy on this machine.
+Their recipes are read from those checkouts, so versions, the lockfile and
+freshness checks do not apply to them.
+```
+
+## Where to go next
+
+- [Consuming recipes](repositories-consuming.md): adding, subscribing, building, and what lands
+  where
+- [Authoring a repository](repositories-authoring.md): `sous repo init`, writing recipes,
+  releasing, and contributing
+- [Recipe variables](repositories-variables.md): the resolution ladder, answers, and the
+  `sous vars` commands
+- [Repository file formats](repositories-file-formats.md): every manifest, index and lockfile
+  schema
+- [Skill categories](skill-categories.md): the canonical category list the official repository
+  uses as namespaces
+- [Command reference](commands.md): every command and flag

package/docs/markdown/skill-categories.md

@@ -0,0 +1,58 @@
+# Skill Categories
+
+Sous keeps one canonical list of skill categories. It is a small, closed vocabulary: it exists so
+that a skill has an obvious home, so that two people filing similar skills reach for the same
+word, and so that a reader scanning a repository can tell what is in it without opening
+anything.
+
+| Category | What belongs in it |
+|----------|--------------------|
+| `reasoning` | How an agent thinks through a problem: decomposition, self-checking, weighing evidence, knowing when it is stuck |
+| `planning` | Turning an intent into an ordered plan, and keeping that plan current as the work moves |
+| `architecture` | Designing systems and deciding structure: boundaries, dependencies, trade-offs, and how a decision gets recorded |
+| `coding` | Writing and changing code: idioms, refactoring, language and framework practice |
+| `data-manipulation` | Reading, transforming, querying and reshaping data, in files, databases or streams |
+| `research` | Finding things out: searching a codebase, reading documentation, gathering evidence before acting |
+| `tool-usage` | Driving a specific tool well: a CLI, a browser, an API, a service that has its own rules |
+| `workflow` | The shape of the work itself: tickets, branches, task files, reviews, handoffs between sessions |
+| `quality` | Confidence in what was built: tests, linting, review practice, and the standards being upheld |
+| `communication` | How an agent talks: writing standards, interaction patterns, asking, reporting, disagreeing usefully |
+| `operations` | Running things: builds, releases, deployment, environments, monitoring, recovery |
+| `security` | Protecting the system and the people using it: secrets, permissions, supply chain, threat awareness |
+
+## Adding a category is a decision
+
+The list above is the whole list. It is deliberately comprehensive rather than deliberately
+small, so that in practice a new skill fits an existing category, and the answer to "which one?"
+is a judgment call about the skill rather than an invitation to invent a thirteenth word.
+
+Adding a category is a considered change to a shared vocabulary, never an ad hoc choice made
+while filing one skill. A category that gets added because one skill did not obviously fit tends
+to attract nothing else, and the list stops being useful the moment it stops being small. If a
+skill genuinely resists every category above, that is worth discussing as a gap in the
+vocabulary, on its own, before anything is filed.
+
+## Categories as namespaces
+
+The official repository, [`sous-io/sous-recipes`](https://github.com/sous-io/sous-recipes), uses
+this list directly: a namespace in that repository is a category from the table above, plus one
+extra namespace, `core`, which holds the recipes that teach an agent about sous itself. `core` is
+not a skill category. It is a distribution concern, and it exists because those recipes are
+auto-subscribed in every project rather than chosen from a catalog.
+
+Your own repository is under no obligation to use these names. Namespaces are just names, and a
+team repository whose namespaces are its own product areas is a perfectly good repository. The
+list is worth borrowing when what you publish is general-purpose skills that other people will
+browse, because a shared vocabulary is what makes browsing work.
+
+?> A namespace subscription gets every recipe in the namespace, including recipes published
+later, which is exactly what you want from a coherent category and exactly what you do not want
+from a grab bag. That is the practical reason to keep a namespace meaning one thing. See
+[Consuming recipes](repositories-consuming.md).
+
+## Where to go next
+
+- [Repositories](repositories.md): the model, and how namespaces fit into it
+- [Authoring a repository](repositories-authoring.md): declaring namespaces and filing recipes
+  under them
+- [Design principles](design-principles.md): the constraints these choices answer to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,52 +27,116 @@
     "access": "public"
   },
   "bin": {
-    "xcv": "./bin/run.js"
+    "sous": "./bin/run.js"
   },
   "files": [
-    "bin",
+    "bin/run.js",
     "src",
     "!src/**/*.spec.ts",
     "!src/test",
-    "shared-prompts"
+    "recipes",
+    "docs/markdown/*.md",
+    "sous.config.schema.json"
   ],
   "scripts": {
     "build": "tsc",
-    "sous:build": "./bin/xcv build --rebuild",
-    "claude": "./bin/xcv launch claude",
+    "sous:build": "./bin/sous build --rebuild",
+    "claude": "./bin/sous launch claude",
     "clean": "rm -rf dist",
+    "schema:build": "tsx scripts/build-schema.mts",
+    "version:sync": "tsx scripts/sync-core-version.mts",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts"
   },
   "dependencies": {
+    "@inquirer/core": "^11.1.7",
     "@inquirer/prompts": "^8.3.2",
     "@oclif/color": "^1.0.13",
     "@oclif/core": "^4",
     "chokidar": "^5.0.0",
     "glob": "^13.0.6",
+    "jsonc-parser": "^3.3.1",
     "liquidjs": "^10.25.0",
     "minimatch": "^10.2.4",
+    "semver": "^7.8.5",
     "tiktoken": "^1.0.22",
-    "tsx": "^4"
+    "tsx": "^4",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/glob": "^8.1.0",
     "@types/node": "^22",
+    "@types/semver": "^7.8.0",
     "@vitest/coverage-v8": "^4.1.0",
     "memfs": "^4.56.11",
     "typescript": "^5",
     "vitest": "^4.1.0"
   },
   "oclif": {
-    "bin": "xcv",
-    "dirname": "xcv",
+    "bin": "sous",
+    "dirname": "sous",
     "flexibleTaxonomy": true,
     "topicSeparator": " ",
+    "additionalHelpFlags": [
+      "-h"
+    ],
     "commands": {
       "strategy": "pattern",
       "target": "./src/commands"
+    },
+    "topics": {
+      "config": {
+        "description": "Inspect the merged configuration"
+      },
+      "configs": {
+        "description": "Inspect the merged configuration",
+        "hidden": true
+      },
+      "repo": {
+        "description": "Manage the recipe repositories this project trusts"
+      },
+      "repos": {
+        "description": "Manage the recipe repositories this project trusts",
+        "hidden": true
+      },
+      "lock": {
+        "description": "Inspect and repair this project's lockfile"
+      },
+      "locks": {
+        "description": "Inspect and repair this project's lockfile",
+        "hidden": true
+      },
+      "namespace": {
+        "description": "Browse the namespaces the trusted repositories publish"
+      },
+      "namespaces": {
+        "description": "Browse the namespaces the trusted repositories publish",
+        "hidden": true
+      },
+      "recipe": {
+        "description": "Browse the recipes the trusted repositories publish"
+      },
+      "recipes": {
+        "description": "Browse the recipes the trusted repositories publish",
+        "hidden": true
+      },
+      "subscription": {
+        "description": "Manage which recipes this project subscribes to"
+      },
+      "subscriptions": {
+        "description": "Manage which recipes this project subscribes to",
+        "hidden": true
+      },
+      "vars": {
+        "description": "Recipe variables and their answers"
+      },
+      "var": {
+        "description": "Recipe variables and their answers",
+        "hidden": true
+      }
     }
   },
   "engines": {

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/SKILL.tpl.md

@@ -10,12 +10,12 @@ user-invocable: false
 # About Agent Skills
 
 A skill is a directory containing a `SKILL.md` file and optional supporting files.
-Skills extend what a coding agent can do — invoke them directly with `/skill-name`,
+Skills extend what a coding agent can do; invoke them directly with `/skill-name`,
 or they load automatically when the agent's decision logic matches the `description`.
 
 ## Where Skills Live
 
-Skills for this project live at `{{ skillsRoot }}`. Create and edit skills there —
+Skills for this project live at `{{ skillsRoot }}`. Create and edit skills there,
 never in `.claude/skills/` or `.codex/skills/` directly. See `create-skill` for
 step-by-step instructions.
 
@@ -29,7 +29,7 @@ my-skill/
 └── scripts/        # Optional. Executable scripts.
 ```
 
-Supporting files must be referenced from `SKILL.md` — the agent will not know they
+Supporting files must be referenced from `SKILL.md`; the agent will not know they
 exist otherwise. Keep `SKILL.md` under ~500 lines; move detailed reference material
 to `references/` files.
 
@@ -46,17 +46,17 @@ user-invocable: false
 ---
 ```
 
-**`name`** — becomes the `/slash-command`. Defaults to the directory name if omitted.
+**`name`**: becomes the `/slash-command`. Defaults to the directory name if omitted.
 
-**`description`** — tells the agent when to invoke this skill. Use strong trigger
+**`description`**: tells the agent when to invoke this skill. Use strong trigger
 language: open with "YOU MUST load this skill when...". Under 500 chars.
 
-**`disable-model-invocation`** — set `true` to prevent the agent from invoking the
+**`disable-model-invocation`**: set `true` to prevent the agent from invoking the
 skill automatically. Use this for command skills that represent intentional,
 user-initiated actions (e.g. `/commit`, `/deploy`). If it makes sense for the agent
 to invoke the skill on the user's behalf, omit it.
 
-**`user-invocable`** — set `false` to hide the skill from the `/` menu. Use this on
+**`user-invocable`**: set `false` to hide the skill from the `/` menu. Use this on
 all topic skills (`about-*`). They are reference material the agent loads
 automatically, not commands for the user to invoke.
 
@@ -69,14 +69,14 @@ shared scripts the action skills draw from. They are moderately descriptive and
 across many workflows. Always set `user-invocable: false`. Use the `about-*` prefix when
 the skill's primary purpose is background understanding.
 
-A topic skill's body holds fundamental knowledge — what is needed in ~75%+ of use cases.
+A topic skill's body holds fundamental knowledge: what is needed in ~75%+ of use cases.
 Deeper reference material (complete tables, edge cases, advanced patterns) goes in
 `references/` files, loaded only when needed. When official documentation exists for the
 topic, fetch it once and store distilled versions in `references/`, including the official
 source URL so the agent can check anything not covered locally. This prevents repeated doc
 fetches during work sessions.
 
-**Action skills** perform a specific operation and are as thin as possible — they
+**Action skills** perform a specific operation and are as thin as possible; they
 contain only what is exclusive to that action. All shared knowledge belongs in the
 parent topic skill. Action skills carry less cold-start context than topic skills: just
 enough to not be opaque, then delegate depth upward with `YOU MUST load`. Name action
@@ -85,7 +85,7 @@ specific type, include it after the verb (e.g. `create-skill` operates on a "ski
 The verb-first pattern immediately distinguishes action skills from topic skills in any
 skill listing.
 
-Non-command action skills must NOT have `disable-model-invocation: true` — that flag
+Non-command action skills must NOT have `disable-model-invocation: true`; that flag
 removes the skill from the agent's context entirely, making it undiscoverable. A
 non-command action skill relies on its description to tell the agent when to invoke it
 automatically; omitting the flag is what makes that possible.
@@ -102,7 +102,7 @@ directory needs `.tpl.` naming or when writing LiquidJS syntax.
 ## General Principles
 
 **Knowledge lives at the highest common ancestor.** If two skills need the same
-knowledge, it belongs in the most general topic skill covering both — never
+knowledge, it belongs in the most general topic skill covering both, never
 duplicated across skills. Before adding content anywhere, ask whether it belongs
 higher up.
 
@@ -117,7 +117,7 @@ directory). Teach the agent where to look rather than providing a snapshot that
 stale. Only document things stable by nature.
 
 **Use strong trigger language.** Descriptions must open with `YOU MUST load this
-skill when...`. Cross-references to other skills must use `YOU MUST load` — weak
+skill when...`. Cross-references to other skills must use `YOU MUST load`; weak
 language like "consult" or "see" is not sufficient. In a skill body, write the
 requirement so it binds whichever agent executes ("The agent performing this work MUST
 load `x`"), not just the main session: delegated sub-agents start with fresh context and
@@ -135,8 +135,8 @@ that warrants its own skill.
 
 ## Template-Compiled Skills
 
-Every skill distributed from a shared library — whether this library (`sous`) or any other
-shared skill library — must use `SKILL.tpl.md`, not `SKILL.md`. This is required because
+Every skill distributed from a shared library, whether this library (`sous`) or any other
+shared skill library, must use `SKILL.tpl.md`, not `SKILL.md`. This is required because
 every distributed skill must end with a `## Source for this Skill` section (see below), and
 that section uses a template variable for the source path, which requires LiquidJS rendering.
 No exceptions.
@@ -159,15 +159,15 @@ compile time.
 
 ## Examples
 
-- [examples/about-something.md](examples/about-something.md) — a complete example of a topic (`about-*`) skill
-- [examples/do-something.md](examples/do-something.md) — a complete example of an action skill (command)
+- [examples/about-something.md](examples/about-something.md): a complete example of a topic (`about-*`) skill
+- [examples/do-something.md](examples/do-something.md): a complete example of an action skill (command)
 
 ## Reference Files
 
-- [frontmatter.md](references/frontmatter.md) — complete frontmatter field table and invocation matrix
-- [substitutions.md](references/substitutions.md) — `$ARGUMENTS`, `$ARGUMENTS[N]`, `$CLAUDE_SESSION_ID`, `$CLAUDE_SKILL_DIR`
-- [commands.md](references/commands.md) — command-specific conventions: descriptions, headings, arguments, `argument-hint`
-- [advanced-patterns.md](references/advanced-patterns.md) — dynamic context injection, subagent execution (`context: fork`), `allowed-tools`
+- [frontmatter.md](references/frontmatter.md): complete frontmatter field table and invocation matrix
+- [substitutions.md](references/substitutions.md): `$ARGUMENTS`, `$ARGUMENTS[N]`, `$CLAUDE_SESSION_ID`, `$CLAUDE_SKILL_DIR`
+- [commands.md](references/commands.md): command-specific conventions: descriptions, headings, arguments, `argument-hint`
+- [advanced-patterns.md](references/advanced-patterns.md): dynamic context injection, subagent execution (`context: fork`), `allowed-tools`
 
 ## Source for this Skill
 

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/examples/about-something.md

@@ -25,9 +25,9 @@ has its own configuration file under `deploy/config/`.
 
 ## Reference Files
 
-- [references/environments.md](references/environments.md) — per-environment config
+- [references/environments.md](references/environments.md): per-environment config
   options, required env vars, and access requirements
-- [references/rollback.md](references/rollback.md) — rollback procedures and known
+- [references/rollback.md](references/rollback.md): rollback procedures and known
   failure modes
 
 # Other Skills

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/examples/do-something.md

@@ -4,7 +4,7 @@
 ---
 name: deploy
 description: >
-  YOU MUST use this skill when deploying the application. Do not use for rollbacks —
+  YOU MUST use this skill when deploying the application. Do not use for rollbacks;
   those follow a different process.
 disable-model-invocation: true
 ---