td

Files (5)

• SKILL.md
• build_td_docx.py
• docx-generation.md
• review-rubric.md
• README.md · samples/

SKILL.md (first lines)

# Technology Disclosure (TD) Skill

## On activation

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

> **TD skill activated.** I'll run a pre-flight, draft the disclosure in markdown, then step you through review, humanizing, and `.docx` generation — pausing for your go-ahead at each step.

Then proceed immediately to Phase 1. No further preamble.

---

This skill generates Technology Disclosures: short research-paper-style documents describing a software contribution from a project. The working format is markdown (for fast iteration). Generation of the final `.docx` is the **last** step and happens only after the user has approved the draft — never automatically right after drafting.

The flow is gated: draft → (ask) self-review → revise until satisfied → (ask) humanize → (ask) generate `.docx`. Each arrow is a checkpoint where you stop and wait for the user. Do not run ahead to the next step on your own.

A TD is **not**: release documentation, a pitch deck, a marketing piece, a code walkthrough. It is closer to an academic research paper but produced for internal IP/disclosure purposes — typically under 20 pages, with the structure and rigor of a short conference paper.

## Deliverables

Files written to the TD output directory, in the order they appear:

1. **Draft TD** — `<PROJECT>_TD_<short-title-slug>_<YYYY-MM-DD>.md` (always)
2. **Self-review** — `<PROJECT>_TD_<short-title-slug>_<YYYY-MM-DD>_review.md` (only if the user opts into review)
3. **Final TD** — `<PROJECT>_TD_<short-title-slug>_<YYYY-MM-DD>.docx` (only when the user approves generation, as the last step)

Where `<PROJECT>` is the project name from `../project_context.md`.

The markdown draft is the working artifact; it is revised in place across review and humanizing. The `.docx` is generated once, at the end, from the approved draft.

---

## Prerequisites

Both are needed for the `.docx` generation step (Phase 5). They do not need to be installed up front — that phase checks for them and offers to install what's missing (see `./docx-generation.md`):

- **`pandoc`** (`brew install pandoc` / `apt install pandoc`) — converts the markdown body and builds the Word table-of-contents field.
- **`python-docx`** (`pip install python-docx`) — adds the cover page, sections, header/footer, page numbering, and justification.

---

## Required reading before doing anything

Before writing any code, generating any draft, or running the review pass:

1. Read `../project_context.md` — authoritative facts about the project.
2. Run the Bootstrap check (see below) — creates output and samples directories if missing.
3. Check `docs/td/samples/` — see "Samples handling" below for what to do based on what you find.

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

---

## Bootstrap — first-time setup check

Run this before anything else, every invocation:

1. Check whether `docs/td/` exists at the project root.
2. **If it does not exist**, create it along with the shared assets directory:
   ```bash
   mkdir -p docs/td/samples/ docs/assets/logos/
   ```
   `docs/assets/logos/` is a **shared** project asset directory (not specific to this skill — other skills, e.g. documentation, can use the same logos). Then tell the user:
   > "This skill requires `docs/td/` in your project root — created it now along with `docs/td/samples/` and a shared `docs/assets/logos/`. Two things to drop in:
   > - **Sample TDs** (`.pdf` / `.docx`) into `docs/td/samples/` — the skill calibrates its tone, structure, and citation style against them.
   > - **Your organization's logo** (`.png` / `.jpg`) into `docs/assets/logos/` — it goes on the `.docx` cover page and in the page header.
   >
   > Re-invoke me once you've added them, or tell me to proceed now (I'll work without samples — output may not match your house style — and ask about the logo when it's time to generate the `.docx`)."

   Wait for the user's response before continuing to Phase 1.

3. **If `docs/td/` exists** but `docs/td/samples/` or `docs/assets/logos/` do not, create the missing ones silently and proceed.

---

## Samples handling

The `docs/td/samples/` directory holds reference TDs from the user's organization. They are used by both the drafter (for tone, structure, conventions) and the reviewer (for style reference during the self-review pass).

**If `docs/td/samples/` contains usable files** (`.pdf`, `.docx`, or `.md` files; ignore `README.md`): read all of them carefully. They are the calibration target for tone, section weight, citation style, table use, and figure conventions.

**If `docs/td/samples/` is empty**: ask the user before proceeding:

> "I don't see any sample TDs in `docs/td/samples/`. The skill works best with at least one reference TD from your organization so the output matches your house style. You can:
> (a) drop one or more `.pdf` / `.docx` TDs into `docs/td/samples/` and re-invoke me, or
> (b) tell me to proceed anyway and I'll produce a best-effort TD using abstract conventions only (output may not match your org's specific style).
>
> What would you like to do?"

If the user picks (b), proceed but include a brief note in the hand-off summary mentioning that the TD was generated without samples and may not match house style. Do not silently lower quality without flagging.

**If `docs/td/samples/` contains a `README.md`**: read it — it may contain user-supplied notes about which samples illustrate which patterns, or about house-convention deviations from the samples (e.g. "samples name commercial competitors but house convention is generic descriptions"). These notes override what you'd infer from the samples alone.

---

## Output directory

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

---

## Workflow

The skill has six phases, each gated on the user's go-ahead:

1. **Pre-flight** — gather scoping context.
2. **Draft** — write the markdown draft. Then *ask* whether to run the self-review.
3. **Self-review** — if the user agrees, review and then revise the draft until they're satisfied.
4. **Humanize** — *ask* whether to apply the `/humanizer` skill to the approved draft.
5. **Generate `.docx`** — *ask* whether the user is ready; then handle the logo and build the document.
6. **Hand off** — summarize and point to the files.

Do them in order. Do not skip a checkpoint or run the next phase before the user says to.

---

### Phase 1 — Pre-flight (ask the user)

TDs are scoped, audience-aware documents. Ask the user the following before drafting. This is "ask more" mode — gather enough context that the draft is grounded, not generic. Bundle the questions; don't ask one at a time.

From cslev/skillet, MIT.

More from cslev/skillet