From 93dbebb98200e3285780622dfeedf4196c964fff Mon Sep 17 00:00:00 2001
From: Steve Cliff <steve@devcloud.guru>
Date: Mon, 22 Jun 2026 20:51:15 +0100
Subject: [PATCH] docs(skill): make SKILL.md self-bootstrapping from the repo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An agent pointed at the repo may load only SKILL.md and then guess a wrong path
for the installer (it fetched /scripts/install.sh at repo root → 404; the file is
under skills/emcli/). Fix:

- Add a "First: get this skill's files" section: the supporting scripts/ and
  references/ files, the absolute raw base URL to fetch them, and the Gitea
  contents API to enumerate the directory.
- Install step now gives an absolute-URL fetch-then-run for the only-SKILL.md case,
  keeping `bash scripts/install.sh` for the bundled case.
- State that every scripts/… and references/… path is relative to the skill dir and
  resolvable against the raw base URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/emcli/SKILL.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/skills/emcli/SKILL.md b/skills/emcli/SKILL.md
index 3997a89..f5a3d18 100644
--- a/skills/emcli/SKILL.md
+++ b/skills/emcli/SKILL.md
@@ -15,6 +15,31 @@ and send mail; the program holds the credentials and enforces the user's rules,
 password and cannot bypass the limits. Every agent command prints exactly **one line of JSON** and
 sets its exit code to match.
 
+## First: get this skill's files
+
+This skill is more than this one file. It ships a `scripts/` and a `references/` directory that the
+steps below use. **If you were pointed at the repository and have only this `SKILL.md` in context,
+download the rest of the skill's files before proceeding** — fetch the whole `skills/emcli/`
+directory, or grab each file as a step calls for it.
+
+Every `scripts/…` and `references/…` path mentioned in this document is **relative to this skill's
+directory**. If a file isn't already on disk, fetch it from this raw base URL + the path:
+
+```
+https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/
+```
+
+The files are:
+
+| Path | Purpose |
+|---|---|
+| `scripts/install.sh` | Installs the emcli binary |
+| `references/commands.md` | Full agent command reference (flags, JSON shapes, error codes) |
+| `references/install.md` | Installer options / build from source |
+
+To enumerate the directory programmatically (then recurse into `scripts` and `references`), use the
+Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/contents/skills/emcli`.
+
 ## Security model — read this first
 
 - **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`. Account setup,
@@ -30,14 +55,24 @@ sets its exit code to match.
 
 ## Setup (do this once per session, before the first command)
 
-1. **Check the binary is available.** Run `emcli version`. If the command is not found, install it:
+1. **Check the binary is available.** Run `emcli version`. If the command is not found, install it.
+
+   If you have the skill files locally:
 
    ```bash
    bash scripts/install.sh
    ```
 
+   If you only have this `SKILL.md` (pointed at the repo), fetch the installer first, then run it:
+
+   ```bash
+   curl -fsSL https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/scripts/install.sh -o emcli-install.sh
+   bash emcli-install.sh
+   ```
+
    This downloads the binary from the project's releases and puts it on your PATH
-   (`~/.local/bin` by default). See [references/install.md](references/install.md) for options.
+   (`~/.local/bin` by default). For options, see `references/install.md` (fetch it from the raw base
+   URL above if you don't have it locally).
 
 2. **Check the key is present.** Confirm the `EMCLI_KEY` environment variable is set (e.g.
    `test -n "$EMCLI_KEY"`). **Do not print its value.** If it is empty, do not proceed — tell the
@@ -124,7 +159,8 @@ Defaults: `--folder INBOX`, `--limit 50` (max 500). Dates are RFC 3339 (e.g.
 `2026-06-01T00:00:00Z`). UIDs come from `list`/`search` output.
 
 **Full reference** (every flag, exact JSON shapes for each command, attachment encoding, error
-codes, and the enforcement rules): [references/commands.md](references/commands.md).
+codes, and the enforcement rules): `references/commands.md` — read it from disk, or fetch it from
+the raw base URL in "First: get this skill's files" above if you don't have it locally.
 
 ## Enforcement awareness — work *with* the rules