documentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Documentation Skill

This skill generates and updates the project's release documentation deliverables.

**Distinct from the `pitch-deck` skill**: that skill produces all standalone slide decks (pitch decks for external audiences, release showcase decks, status decks). This skill produces written `.docx` guides only — no decks.

**Distinct from the `td` skill**: that skill produces Technology Disclosures (research-paper-style documents for IP/disclosure purposes). This skill produces user-facing and engineer-facing release documentation.

## Deliverables

Each release produces two files:

1. **User Guide** — `.docx`, technical overview level
2. **Technical Guide** — `.docx`, internals-deep level

If a release-showcase slide deck is also wanted, that's the pitch-deck skill's job (mode (b) frame (i) — version-vs-version pitch deck). The two skills are designed to be used together when needed: this one for the prose docs, the pitch-deck skill for the deck.

Both guides target a technical audience. The User Guide explains *what the system does and how to operate it*; the Technical Guide explains *how it works internally*. Tone and structure should loosely match the previous versions in the project's documentation directory but improvements are welcome — do not slavishly copy formatting quirks.

---

## On activation

**Always announce that this skill has been triggered.** At the very start of your first reply, output exactly one line:

> **Documentation skill activated.** I'll generate versioned User Guide and Technical Guide `.docx` files for your release.

Then proceed immediately to the workflow. No further preamble.

---

## Prerequisites

`python-docx` must be installed in the environment (`pip install python-docx`). All `.docx` reading and generation depends on it.

---

## Required reading before doing anything

Before writing any code or generating any file:

1. Read `../project_context.md` — authoritative facts about the project (name, components, terminology). Everything in the docs must be consistent with this file.
2. Run the Bootstrap check (see below) — creates output and samples directories if missing.
3. Read the **most recent** existing doc of each type in `docs/documentation/` — for tone, structure, terminology, and filename patterns.

For producing the `.docx` files themselves, use `python-docx` via a Python script. If updating existing docs in place (rather than creating new versioned files), use `python-docx`'s revision-tracking support to apply tracked changes to the existing file.

If `../project_context.md` has placeholder `<fill in: ...>` markers still unfilled and they're relevant to the section being documented, stop and tell the user — the docs cannot be reliable until those are real.

---

## Bootstrap — first-time setup check

Run this before anything else, every invocation:

1. Check whether `docs/documentation/` exists at the project root.
2. **If it does not exist**, create it:
   ```bash
   mkdir -p docs/documentation/samples/
   ```
   Then tell the user:
   > "This skill requires `docs/documentation/` in your project root — created it now along with `docs/documentation/samples/`. You can optionally drop reference `.docx` files from other projects or your organization's style guide into `docs/documentation/samples/` for style calibration. Tell me to proceed when ready."

   Wait for the user's response before continuing.

3. **If it exists** but `docs/documentation/samples/` does not, create it silently and proceed.

---

## Output directory

Always use `docs/documentation/` for output. Always use `docs/documentation/samples/` for reference samples. These paths are fixed — do not look for or create alternative locations.

**Determining the filename pattern:**

1. **Read existing filenames in `docs/documentation/`** to infer the project's filename pattern. For example:
   - `MyProject_UserGuide_v1.2.docx` → pattern is `<ProjectName>_UserGuide_v<MAJOR>.<MINOR>.docx`
   - `userguide-v1.2.docx` → pattern is `userguide-v<MAJOR>.<MINOR>.docx`

2. **If the directory is empty** (first use), ask the user what filename pattern they'd like, or propose a default based on the project name from `../project_context.md`:
   ```
   <ProjectName>_UserGuide_v<MAJOR>.<MINOR>.docx
   <ProjectName>_TechnicalGuide_v<MAJOR>.<MINOR>.docx
   ```

3. **Other documents in the same directory** (pitch decks, TDs, ad-hoc notes) should be ignored — filter to files matching the User Guide and Technical Guide patterns specifically.

---

## Reference samples (optional)

`docs/documentation/samples/` may contain `.docx` files from other projects or your organization's documentation style guide. If present, read them for tone, heading structure, and formatting conventions before generating. They supplement (not replace) the most recent versioned docs in `docs/documentation/`. Do not version-diff against them.

If `docs/documentation/samples/` is empty, skip it silently — reference samples are optional for this skill.

---

## Workflow

### Step 1 — Determine the target version

Ask the user for the new version number (e.g. "v2.0") if it isn't already clear from the prompt or recent context. Do not guess. The version string drives output filenames and the "what's new" markers throughout the docs.

### Step 2 — Find the latest existing version of each doc

For each release-doc type (User Guide, Technical Guide), list the docs directory, filter to files matching the patterns identified above, and pick the file with the highest version number by parsing the version suffix. **Do not assume alphabetical sort gives the right answer** — `v1.10` sorts before `v1.2` alphabetically but is newer. Parse numerically.

If no previous version of a given doc type exists, treat this as a first release for that doc and generate from scratch — but still gather change context (Step 3) so the doc is grounded in actual current state.

### Step 3 — Gather change signal from all four sources

To determine what's new in this version, cross-reference **all of the following**, in this order:

1. **`CHANGELOG.md`** at repo root (or wherever the project's changelog lives — check `CHANGELOG`, `HISTORY.md`, `RELEASES.md` if `CHANGELOG.md` isn't there) — the user's curated source of truth. Read the section for the new version. If a section for the new version doesn't exist yet, ask the user whether to proceed using the other three sources only, or wait for the changelog to be updated.

2. **Git log since the previous release tag**:
   ```bash
   git log <previous-version-tag>..HEAD --oneline --no-merges
   ```

From cslev/skillet, MIT.

More from cslev/skillet