@sous-io/sous 0.1.0

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/utils.mjs

@@ -0,0 +1,185 @@
+/**
+ * ctx.utils — generic, site-agnostic helpers for automation scripts.
+ *
+ * These are the patterns proven during the POC, promoted out of any single
+ * script. Site-specific logic (dismissing a particular app's modals, parsing a
+ * particular tool's output) stays in the script as step functions.
+ *
+ * Built per-run and bound to the live `page`/`logger`, so scripts call them as
+ * `ctx.utils.foo(...)` without threading `page` through every call.
+ */
+
+/**
+ * Build the utils object for a run.
+ *
+ * @param {import('playwright').Page} page
+ * @param {object} logger - The script's logger (a child is created per helper)
+ * @returns {object} the ctx.utils surface
+ */
+export function createUtils(page, logger) {
+  const log = logger.child('utils');
+
+  return {
+    /**
+     * RECOMMENDED way to handle modals/banners that appear at an unpredictable
+     * time and would block later actions. Registers a Playwright locator handler:
+     * whenever `triggerLocator` is present and blocks an action, `dismiss` runs.
+     * This is fully timing-independent — no sleeps, no races. Prefer this over
+     * `dismissModals` for anything that may appear asynchronously.
+     *
+     * @param {import('playwright').Locator} triggerLocator - The modal/overlay.
+     * @param {(locator) => Promise<void>} dismiss - How to dismiss it.
+     * @returns {Promise<void>}
+     */
+    async autoDismiss(triggerLocator, dismiss) {
+      await page.addLocatorHandler(triggerLocator, dismiss);
+      log.info('registered auto-dismiss handler');
+    },
+
+    /**
+     * Best-effort one-shot dismissal of modals KNOWN to already be present. Clicks
+     * the first of each candidate selector that currently exists; failures are
+     * swallowed. Does NOT wait for modals that may appear later — use
+     * `autoDismiss` for those. No fixed delays.
+     *
+     * @param {string[]} selectors
+     * @param {object} [opts] - { timeout }
+     * @returns {Promise<number>} count of elements clicked
+     */
+    async dismissModals(selectors, opts = {}) {
+      const { timeout = 2000 } = opts;
+      let dismissed = 0;
+      for (const sel of selectors) {
+        const el = await page.$(sel);
+        if (!el) continue;
+        try {
+          await el.click({ timeout });
+          dismissed++;
+        } catch {
+          // best-effort; modal may have already closed or be non-actionable
+        }
+      }
+      if (dismissed) log.info(`dismissed ${dismissed} modal element(s)`);
+      return dismissed;
+    },
+
+    /**
+     * Click an element located by visible text (regex or string). Defaults to a
+     * NON-forced click so Playwright auto-waits for the element to be actionable
+     * (visible, stable, not covered) — the resilient default. Pass `force: true`
+     * only for the rare element a component library (e.g. Blueprint.js) wrongly
+     * reports as disabled, and verify the outcome afterward.
+     *
+     * @param {RegExp|string} text
+     * @param {object} [opts] - { force, timeout }
+     */
+    async clickByText(text, opts = {}) {
+      const { force = false, timeout = 15000 } = opts;
+      const locator = page.getByText(text).first();
+      await locator.waitFor({ timeout });
+      await locator.click({ force });
+    },
+
+    /**
+     * Wait for any element matching `text` (regex or string) to appear, without
+     * clicking. Useful for asserting a list/view has rendered.
+     *
+     * @param {RegExp|string} text
+     * @param {object} [opts] - { timeout }
+     */
+    async waitForText(text, opts = {}) {
+      const { timeout = 15000 } = opts;
+      await page.getByText(text).first().waitFor({ timeout });
+    },
+
+    /**
+     * Try each selector in order; return the longest text content found among
+     * all matches, or null if nothing exceeds `minLength`. Built for "find the
+     * log/output blob on the page" cases where the exact container is unknown.
+     *
+     * @param {string[]} selectors
+     * @param {object} [opts] - { minLength }
+     * @returns {Promise<string|null>}
+     */
+    async extractLongestText(selectors, opts = {}) {
+      const { minLength = 50 } = opts;
+      for (const sel of selectors) {
+        const els = await page.$$(sel);
+        if (!els.length) continue;
+        const texts = await Promise.all(els.map((el) => el.textContent()));
+        const longest = texts
+          .filter(Boolean)
+          .map((t) => t.trim())
+          .sort((a, b) => b.length - a.length)[0];
+        if (longest && longest.length >= minLength) return longest;
+      }
+      return null;
+    },
+
+    /**
+     * Extract the first match of a regex from page text (or supplied text).
+     * Returns the trimmed match string, or null.
+     *
+     * @param {RegExp} pattern
+     * @param {object} [opts] - { source: string, group: number }
+     * @returns {Promise<string|null>}
+     */
+    async extractTextByPattern(pattern, opts = {}) {
+      const { source = null, group = 0 } = opts;
+      const haystack = source ?? (await page.textContent('body')) ?? '';
+      const m = haystack.match(pattern);
+      return m ? m[group].trim() : null;
+    },
+
+    /**
+     * Capture a screenshot for debugging. No-op-safe: failures are logged, not
+     * thrown, so a debug aid never breaks a run.
+     *
+     * @param {string} path - Absolute file path for the PNG
+     * @param {object} [opts] - { fullPage }
+     */
+    async screenshot(path, opts = {}) {
+      const { fullPage = true } = opts;
+      try {
+        await page.screenshot({ path, fullPage });
+        log.info(`screenshot saved: ${path}`);
+      } catch (err) {
+        log.warn(`screenshot failed: ${err.message}`);
+      }
+    },
+
+    /**
+     * Scroll an element matching `selector` into view. Returns true if found.
+     *
+     * @param {string} selector
+     */
+    async scrollIntoView(selector) {
+      const el = await page.$(selector);
+      if (!el) return false;
+      await el.scrollIntoViewIfNeeded().catch(() => {});
+      return true;
+    },
+
+    /**
+     * Retry an async function until it succeeds or attempts are exhausted.
+     * Throws the last error on final failure.
+     *
+     * @param {Function} fn - async () => result
+     * @param {object} [opts] - { attempts, delay, label }
+     */
+    async retry(fn, opts = {}) {
+      const { attempts = 3, delay = 1000, label = 'operation' } = opts;
+      let lastErr;
+      for (let i = 1; i <= attempts; i++) {
+        try {
+          return await fn();
+        } catch (err) {
+          lastErr = err;
+          log.warn(`${label} failed (attempt ${i}/${attempts}): ${err.message}`);
+          if (i < attempts) await page.waitForTimeout(delay);
+        }
+      }
+      throw lastErr;
+    },
+  };
+}

package/shared-prompts/skills/automated-browser-tasks/create-automated-browser-task/SKILL.tpl.md

@@ -0,0 +1,52 @@
+---
+name: create-automated-browser-task
+description: >
+  YOU MUST load this skill when you need to create a new headless browser
+  automation script — i.e. a browser task is required and no existing script
+  performs it. Produces a convention-compliant script in the project's
+  automation scripts directory.
+---
+
+# Create an Automated Browser Task
+
+A thin action skill. The architecture, `ctx` API, and full conventions live in
+the parent topic skill; the agent performing this work MUST load
+`about-automated-browser-tasks`.
+
+## Delegation
+
+Per the sub-agent delegation pattern
+(`~sous-shared/_partials/sub-agent-delegation.md`), writing and iterating on a script is
+delegated work: one Opus sub-agent writes it, runs it, and iterates against the
+real page until it works, then reports the script path and result. Give it the
+target URL, the data to extract, and the params wanted.
+
+## Steps
+
+1. **Confirm none exists.** Search the project's automation scripts directory for
+   a script that already does this. If one is close, prefer
+   `update-automated-browser-task` instead.
+2. **Name the file** `verb-noun-qualifier.mjs` (e.g. `get-repo-ci-error.mjs`).
+3. **Declare `meta`** — `name`, a descriptive `description`, and `params`. For each
+   param set `required`, `default`, a genuinely descriptive `description`, and a
+   `validate` rule (RegExp or function) with an `invalidMessage`. Pull shared
+   values (URLs, resource IDs, profile) from `ctx.settings` rather than hardcoding.
+4. **Write `execute(ctx)`** as a thin orchestrator that calls small, named step
+   functions. Destructure off `ctx`/`params` at the top. Use `ctx.logger`, never
+   `console.log`. Use `ctx.utils` for generic patterns; keep site-specific logic
+   in step functions. Give EVERY function a full JSDoc block.
+5. **Return a result object** (`found`, `content`, `outputFile`, a URL, `message`).
+6. **Run it** to verify — see `running-automated-browser-tasks`. Iterate on the
+   real page; do not guess selectors.
+
+## Reference
+
+The exact param spec, `ctx.utils` surface, return shape, and worked examples are
+in the topic skill's references and `examples/`. Read them — do not improvise.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/automated-browser-tasks/running-automated-browser-tasks/SKILL.tpl.md

@@ -0,0 +1,59 @@
+---
+name: running-automated-browser-tasks
+description: >
+  YOU MUST load this skill when you need to run an existing headless browser
+  automation script for the user — to execute a task, fetch data from a site, or
+  verify a script you just wrote or changed.
+---
+
+# Run an Automated Browser Task
+
+A thin action skill. The agent performing this work MUST load
+`about-automated-browser-tasks` for the architecture and the meaning of `ctx`,
+auth handling, and result shapes.
+
+## Delegation
+
+Per the sub-agent delegation pattern
+(`~sous-shared/_partials/sub-agent-delegation.md`), a browser run is a slow, multi-step
+execution: delegate it to a background sub-agent, which runs the command,
+interprets the outcome below, and reports the result plus any link or actionable
+message. Run a one-off script inline only when its result blocks the very next
+step.
+
+## Invocation
+
+Run a script by its absolute path through the runner in this system's `scripts/`
+directory:
+
+```bash
+node <scriptsDir>/run.mjs <absolute-path-to-script.mjs> [--param=value ...]
+```
+
+- Pass script params as `--paramName=value`.
+- Harness options: `--profileName=<name>` (Chrome profile), `--timeout=<ms>`.
+- The runner loads compiled project `settings.mjs` automatically and prints the
+  resolved params (marking which came from defaults/settings) before running.
+
+## Reading the outcome
+
+- **Success** → `✓` and the result is printed; if the script returned an
+  `outputFile` + `content`, the runner writes the file and reports the path.
+- **`error: params`** → a required param was missing or failed validation. Fix the
+  invocation; do not edit the script to bypass validation.
+- **`error: auth`** → the session was redirected to a login page. The user must log
+  in to the site in their Chrome profile, then the SAME command is re-run; no
+  script change needed. A sub-agent cannot ask for this: return the actionable
+  message and the link to the orchestrator, which relays them to the user and
+  re-dispatches the run afterward.
+- **`error: script`** → an unexpected failure with a stack. Inspect, then use
+  `update-automated-browser-task` to fix the root cause and re-run.
+
+Never silently swallow a failure or fake a result. Report what happened.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/automated-browser-tasks/update-automated-browser-task/SKILL.tpl.md

@@ -0,0 +1,47 @@
+---
+name: update-automated-browser-task
+description: >
+  YOU MUST load this skill when you need to modify, fix, or extend an existing
+  headless browser automation script — for example when a script breaks because
+  a site's markup changed, or a new param/behavior is needed.
+---
+
+# Update an Automated Browser Task
+
+A thin action skill. The agent performing this work MUST load
+`about-automated-browser-tasks` for the architecture, `ctx` API, and full
+conventions.
+
+## Delegation
+
+Per the sub-agent delegation pattern
+(`~sous-shared/_partials/sub-agent-delegation.md`), the fix-and-re-run loop below
+is delegated to one Opus sub-agent, which reports what broke, what it changed, and the verified
+result. Give it the script path and the failing run output.
+
+## Steps
+
+1. **Read the script** and the run output. Identify the failing step from the
+   logger prefixes (`[script:section]`) in the output.
+2. **Reproduce** by running it (see `running-automated-browser-tasks`). For
+   selector/markup failures, inspect the live page — use `ctx.utils.screenshot`
+   or widen selectors; do not guess.
+3. **Make the smallest correct change.** Fix the root cause, not the symptom. Keep
+   the existing decomposition: edit the relevant step function, add a new one if a
+   new discrete action is needed.
+4. **Preserve conventions.** Maintain JSDoc blocks, `ctx`/`params` destructuring,
+   `ctx.logger` usage, and `meta.params` validation. If you add a param, give it a
+   description and a `validate` rule.
+5. **Re-run to verify** the fix end-to-end.
+
+## When NOT to update
+
+If the change amounts to a different task, create a new script instead
+(`create-automated-browser-task`). Keep each script focused on one job.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/approve/SKILL.tpl.md

@@ -0,0 +1,26 @@
+---
+name: approve
+description: Approve the current plan and instruct Claude to proceed with maximum parallelism.
+disable-model-invocation: true
+---
+
+Your plan looks good, and I approve.
+
+While executing the plan, maximize parallelism:
+- Delegate the steps that have any complexity to background sub-agents, per the sub-agent
+  delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), batching independent
+  dispatches into one message.
+- Batch independent investigations (searches, file reads, greps, listings) into concurrent tool
+  calls whenever practical.
+- Keep dependent steps sequential (especially edits, formatting/linting, and tests that rely on
+  prior changes).
+
+Use the best-fit tools for the job. If you can't parallelize a step, say why briefly and proceed
+sequentially.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
+template and the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/opine/SKILL.tpl.md

@@ -0,0 +1,58 @@
+---
+name: opine
+description: >
+  Used to send an idea or proposal to the agent and have it repeat it back, then offer an honest
+  analysis of viability, practicality, and overall merit. This is a discussion; no action is taken.
+argument-hint: idea or proposal
+disable-model-invocation: true
+---
+
+New Idea/Proposal:
+$ARGUMENTS
+
+-
+
+## CRITICAL: DO NOT ACT ON THIS IDEA
+
+This is a discussion, not a request. You must NOT take any action: do not write code, do not edit
+files, do not create branches, do not modify anything. The user is thinking out loud and wants
+your opinion. Your only output is text directed at the user.
+
+## Research
+
+You may research the codebase and/or the web before responding if you think it would improve the
+accuracy of your analysis. Most ideas won't need this; use your judgement. When you do research,
+prefer sub-agents and run them in parallel where practical.
+
+## Step 1: Repeat
+
+Repeat the idea or proposal back to me, in your own words and in a well-structured format so
+that I know our understandings are aligned.
+
+## Step 2: Analyze
+
+After repeating the idea back, offer your analysis in three parts:
+
+1. **Viability**: Is this idea technically feasible? Are there any fundamental blockers or
+   constraints that would prevent it from working?
+
+2. **Practicality**: Even if viable, is it practical? Would it require more steps, complexity,
+   or hacky code than I'm probably anticipating? Are there hidden costs (maintenance burden,
+   performance implications, edge cases)?
+
+3. **Opinion**: Is this a good idea? Give your honest take on whether this is the right approach.
+
+## Guidelines
+
+- **No action.** This cannot be overstated. Do not act on the idea. Only discuss it.
+- Be open and honest. Push back when you genuinely see problems.
+- "Yes, that seems like a great idea" is an entirely valid response. Do not manufacture
+  objections or play devil's advocate just for the sake of it. If the idea is sound, say so.
+  If it has real problems, say that too.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
+template and the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/repeat/SKILL.tpl.md

@@ -0,0 +1,27 @@
+---
+name: repeat
+description: >
+  Used to send an instruction to the agent and have the agent repeat the instruction back to you
+  before acting, to ensure that you and the agent are aligned.
+argument-hint: instruction
+disable-model-invocation: true
+---
+
+New Instruction:
+$ARGUMENTS
+
+-
+
+DO NOT ACT, yet. Instead, I want you to repeat the instruction back to me, in your own words and
+in a well-structured format so that I know our understandings are aligned. If I am satisfied with
+your explanation, I will approve you to begin acting.
+
+You may do a small amount of research before repeating the instruction back to me, if you think
+it would allow you to be more precise or accurate in your explanation.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
+template and the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/control-flow/research/SKILL.tpl.md

@@ -0,0 +1,34 @@
+---
+name: research
+description: Run a research task using background sub-agents
+user-invocable-only: true
+arguments-hint: what to research via background subagents
+---
+
+Have a background sub-agent do the following:
+$ARGUMENTS
+
+## Prefer Parallelism
+
+If possible, practical, and reasonable, break the task into multiple parts and assign each part to a sub-agent.
+Running background sub-agents in parallel usually makes things go much faster. Don't break tiny tasks up, though.
+
+Batch the independent dispatches into one message so they run at once. Opus by default; Sonnet only
+for rote extraction.
+
+## Sub-Agent Prompts
+
+Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), each prompt
+must be self-contained: the question to answer, the
+paths/IDs/facts needed, which skills to load, and the shape of the answer wanted. Sub-agents start
+fresh and cannot see this conversation.
+
+Each returns a concise summary, not a file dump. Do not fabricate or predict a pending result; wait
+for the notification. Synthesis and reporting to the user are orchestrator-only.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a
+template and the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/sous-skills/about-agent-skills/SKILL.tpl.md

@@ -0,0 +1,177 @@
+---
+name: about-agent-skills
+description: >
+  YOU MUST load this skill when creating, editing, auditing, or reasoning about any
+  skill. Covers skill structure, frontmatter fields, invocation, topic vs action
+  patterns, naming conventions, and general principles.
+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`,
+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 —
+never in `.claude/skills/` or `.codex/skills/` directly. See `create-skill` for
+step-by-step instructions.
+
+## Directory Structure
+
+```
+my-skill/
+├── SKILL.md        # Required. Frontmatter + instructions.
+├── references/     # Optional. Deep-dive docs loaded when needed.
+├── examples/       # Optional. Example outputs.
+└── scripts/        # Optional. Executable scripts.
+```
+
+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.
+
+## Core Frontmatter
+
+```yaml
+---
+name: my-skill
+description: >
+  One or two sentences describing when the agent should invoke this skill.
+  Under 500 characters. Write as a trigger condition, not a title.
+disable-model-invocation: true
+user-invocable: false
+---
+```
+
+**`name`** — becomes the `/slash-command`. Defaults to the directory name if omitted.
+
+**`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
+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
+all topic skills (`about-*`). They are reference material the agent loads
+automatically, not commands for the user to invoke.
+
+For all frontmatter fields, see [references/frontmatter.md](references/frontmatter.md).
+
+## Topic vs Action Skills
+
+**Topic skills** hold reference material and background context for a concept, plus any
+shared scripts the action skills draw from. They are moderately descriptive and reusable
+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.
+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
+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
+skills with a verb prefix: `create-`, `deploy-`, `run-`. If the skill operates on a
+specific type, include it after the verb (e.g. `create-skill` operates on a "skill").
+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
+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.
+
+## Template Files (`.tpl.`)
+
+Any file in a skill directory can use `.tpl.` naming to opt into LiquidJS processing
+at compile time. The `.tpl.` segment is stripped from the output filename.
+For when `SKILL.md` must be `SKILL.tpl.md`, see **Template-Compiled Skills** below.
+
+YOU MUST load `about-liquid-templates` when deciding whether any file in a skill
+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
+duplicated across skills. Before adding content anywhere, ask whether it belongs
+higher up.
+
+**Every skill provides minimal cold-start context.** Assume the agent knows nothing
+about the concept until the skill is loaded, and will not load any other skill unless
+explicitly told to. Include the briefest possible orientation, then point to deeper
+resources.
+
+**Never duplicate information that changes over time.** Do not create lists or tables
+that inventory things which will evolve (e.g. available skills, current files in a
+directory). Teach the agent where to look rather than providing a snapshot that will go
+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
+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
+must load the skills themselves.
+
+**Write steps for whoever executes them.** Do not assume the main session performs
+a skill's steps inline. Say which steps are delegated to a sub-agent and which are
+orchestrator-only (anything needing the user, or the chat conversation's own
+contents). Never rely on "skip this if it is already in context" heuristics: a
+sub-agent's context is always fresh. Steps that produce a link or question for the
+user must return it to the orchestrator, which relays it.
+
+**If no action skill exists for a task, ask the user.** Do not improvise an action
+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 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.
+
+Every such skill's `SKILL.md` must end with a `## Source for this Skill` section:
+
+```
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: <resolved source path>
+```
+
+This tells agents reading the compiled output where the skill originated and that the
+file must not be edited directly. Because this footer is required, all shared skills must
+use `SKILL.tpl.md` (not `SKILL.md`) so the source path variable can be rendered at
+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)
+
+## 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`
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}