# Agent Skills

> Personal collection of agent skills — both custom-authored and cherry-picked from upstream repos.

Personal collection of agent skills — local custom-authored skills under skills/local/ and 3rd-party skills cherry-picked into skills/vendor/ via the vendor.yaml manifest. Includes project-knowledge-harness (a TODO/backlog/pitfalls memory harness with bundled init/kanban/promote scripts) and quantatitive-factor-researcher (a Python quant-research persona). Installable via `npx skills@latest add daviddwlee84/agent-skills/skills`.


# Guides

# Agent Skills

A personal collection of [agent skills](https://agentskills.io/home) — both custom-authored and cherry-picked from upstream repos — installable as a single package.

## Install

```
# Install all skills bundled in this repo into your project's
# .agents/skills/ directory.
npx skills@latest add daviddwlee84/agent-skills/skills
```

> **Note** The trailing `/skills` matters. Without it, `npx skills` will look in `.agents/skills/` of the upstream repo, which contains a different layout. The `skills/` suffix points the installer at the `skills/local/` and `skills/vendor/` trees.

This is the recommended cross-agent install path. Project installs place the canonical skill content under `.agents/skills/`, which Codex reads directly; Claude Code receives its corresponding `.claude/skills/` links.

> **Heads-up — upstream picker bug.** `npx skills`' interactive multiselect glitches once the skill list is long enough to scroll: options render duplicated and the selection state gets corrupted ([vercel-labs/skills#969](https://github.com/vercel-labs/skills/issues/969)). This repo ships enough skills to trigger it. Until it's fixed upstream, skip the picker:
>
> ```
> # Install everything, non-interactively (no picker)
> npx skills@latest add daviddwlee84/agent-skills/skills --yes
>
> # List names from a disposable directory. In an existing agent-managed
> # project, skills@1.5.23 may reconcile .agents/skills even with --list.
> scratch="$(mktemp -d)"
> (cd "$scratch" && npx skills@latest add daviddwlee84/agent-skills/skills --list)
> rm -rf "$scratch"
>
> # Install one skill by name.
> npx skills@latest add daviddwlee84/agent-skills/skills --skill clash-proxy-api
> ```

### Optional: native Claude Code and Codex marketplaces

A local checkout can expose the same category catalog through either native plugin CLI:

```
git clone https://github.com/daviddwlee84/agent-skills.git

# Claude Code
claude plugin marketplace add ./agent-skills/skills
claude plugin install version-control@daviddwlee84-skills

# Codex (verified with 0.147.0)
codex plugin marketplace add ./agent-skills/skills
codex plugin add version-control@daviddwlee84-skills
```

Both native routes install a whole category plugin (`version-control` in this example), not an arbitrary single skill. Codex reads the existing Claude-format marketplace and generates its `.codex-plugin/plugin.json` adapter inside the plugin cache; this repository does not need to maintain that second manifest. Keep using `npx skills` when you want one skill or a cross-agent installation.

Pass the checkout's `skills/` directory, not the repository root: the catalog intentionally lives under `skills/.claude-plugin/` for the `npx` subpath above, and both native CLIs require a supported manifest at the marketplace source root.

## What's in here

Three categories of skills live under `skills/`:

- **`skills/local/`** — custom-authored skills maintained in this repo. See the [Skills overview](https://daviddwlee84.github.io/agent-skills/skills/index.md) for the index.
- **`skills/owned/`** — first-party skills maintained in other projects, including [go-cli-tui](https://daviddwlee84.github.io/agent-skills/skills/go-cli-tui/index.md); see [owned workflows](https://daviddwlee84.github.io/agent-skills/workflows/adding-owned-skills/index.md).
- **`skills/vendor/`** — third-party skills synced from upstream repos via the [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml) manifest. See [Adding vendor skills](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/index.md).

The repo is also a live example of the [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) skill applied to itself: [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md), [`backlog/`](https://github.com/daviddwlee84/agent-skills/tree/main/backlog), and [`pitfalls/`](https://github.com/daviddwlee84/agent-skills/tree/main/pitfalls) sit at repo root, with [`scripts/`](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md) wrapping the validator/promoter/inbox toolkit.

## Where to go next

| If you want to…                           | Read                                                                                                             |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Install and try the skills                | [Getting Started](https://daviddwlee84.github.io/agent-skills/getting-started/index.md)                          |
| Understand naming / layout rules          | [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md)                                  |
| Add a third-party skill                   | [Adding vendor skills](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/index.md)      |
| Author a new local skill                  | [Creating local skills](https://daviddwlee84.github.io/agent-skills/workflows/creating-local-skills/index.md)    |
| Capture a TODO or pitfall in a project    | [Project memory workflow](https://daviddwlee84.github.io/agent-skills/workflows/project-memory/index.md)         |
| Browse what skills exist                  | [Skills overview](https://daviddwlee84.github.io/agent-skills/skills/index.md)                                   |
| Browse external skills, MCPs, domain hubs | [Catalog](https://daviddwlee84.github.io/agent-skills/catalog/index.md)                                          |
| Build a docs site for your own project    | [Downstream docs stack recipe](https://daviddwlee84.github.io/agent-skills/reference/docs-stack-recipe/index.md) |

## For AI assistants

This site exposes LLM-friendly endpoints (per the [llmstxt.org](https://llmstxt.org/) spec):

- [`llms.txt`](https://daviddwlee84.github.io/agent-skills/llms.txt) — compact index of all default-language pages
- [`llms-full.txt`](https://daviddwlee84.github.io/agent-skills/llms-full.txt) — default-language pages concatenated into one file
- Every page is also available as raw Markdown by appending `/index.md` to its URL (e.g. [`getting-started/index.md`](https://daviddwlee84.github.io/agent-skills/getting-started/index.md)).

If you're an agent reading this, prefer `llms-full.txt` for a single-shot context dump, or fetch individual `*/index.md` paths for the page you need.

# Getting Started

## Install the skills

```
# Install all skills bundled in this repo into your project's
# .agents/skills/ directory.
npx skills@latest add daviddwlee84/agent-skills/skills
```

> **Note** The trailing `/skills` matters. Without it, `npx skills` will look in `.agents/skills/` of the upstream repo, which contains a different layout. The `skills/` suffix points the installer at the `skills/local/` and `skills/vendor/` trees.

This is the recommended cross-agent install path. Project installs place the canonical skill content under `.agents/skills/`, which Codex reads directly; Claude Code receives its corresponding `.claude/skills/` links.

> **Heads-up — upstream picker bug.** `npx skills`' interactive multiselect glitches once the skill list is long enough to scroll: options render duplicated and the selection state gets corrupted ([vercel-labs/skills#969](https://github.com/vercel-labs/skills/issues/969)). This repo ships enough skills to trigger it. Until it's fixed upstream, skip the picker:
>
> ```
> # Install everything, non-interactively (no picker)
> npx skills@latest add daviddwlee84/agent-skills/skills --yes
>
> # List names from a disposable directory. In an existing agent-managed
> # project, skills@1.5.23 may reconcile .agents/skills even with --list.
> scratch="$(mktemp -d)"
> (cd "$scratch" && npx skills@latest add daviddwlee84/agent-skills/skills --list)
> rm -rf "$scratch"
>
> # Install one skill by name.
> npx skills@latest add daviddwlee84/agent-skills/skills --skill clash-proxy-api
> ```

### Optional: native Claude Code and Codex marketplaces

A local checkout can expose the same category catalog through either native plugin CLI:

```
git clone https://github.com/daviddwlee84/agent-skills.git

# Claude Code
claude plugin marketplace add ./agent-skills/skills
claude plugin install version-control@daviddwlee84-skills

# Codex (verified with 0.147.0)
codex plugin marketplace add ./agent-skills/skills
codex plugin add version-control@daviddwlee84-skills
```

Both native routes install a whole category plugin (`version-control` in this example), not an arbitrary single skill. Codex reads the existing Claude-format marketplace and generates its `.codex-plugin/plugin.json` adapter inside the plugin cache; this repository does not need to maintain that second manifest. Keep using `npx skills` when you want one skill or a cross-agent installation.

Pass the checkout's `skills/` directory, not the repository root: the catalog intentionally lives under `skills/.claude-plugin/` for the `npx` subpath above, and both native CLIs require a supported manifest at the marketplace source root.

This populates `.agents/skills/` in your project with everything under `skills/local/` and `skills/vendor/` from this repo.

## Render the repo backlog

If you want to see the kanban view of the repo's own TODO list:

```
git clone https://github.com/daviddwlee84/agent-skills
cd agent-skills
make kanban
```

`make kanban` runs [`scripts/todo-kanban.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#todo-kanbansh), which validates [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) and prints a Markdown board grouped by lane.

## Build the docs locally

The docs site you're reading is a [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) site. To preview it locally:

```
# From the repo root
uv sync --extra docs
uv run mkdocs serve
```

Then open <http://127.0.0.1:8000/>.

To produce the static site (what GitHub Pages serves):

```
uv run mkdocs build --strict
```

`make docs-serve` and `make docs-build` are convenience wrappers around those two commands.

## Apply the project-knowledge-harness skill to your own project

If you just want the TODO + backlog + pitfalls structure in another repo, the bundled init script does the whole setup in one shot:

```
git clone https://github.com/daviddwlee84/agent-skills /tmp/agent-skills
/tmp/agent-skills/skills/local/project-knowledge-harness/scripts/init.sh \
  --target /path/to/your/project \
  --project-name "Your Project" \
  --deployment chezmoi   # or npm | pip | docker | none
```

See the [`project-knowledge-harness` page](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) for what the script does and what flags it supports.

# Conventions

These are the rules every local skill in this repo follows. They exist so the package shipped via `npx skills` stays predictable and so adding a new skill is mechanical, not a design exercise.

## Local skill layout

Each `skills/local/<skill>/` directory should contain:

- **`SKILL.md`** — required, with YAML frontmatter (`name`, `description`) and a body that follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) (lean SKILL.md under ~500 lines, defaults over menus, procedures over declarations).
- **`assets/`** — templates the skill copies into a target project (e.g. `TODO.md.template`, `pitfall-doc.md.template`).
- **`scripts/`** — executable helpers the agent should invoke instead of re-implementing logic in chat. Bash 3.2 compatible (so they run on stock macOS without homebrew bash).
- **`references/`** — long-form material the agent loads on demand (decision tables, schema cheatsheets, anti-pattern lists). Push detail here rather than swelling `SKILL.md`.

## Mirror scripts to top-level `scripts/`

Where a skill ships scripts that this repo also wants to run directly (currently only [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md)), copy them into the top-level [`scripts/`](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md) directory so `make` targets and CI can invoke them. Keep the canonical copy inside the skill so the package shipped via `npx skills` stays self-contained.

The pair must stay byte-identical. The repo doesn't (yet) enforce this in CI; if you edit one, edit the other in the same commit.

## Owned skill layout

`skills/owned/<skill>/` contains first-party skills maintained in a separate source project. Edit that project's canonical skill, then sync here. The same upstream manifest and machinery serve owned and third-party sources; see [owned workflow](https://daviddwlee84.github.io/agent-skills/workflows/adding-owned-skills/index.md). The distribution directory contains real files, not cross-repository symlinks.

## Vendor skill layout

`skills/vendor/<skill>/` mirrors the upstream layout exactly. Don't edit vendored skills in place — modifications get overwritten by `make sync`. If you need to customize a vendored skill, fork it into `skills/local/` and update [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml) to drop the upstream entry.

## Documentation

Every local skill should also have a page under `docs/skills/<skill>.md`. The skill's `SKILL.md` is for the agent (concise, machine-aimed); the `docs/skills/<skill>.md` page is for humans deciding whether to use it. Both surfaces are valuable — don't try to merge them.

Long-form references that the agent loads on demand (`skills/local/<skill>/references/*.md`) can be mirrored or summarized under `docs/reference/` when the audience extends to humans browsing the site, but the canonical copy still lives next to `SKILL.md`.

## Personal scratch areas

`Collections.md` and `notes/` at the repo root are personal scratch space for the maintainer and are intentionally not part of the published docs site or the agent-facing surface. Don't link into them from `SKILL.md` or from any docs page.
# Workflows

# Adding catalog entries

How to add or update entries in the [Catalog](https://daviddwlee84.github.io/agent-skills/catalog/index.md) — new external skills, new MCP servers, new domain hubs, or status changes on existing entries.

This workflow couples the catalog to `vendor.yaml` and `TODO.md` (the existing sources of truth) without duplicating them. Catalog pages are the *vendoring decision log*; the actual vendoring happens via existing scripts.

## When to write a catalog entry

| You discovered…                                                      | Where it goes                                                                                                                                                                                          | Status to start with                |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| An external skill you might want to vendor                           | [`skill-collections.md`](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/index.md) + relevant [domain hub](https://daviddwlee84.github.io/agent-skills/catalog/domains/index.md) | `wishlist`                          |
| An interesting skill you explicitly do not want in routine discovery | [`curiosities.md`](https://daviddwlee84.github.io/agent-skills/catalog/curiosities/index.md)                                                                                                           | `skipped` with the docs-only reason |
| An MCP server you want to remember                                   | New file under [`catalog/mcp/`](https://daviddwlee84.github.io/agent-skills/catalog/mcp/index.md) + relevant domain hub                                                                                | `wishlist`                          |
| A whole new professional domain                                      | New file under [`catalog/domains/`](https://daviddwlee84.github.io/agent-skills/catalog/domains/index.md) (copy `_template.md`)                                                                        | (hub itself, not entry)             |
| A skill you looked at and rejected                                   | Add to `skill-collections.md` with reason                                                                                                                                                              | `skipped`                           |
| A skill you looked at but didn't decide on                           | Add to `skill-collections.md` with 1-line note                                                                                                                                                         | `evaluated`                         |

## Status enum

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

## Status change recipes

### `wishlist` → `deferred`

The entry has crossed into "we should evaluate this" territory.

```
./scripts/add-todo.sh --priority P? --effort <S|M|L> \
  --title "<skill-name> skill" \
  --description "Evaluate <upstream URL> for <use case>. See catalog/<page>.md."
```

Then edit the catalog entry: change `status: wishlist` → `status: deferred`, link to the new TODO line.

### `deferred` → `vendored`

The entry has been evaluated and we want to vendor it.

```
# Vendor the skill (writes to vendor.yaml + downloads files)
./scripts/add-vendor.sh <owner>/<repo>/<path-to-skill>

# Or with a series subdir
./scripts/add-vendor.sh --series <series-name> <owner>/<repo>/<path-to-skill>

# If the entry had a TODO P? line, promote it
./scripts/promote-todo.sh --title "<substring>" \
  --summary "Vendored from <upstream URL>"
```

Then edit the catalog entry: change `status: deferred` → `status: vendored`, update the link to point at `skills/vendor/<name>/` (or `skills/vendor/<series>/<name>/`).

### `wishlist` / `evaluated` → `skipped`

You read the upstream and decided not to vendor.

Just edit the catalog entry: change status → `skipped`, add the reason inline (one sentence). Examples:

- "Skipped — duplicates `<other-skill>` from `<more-authoritative-source>`."
- "Skipped — Slack-specific; not portable."
- "Skipped — narrower than `<existing-local-skill>` and overlaps it."

## Adding a new MCP entry

1. Create `docs/catalog/mcp/<slug>.md` with the YAML frontmatter schema documented in [`mcp/index.md`](https://daviddwlee84.github.io/agent-skills/catalog/mcp/#per-entry-conventions).
1. Fill the 6-section body (TL;DR / capabilities / install / when / related / sources).
1. Translate to `docs/catalog/mcp/<slug>.zh-TW.md`.
1. Add to the `mkdocs.yml` nav under `Catalog → MCP wiki`.
1. Add a row to the entries table in [`mcp/index.md`](https://daviddwlee84.github.io/agent-skills/catalog/mcp/index.md).
1. Cross-link from any relevant domain hub's MCP section.

When the MCP wiki has 5+ entries, the index table will be regenerated by a script (planned — see follow-up TODOs). Until then, edit the table by hand.

## Adding a new domain hub

See the [How to add a new domain hub](https://daviddwlee84.github.io/agent-skills/catalog/domains/#how-to-add-a-new-domain-hub) section in the Domains overview — the recipe lives next to the template it references.

## Bilingual obligation

Every page in `docs/catalog/` (except the snippet and `_template.md`) must have a `*.zh-TW.md` counterpart. The `mkdocs-i18n` plugin's `fallback_to_default: true` means missing translations don't break the build, but the project convention is that every published page has both languages in the same PR.

## Validation

```
make docs-build       # strict mode catches missing snippets / broken links
make marketplace      # ensure no regression on vendor.yaml / marketplace.json
make kanban           # ensure TODO.md still parses
```

Open the served site (`make docs-serve`) and click through the new entries' cross-links to verify they resolve.

# Adding owned skills

Use `owned` when a skill belongs with another project you maintain. The source project evolves the instructions alongside its code; this collection supplies discovery, grouped installation, documentation, and a reviewed distribution copy.

| Category | Canonical location             | Editing rule                                       |
| -------- | ------------------------------ | -------------------------------------------------- |
| `local`  | This repository                | Edit `skills/local/<name>/`                        |
| `owned`  | Another first-party repository | Edit there; sync into `skills/owned/<name>/`       |
| `vendor` | A third-party repository       | Follow upstream; sync into `skills/vendor/<name>/` |

Ownership is explicit through `collection: owned`, not inferred from a username. `vendor.yaml` retains its historical filename and serves both upstream categories; omitting `collection` preserves existing vendor behavior. `series`, `license_path` and `frozen` work in either category.

## Start in the source project

For a skill useful while developing that project, put the canonical directory in `.agents/skills/<name>/`, with an optional `.claude/skills/<name>` discovery link. Use `skill-author` with explicit project scope:

```
bash skills/local/skill-author/scripts/new-skill.sh \
  --project --root /path/to/source-project userscript-development
```

Write and validate the skill in that project. Publish its canonical files before enrolling an ordinary remote sync source. Then, from this collection:

```
./scripts/add-vendor.sh --owned \
  daviddwlee84/Tampermonkey-Scripts/.agents/skills/userscript-development
```

Add `./owned/userscript-development` to the appropriate marketplace plugin's `skills[]`, add bilingual docs and navigation, and run `make validate` plus `make docs-build`. A series uses `./owned/<series>/<name>`.

## Bootstrap before the first upstream publication

A skill being authored across two local repositories does not yet have a remote commit containing its new files. Do not record an unrelated HEAD as `last_sync`. For this initial state only:

1. Finish and validate the source project's canonical directory.
1. Copy its actual files into `skills/owned/<name>/` and verify byte equality.
1. Add the source entry with `collection: owned`, `pending_upstream: true`, and empty `last_sync.date` / `last_sync.commit`.
1. Keep developing in the source project; refresh the bootstrap copy when needed.

```
skills:
  - name: userscript-development
    collection: owned
    pending_upstream: true
    upstream:
      owner: daviddwlee84
      repo: Tampermonkey-Scripts
      path: .agents/skills/userscript-development
      branch: main
    last_sync:
      date: ""
      commit: ""
```

Routine `make sync` / `make sync-check` explicitly report pending and preserve the bootstrap files. After the source is published, activate the named entry:

```
./scripts/sync-vendor.sh --activate userscript-development
```

Activation performs a real remote sync and clears pending only after success. An unpublished path or failed download leaves the existing copy intact. Review the diff before publishing this collection. Pending is for an unpublished owned source; `frozen` is for an upstream intentionally no longer being followed.

## Normal update loop

1. Update and validate the canonical skill with the source project's change.
1. Publish that source change through the project's normal workflow.
1. Run `./scripts/sync-vendor.sh --check userscript-development`, then `./scripts/sync-vendor.sh userscript-development` here.
1. Review the mirrored diff and recorded upstream SHA, run publish gates, and publish this collection through its normal workflow.

The existing weekly sync workflow also covers active owned entries and opens a reviewable PR. Sync fetches the skill tree from the recorded commit and stages downloads before replacing the last good copy.

The distribution copy contains real files. Cross-repository symlinks would refer to paths absent from downstream installations. Do not add a second canonical `skills/local/<name>` copy or load the skill into this collection's own discovery directories unless maintaining this collection actually needs it.

After publication, users can install from this collection's grouped picker or directly from the source project. The skill name stays `userscript-development`; changing its upstream source can still require an explicit reinstall/lock review.

## Maintainer verification

`make test-source-sync` runs offline fixtures with a fake GitHub CLI and real `yq`: default vendor routing, owned/series routing, check mode, pending activation, failed-download preservation, frozen entries, destination validation, and `add-vendor.sh --owned`. It requires Python 3 and mikefarah/yq.

# Adding vendor skills

Vendor skills are third-party skills cherry-picked from upstream repos into [`skills/vendor/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/vendor). The [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml) manifest tracks each upstream source plus the last-synced date and commit SHA, so re-syncing is reproducible.

## Quick add

```
./scripts/add-vendor.sh owner/repo/path/to/skill

# Examples
./scripts/add-vendor.sh marimo-team/skills/skills/marimo-notebook
./scripts/add-vendor.sh vercel-labs/agent-skills/skills/next-js
./scripts/add-vendor.sh --name my-name --branch dev owner/repo/skills/some-skill

# Group into a series subdir
./scripts/add-vendor.sh --series fullstack-nextjs vercel/vercel-plugin/skills/nextjs

# Or via Makefile
make add-vendor SOURCE=owner/repo/path/to/skill

# GitHub URLs also work
./scripts/add-vendor.sh https://github.com/marimo-team/skills/tree/main/skills/marimo-notebook
```

This verifies the upstream path exists, adds an entry to `vendor.yaml`, and syncs the skill immediately. Pass `--no-sync` to only add the entry without downloading.

**Dependencies:** `gh` (GitHub CLI, authenticated) and `yq` (YAML processor).

## Series grouping

When you're vendoring a coherent set of skills around a single tech stack (e.g. Next.js + Supabase + shadcn), pass `--series <name>` so the skills land in `skills/vendor/<series>/<name>/` instead of being flat. The `series` field is recorded in `vendor.yaml` and honored by `sync-vendor.sh`.

```
# vendor.yaml
- name: nextjs
  series: fullstack-nextjs              # ← optional, omit for flat layout
  upstream:
    owner: vercel
    repo: vercel-plugin
    path: skills/nextjs
    branch: main
  last_sync: { date: "...", commit: "..." }
```

This results in `skills/vendor/fullstack-nextjs/nextjs/SKILL.md`. The `npx skills@latest add` discovery does a 5-level fallback recursive search, so series subdirs are still discovered.

Existing flat entries (no `series` field) keep working unchanged. Active series in this repo:

- **`fullstack-nextjs`** — see [Skills overview > Fullstack Next.js series](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series)

## Repository-level licenses

If the skill subtree does not contain the upstream license, add `license_path` to its manifest entry:

```
- name: my-skill
  upstream:
    owner: org-name
    repo: project
    path: skills/my-skill
    branch: main
  license_path: LICENSE
  last_sync:
    date: ""
    commit: ""
    license_sha: ""
```

The sync script copies it to `skills/vendor/<name>/LICENSE.txt` and tracks its blob SHA independently, so license-only updates are detected by `make sync-check`.

## Manual config

If you'd rather edit `vendor.yaml` by hand:

```
- name: my-skill
  upstream:
    owner: org-name
    repo: skills-repo
    path: skills/my-skill
    branch: main
  last_sync:
    date: ""
    commit: ""
```

Then run `make sync` to download and stamp `last_sync`.

## Check for upstream updates

```
make sync-check
```

This dry-runs the sync against the recorded `last_sync.commit` for each entry and prints which skills have new commits upstream. Run `make sync` to apply.

## Scheduled sync (GitHub Actions)

[`.github/workflows/vendor-sync.yml`](https://github.com/daviddwlee84/agent-skills/blob/main/.github/workflows/vendor-sync.yml) runs `make sync` every Monday 03:00 UTC (plus `workflow_dispatch`, which takes an optional single-skill filter). When there is a diff it runs the publish gates and opens — or updates — a PR on the fixed branch `chore/vendor-sync`.

It opens a PR instead of committing to `main` because vendored `SKILL.md` content ships straight into downstream agents' context via `npx skills update`, and because a SKILL.md whose frontmatter stops parsing is [silently skipped](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/skill-description-colon-breaks-yaml-frontmatter.md) by `npx skills add` rather than erroring.

Two things to know:

- **`validate.yml` does not run on the sync PR.** GitHub does not trigger workflows for PRs created with `GITHUB_TOKEN`, so the sync job runs the gates itself (frontmatter lint, marketplace, kanban, native smoke) and reports the result in the PR body.
- **A red job usually means an upstream rename or removal.** `make sync` fails hard when `upstream.path` no longer resolves — that needs a human to choose `renamed_from:` vs `frozen:` (see [conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md)).

Repo setup required once: **Settings → Actions → General → Workflow permissions** must be *Read and write* with *Allow GitHub Actions to create and approve pull requests* enabled.

## Why not just install upstream directly?

`npx skills add owner/repo/path/to/skill` works one skill at a time and leaves no manifest. Vendoring into this repo gives you:

- A single install command for the whole curated set (`npx skills@latest add daviddwlee84/agent-skills/skills`).
- A pinned commit per skill so a reckless upstream change doesn't surprise you.
- A diff in your repo when you re-sync, which is your chance to read what changed before accepting it.

## Don't edit vendored skills in place

Modifications under `skills/vendor/` get overwritten by `make sync`. If you need to customize a vendored skill, fork it into `skills/local/` and drop the upstream entry from `vendor.yaml`. See [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md).

# Creating local skills

A local skill is a custom-authored skill maintained in this repo under [`skills/local/<skill-name>/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local).

## Scaffold a new skill

Use the bundled scaffolder (recommended — seeds the full agentskills.io best-practice layout and fans out the discovery symlinks for non-universal agents):

```
bash skills/local/skill-author/scripts/new-skill.sh <skill-name>
```

The script picks one of three **placement scopes** by walking up from your CWD; override with `--local` / `--project` / `--global` when intent isn't obvious:

| Scope       | Trigger                                                          | Canonical dir                                                                                           | Symlinks created                                                                                                          |
| ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **LOCAL**   | `vendor.yaml` / `skills/local/` / `skills/.claude-plugin/` found | `<repo>/skills/local/<name>/` (or `skills/vendor/` with `--vendor`)                                     | `.agents/skills/<name>` + `.claude/skills/<name>` -> `../../skills/{local,vendor}/<name>`                                 |
| **PROJECT** | `.git` found                                                     | `<repo>/.agents/skills/<name>/` (universal agents — Cursor/Codex/OpenCode/Warp — pick this up directly) | `.claude/skills/<name>` -> `../../.agents/skills/<name>` (+ any non-universal agent dir already present at the repo root) |
| **GLOBAL**  | neither anchor, or `--global`                                    | `~/.agents/skills/<name>/`                                                                              | `~/.claude/skills/<name>` -> `../../.agents/skills/<name>` (+ any non-universal agent dir already present under `$HOME`)  |

This mirrors the placement contract of `npx skills add` (canonical content in `.agents/skills/` + relative symlinks into each non-universal agent's home), so a skill scaffolded here will be picked up by Claude Code, Cursor, Codex, OpenCode, Warp, etc. without any extra wiring. See [`docs/reference/npx-skills-metadata.md`](https://daviddwlee84.github.io/agent-skills/reference/npx-skills-metadata/index.md) for the upstream mechanism.

Alternative (just the SKILL.md skeleton, no symlinks, no `references/` / `scripts/` / `assets/`):

```
cd skills/local
npx skills@latest init [skill-name]
```

This creates only `skills/local/<skill-name>/SKILL.md` with the required YAML frontmatter (`name`, `description`).

Before writing the description, check the repo's [Agent skill compatibility](https://daviddwlee84.github.io/agent-skills/reference/agent-skill-compatibility/index.md) policy. Local skills should target portable coding-agent limits: hyphen-case names under 64 chars, descriptions under 1024 chars, and 120-500 chars preferred.

## Required structure

See [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md) for the full layout rules. In short:

- `SKILL.md` — required, lean (under ~500 lines).
- `assets/` — templates the skill copies into target projects.
- `scripts/` — executable helpers (Bash 3.2 compatible).
- `references/` — long-form material loaded on demand.

## Author the SKILL.md following agentskills.io best practices

The two highest-leverage rules from the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices):

1. **Procedures over declarations.** Tell the agent what to *do*, not what to *be*. A SKILL.md that says "follow these three steps" is much more reliable than one that says "be a careful and methodical helper".
1. **Defaults over menus.** Pick one workflow as the default; offer alternatives via flags or in `references/`. Letting the agent choose between three equivalent options at every step is a debugging nightmare.

A third rule we apply in this repo:

- **Bundle the workflow as a script if you can.** If the skill keeps asking the agent to perform the same multi-step procedure, write it as a shell script in `scripts/` and make the SKILL.md call the script. The [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) skill is the reference for this pattern.

## Add a docs page

Every local skill should also have a page under `docs/skills/<skill>.md` that explains, for a human reader, what the skill is for, when it triggers, and what it costs to use. The `SKILL.md` is the agent-facing contract; the docs page is the human-facing pitch. Both are valuable.

When you create the docs page, also link it from [`docs/skills/index.md`](https://daviddwlee84.github.io/agent-skills/skills/index.md) and from `mkdocs.yml`'s `nav:` block at the repo root.

## Test by installing into a scratch project

```
mkdir /tmp/scratch && cd /tmp/scratch
git init
npx skills@latest add daviddwlee84/agent-skills/skills
```

This pulls the new skill into `.agents/skills/` of a clean project so you can verify the SKILL.md activates as you expect.

# Project memory workflow

This page describes how to add and maintain entries in this repo's [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md), [`backlog/`](https://github.com/daviddwlee84/agent-skills/tree/main/backlog), and [`pitfalls/`](https://github.com/daviddwlee84/agent-skills/tree/main/pitfalls) directories. The same workflow applies to any project that has run [`project-knowledge-harness`'s `init.sh`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md).

## Three ways to add a TODO

| Method                      | Best for                                                     | Validation                                    |
| --------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| **`scripts/add-todo.sh`**   | Structured items where you know priority + effort            | Enforced — refuses to write a malformed entry |
| **`backlog/inbox.md`**      | Quick captures from the maintainer; "I'll triage this later" | None — formalized later by `sweep-inbox.sh`   |
| **Edit `TODO.md` directly** | Bulk import; agents that are happy following the format spec | Run `make kanban` after to catch drift        |

`add-todo.sh` and the inbox sweeper are bundled with the [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) skill and mirrored into the top-level [`scripts/`](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md).

### Method 1 — `scripts/add-todo.sh`

```
./scripts/add-todo.sh \
  --priority P3 \
  --effort M \
  --title "Add docs versioning" \
  --description "Use mike for versioned docs"

# P? items use --unknown-priority; effort can also be unknown:
./scripts/add-todo.sh \
  --priority "P?" \
  --effort "?" \
  --title "Try Rspress for docs" \
  --description "Evaluate AI-native docs framework alternative"

# Add a backlog research doc at the same time
./scripts/add-todo.sh \
  --priority P2 \
  --effort L \
  --title "Migrate kanban to Python" \
  --description "Bash 3.2 compat is getting expensive" \
  --backlog
```

What it does:

1. Builds the canonical line for the chosen lane.
1. Inserts it under the matching `## P?` heading in `TODO.md`.
1. If `--backlog` is set, scaffolds `backlog/<slug>.md` from the skill's `assets/backlog-doc.md.template` and appends `→ [research](backlog/<slug>.md)` to the new TODO line.
1. Re-runs the validator. If validation fails, the original `TODO.md` is restored.

See [`scripts/add-todo.sh --help`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#add-todosh) for the full flag list.

### Method 2 — `backlog/inbox.md`

For loose captures where you don't yet know the priority or effort:

```
echo "- maybe add docs versioning with mike" >> backlog/inbox.md
echo "- the find-skills bootstrap UX is rough" >> backlog/inbox.md
```

Anything goes in `inbox.md` — free-form prose, dashed lists, half-thoughts. The validator does **not** look at this file.

When you (or an agent) are ready to triage, run:

```
./scripts/sweep-inbox.sh
```

The sweeper reads `inbox.md` line by line, prompts for the priority / effort / formal title / description for each one, calls `add-todo.sh`, and removes the line from the inbox once it's been formalized. Use `--dry-run` to preview without mutating either file.

If you're working with an agent, the easier path is to ask it: *"sweep the inbox"* or *"clear `backlog/inbox.md`"*. The [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) SKILL.md instructs the agent to invoke `sweep-inbox.sh` and to ask the maintainer for the missing fields one item at a time.

### Method 3 — edit `TODO.md` directly

Sometimes the fastest path. The format is small enough to memorize:

```
## P2

- [ ] **[M] Title here** — description goes after the em-dash

## P?

- [ ] **[?/L] Unsure-priority item** — description
```

After editing, run `make kanban` (or `./scripts/todo-kanban.sh --validate-only`) to catch typos before committing. The full grammar lives in [Reference → TODO format](https://daviddwlee84.github.io/agent-skills/reference/todo-format/index.md).

## Promoting a finished item

When you ship a TODO item, in the same commit:

```
./scripts/promote-todo.sh \
  --title "<substring of the item's title>" \
  --summary "<one-line shipped summary>"
```

This atomically moves the matched active item into `## Done` with the dated `Done` syntax and re-validates. It refuses to run if the substring matches zero or more than one active item, so refine the substring if it errors out.

If a `backlog/<slug>.md` exists for the item, set its `Status: shipped` in the same commit — don't delete it. Historical research often informs adjacent decisions.

## When to write a `backlog/` doc

Write `backlog/<slug>.md` when the conversation produced something worth re-reading later: research notes, design trade-offs, error traces from a failed spike, vendor comparison tables. The TODO line is the *index*; the backlog doc is the *content*.

A useful filter: *"if I came back to this in three months with no memory, would the TODO line alone be enough?"* If no, write the backlog doc.

The skill's [`references/when-to-add-docs.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/when-to-add-docs.md) has the full decision tree.

## When to write a `pitfalls/` doc

Write `pitfalls/<symptom-slug>.md` immediately after debugging something non-obvious that could plausibly happen again. The title should be the **symptom** (what you typed into a search bar), not the root cause.

Copy verbatim error messages — never paraphrase, it kills grep-ability.

If the trap is severe (silent data corruption, cross-machine recurrence, non-obvious workaround), graduate it to a Hard invariant in `AGENTS.md` / `CLAUDE.md`. The pitfall doc stays as the historical record; the invariant is the rule that prevents recurrence.
# Skills

# Skills overview

This page indexes the skills bundled in this repo.

- **Local skills** (`skills/local/`) are authored and maintained here.
- **Owned skills** (`skills/owned/`) are first-party skills maintained in another project and synced here for distribution; see [the workflow](https://daviddwlee84.github.io/agent-skills/workflows/adding-owned-skills/index.md).
- **Vendored skills** (`skills/vendor/`) are cherry-picked from upstream repos and synced via the [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml) manifest — see [Adding vendor skills](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/index.md). Do not edit vendored SKILL.md files locally; changes will be clobbered on the next `make sync`.

## Local skills

Custom-authored, curated to this repo's conventions (see [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md)).

| Skill                                                                                                                          | One-line                                                                                                                                                                                                                            | Detailed page                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md)           | TODO + backlog + pitfalls structure with a bundled validator/init/promote toolkit                                                                                                                                                   | [docs](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md)      |
| [`quantatitive-factor-researcher`](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md) | Quantitative factor research persona for Python-based strategy work                                                                                                                                                                 | [docs](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md) |
| [`vectorbt`](https://daviddwlee84.github.io/agent-skills/skills/vectorbt/index.md)                                             | OSS/PRO library development, XDG documentation synchronization, and optional MCP                                                                                                                                                    | [docs](https://daviddwlee84.github.io/agent-skills/skills/vectorbt/index.md)                       |
| [`nautilus-trader`](https://daviddwlee84.github.io/agent-skills/skills/nautilus-trader/index.md)                               | v1 Cython / v2 Rust-PyO3 generation detection, version-matched docs cache, event-driven backtests, and live-trading gates                                                                                                           | [docs](https://daviddwlee84.github.io/agent-skills/skills/nautilus-trader/index.md)                |
| [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md)                                     | Author new skills following agentskills.io best practices; ships `new-skill.sh` and `lint-skill.sh`                                                                                                                                 | [docs](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md)                   |
| [`verifiable-surfaces`](https://daviddwlee84.github.io/agent-skills/skills/verifiable-surfaces/index.md)                       | Design verifiable CLI/tool/service surfaces (`--help`/`--dry-run`/`--print-config`/isolated smoke) and verify config changes via app-native loaders                                                                                 | [docs](https://daviddwlee84.github.io/agent-skills/skills/verifiable-surfaces/index.md)            |
| [`12-factor-agent-design-review`](https://daviddwlee84.github.io/agent-skills/skills/12-factor-agent-design-review/index.md)   | Design or evidence-review production LLM applications across prompts, context, typed tools, durable state, owned control flow, pause/resume, humans, retries, and replay                                                            | [docs](https://daviddwlee84.github.io/agent-skills/skills/12-factor-agent-design-review/index.md)  |
| [`openui-direct-provider`](https://daviddwlee84.github.io/agent-skills/skills/openui-direct-provider/index.md)                 | Build OpenUI generative UI on your own model provider (no Gateway); provider-neutral companion to vendored `openui`                                                                                                                 | [docs](https://daviddwlee84.github.io/agent-skills/skills/openui-direct-provider/index.md)         |
| [`demo-evidence`](https://daviddwlee84.github.io/agent-skills/skills/demo-evidence/index.md)                                   | Capture acceptance evidence (screenshots/recordings/HTTP logs) into a gitignored `.evidence/` bundle keyed to git branch/commit + agent session, for async "Demos over diffs" review                                                | [docs](https://daviddwlee84.github.io/agent-skills/skills/demo-evidence/index.md)                  |
| [`mkdocs-site-bootstrap`](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md)                   | Bootstrap a MkDocs Material site + GitHub Pages deploy; consent-gated with `.skills/preferences.yaml`                                                                                                                               | [docs](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md)          |
| [`zensical-site-bootstrap`](https://daviddwlee84.github.io/agent-skills/skills/zensical-site-bootstrap/index.md)               | English Zensical pilot with safe initialization, native LLM exports, and build-only CI                                                                                                                                              | [docs](https://daviddwlee84.github.io/agent-skills/skills/zensical-site-bootstrap/index.md)        |
| [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md)                       | marimo dual-mode (UI + batch CLI) notebooks with Tyro + MLflow                                                                                                                                                                      | [docs](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md)            |
| [`dvc-ml-workflow`](https://daviddwlee84.github.io/agent-skills/skills/dvc-ml-workflow/index.md)                               | DVC pipelines + queued experiments with metrics auto-bound to ephemeral commits; ships init/queue/lint helpers                                                                                                                      | [docs](https://daviddwlee84.github.io/agent-skills/skills/dvc-ml-workflow/index.md)                |
| [`mlflow-tracking`](https://daviddwlee84.github.io/agent-skills/skills/mlflow-tracking/index.md)                               | Generic MLflow skill — sqlite + `mlflow ui`, vendored PostgreSQL + MinIO docker stack, LLM tracing, registry, autolog                                                                                                               | [docs](https://daviddwlee84.github.io/agent-skills/skills/mlflow-tracking/index.md)                |
| [`agent-history-hygiene`](https://daviddwlee84.github.io/agent-skills/skills/agent-history-hygiene/index.md)                   | Commit transcripts/plans with feature diffs, derive staged harness/model provenance, bootstrap secret scanning, and apply rotate-first leak remediation                                                                             | [docs](https://daviddwlee84.github.io/agent-skills/skills/agent-history-hygiene/index.md)          |
| [`git-workflow`](https://daviddwlee84.github.io/agent-skills/skills/git-workflow/index.md)                                     | Scale-aware Git workflow with English Conventional Commits, cross-harness AI provenance, linear history, worktrees, SemVer, and commit validation                                                                                   | [docs](https://daviddwlee84.github.io/agent-skills/skills/git-workflow/index.md)                   |
| [`superproject-workspace`](https://daviddwlee84.github.io/agent-skills/skills/superproject-workspace/index.md)                 | Keep a git-submodule superproject from drifting — per-child track/pin/lazy policy in `.gitmodules`, lag/drift status, preflighted one-commit bumps, scheduled bump PRs, child worktrees, audit/adopt                                | [docs](https://daviddwlee84.github.io/agent-skills/skills/superproject-workspace/index.md)         |
| [`pueue-job-queue`](https://daviddwlee84.github.io/agent-skills/skills/pueue-job-queue/index.md)                               | Drive Nukesor/pueue for queued/parallel/scheduled shell jobs; submit-one + DAG submitter + JSON-summary waiter; observed pueue 4.0.2 schema                                                                                         | [docs](https://daviddwlee84.github.io/agent-skills/skills/pueue-job-queue/index.md)                |
| [`slurm-hpc`](https://daviddwlee84.github.io/agent-skills/skills/slurm-hpc/index.md)                                           | Portable Slurm know-how — sbatch skeleton, resource requests, job chaining (`--dependency=afterok` + the DependencyNeverSatisfied trap), and what actually fences GPU VRAM (shard vs MPS vs MIG)                                    | [docs](https://daviddwlee84.github.io/agent-skills/skills/slurm-hpc/index.md)                      |
| [`long-running-jobs`](https://daviddwlee84.github.io/agent-skills/skills/long-running-jobs/index.md)                           | How an agent should wait for work outlasting a turn — scheduler-owned chaining, one blocking backgrounded wait, filtered event streams, scheduled check-ins last; durable exit-code markers via `run-and-mark.sh` + `check-runs.sh` | [docs](https://daviddwlee84.github.io/agent-skills/skills/long-running-jobs/index.md)              |
| [`experiment-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/experiment-knowledge-harness/index.md)     | Research memory for ML/Quant — LEDGER of overturnable findings, payoff-triaged ROADMAP, pre-registered REPORTs with single-axis ablation contract, auto-rendered Mermaid map                                                        | [docs](https://daviddwlee84.github.io/agent-skills/skills/experiment-knowledge-harness/index.md)   |
| [`clash-proxy-api`](https://daviddwlee84.github.io/agent-skills/skills/clash-proxy-api/index.md)                               | Discover & drive a Clash/mihomo external-controller: status/mode/TUN/switch/reload/connections + OS system-proxy toggle; multi-client (Verge Rev, ClashX, mihomo CLI) with enable-the-API guidance                                  | [docs](https://daviddwlee84.github.io/agent-skills/skills/clash-proxy-api/index.md)                |
| [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md)                       | Production FastAPI patterns + gotchas for AI/ML/LLM serving; `def`/`async` decision table + 8 references over all 10 chapters                                                                                                       | [docs](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md)            |
| [`fastapi-ai-scaffold`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-scaffold/index.md)                       | Generate a production-shaped FastAPI AI service (clean architecture, lifespan model, JWT, SSE, probes, tests, Docker); `new-fastapi-ai-service.sh` + 44-file skeleton                                                               | [docs](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-scaffold/index.md)            |
| [`fastapi-ai-interview-prep`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-interview-prep/index.md)           | 100 self-written FastAPI/AI interview Q&A across 10 topics + a `quiz.py` mock-interview CLI                                                                                                                                         | [docs](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-interview-prep/index.md)      |
| [`raycast-extension-dev`](https://daviddwlee84.github.io/agent-skills/skills/raycast-extension-dev/index.md)                   | Build/verify/ship Raycast extensions — the launchd PATH trap, the typecheck `ray build` skips, `MenuBarExtra` constraints, and the store checks `ray lint` never runs; ships a scaffolder + readiness checker                       | [docs](https://daviddwlee84.github.io/agent-skills/skills/raycast-extension-dev/index.md)          |
| [`python-project-best-practice`](https://daviddwlee84.github.io/agent-skills/skills/python-project-best-practice/index.md)     | Modern Python project conventions — uv + src layout, Tyro CLIs, loguru, ruff/type/pytest behind a Justfile, an AGENTS.md docs-drift gate; ships a six-profile scaffolder and a 26-check read-only legacy audit                      | [docs](https://daviddwlee84.github.io/agent-skills/skills/python-project-best-practice/index.md)   |

## Owned skills

| Skill                                                                                  | Canonical project                                                            | Detailed page                                                                              |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`go-cli-tui`](https://daviddwlee84.github.io/agent-skills/skills/go-cli-tui/index.md) | [awesome-lazy-tools](https://github.com/daviddwlee84/awesome-lazy-tools)     | [docs](https://daviddwlee84.github.io/agent-skills/skills/go-cli-tui/index.md)             |
| `userscript-development`                                                               | [Tampermonkey-Scripts](https://github.com/daviddwlee84/Tampermonkey-Scripts) | [docs](https://daviddwlee84.github.io/agent-skills/skills/userscript-development/index.md) |

## Vendored skills

3rd-party skills cherry-picked because they fill a gap the local skills don't cover, or because the upstream is the canonical authority on the topic. The linked detail page shows what each skill teaches, upstream provenance, and last-sync commit is tracked in `vendor.yaml`.

Vendored skills can be **flat** (`skills/vendor/<name>/`) or grouped into a **series** (`skills/vendor/<series>/<name>/`). See [Adding vendor skills](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/#series-grouping) for how series work.

### Flat (notebooks + meta)

| Skill                                                                                                    | Upstream                                                                                                              | Detailed page                                                                           |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`marimo-notebook`](https://daviddwlee84.github.io/agent-skills/skills/marimo-notebook/index.md)         | [marimo-team/skills](https://github.com/marimo-team/skills/tree/main/skills/marimo-notebook)                          | [docs](https://daviddwlee84.github.io/agent-skills/skills/marimo-notebook/index.md)     |
| [`streamlit-to-marimo`](https://daviddwlee84.github.io/agent-skills/skills/streamlit-to-marimo/index.md) | [marimo-team/skills](https://github.com/marimo-team/skills/tree/main/skills/streamlit-to-marimo)                      | [docs](https://daviddwlee84.github.io/agent-skills/skills/streamlit-to-marimo/index.md) |
| [`anywidget`](https://daviddwlee84.github.io/agent-skills/skills/anywidget/index.md)                     | [marimo-team/skills](https://github.com/marimo-team/skills/tree/main/skills/anywidget)                                | [docs](https://daviddwlee84.github.io/agent-skills/skills/anywidget/index.md)           |
| [`skill-creator`](https://daviddwlee84.github.io/agent-skills/skills/skill-creator/index.md)             | [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/skill-creator)                              | [docs](https://daviddwlee84.github.io/agent-skills/skills/skill-creator/index.md)       |
| [`herdr`](https://daviddwlee84.github.io/agent-skills/skills/herdr/index.md)                             | [herdrdev/herdr](https://github.com/herdrdev/herdr/tree/master/skills/herdr)                                          | [docs](https://daviddwlee84.github.io/agent-skills/skills/herdr/index.md)               |
| [`security-audit`](https://daviddwlee84.github.io/agent-skills/skills/security-audit/index.md)           | [cloudflare/security-audit-skill](https://github.com/cloudflare/security-audit-skill/tree/main/skills/security-audit) | [docs](https://daviddwlee84.github.io/agent-skills/skills/security-audit/index.md)      |
| [`openui`](https://daviddwlee84.github.io/agent-skills/skills/openui/index.md)                           | [thesysdev/skills](https://github.com/thesysdev/skills/tree/main/skills/openui)                                       | [docs](https://daviddwlee84.github.io/agent-skills/skills/openui/index.md)              |

### Fullstack Next.js series

`series: fullstack-nextjs` — Next.js (App Router) + Supabase (Postgres) + shadcn/ui + Tailwind CSS + design/testing skills. All from official orgs (Vercel, vercel-labs, Supabase, Anthropic).

| Skill                                                                                                                              | Upstream                                                                                                            | Detailed page                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md)                                                     | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin/tree/main/skills/nextjs)                             | [docs](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md)                           |
| [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md)                                                     | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin/tree/main/skills/shadcn)                             | [docs](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md)                           |
| [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md)                         | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin/tree/main/skills/react-best-practices)               | [docs](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md)             |
| [`vercel-storage`](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md)                                     | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin/tree/main/skills/vercel-storage)                     | [docs](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md)                   |
| [`supabase`](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md)                                                 | [supabase/agent-skills](https://github.com/supabase/agent-skills/tree/main/skills/supabase)                         | [docs](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md)                         |
| [`supabase-postgres-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/supabase-postgres-best-practices/index.md) | [supabase/agent-skills](https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices) | [docs](https://daviddwlee84.github.io/agent-skills/skills/supabase-postgres-best-practices/index.md) |
| [`web-design-guidelines`](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md)                       | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines)      | [docs](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md)            |
| [`frontend-design`](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md)                                   | [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/frontend-design)                          | [docs](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md)                  |
| [`webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md)                                     | [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/webapp-testing)                           | [docs](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md)                   |

For the rules every local skill follows (layout, naming, scripts, references), see [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md). For how vendoring works end-to-end, see [Adding vendor skills](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/index.md).

# 12-factor-agent-design-review

Design or review production LLM applications using HumanLayer's [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) as an evidence-first engineering lens. The skill supports a greenfield **Design** mode, an evidence-backed **Review** mode, and a **Mixed** mode that reviews the current system before proposing a target architecture.

It is intentionally not a compliance scorer or project scaffolder.

## Recommended use cases

| Scenario                                    | Mode             | Why this skill fits                                                                                                                            |
| ------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Design a new customer-facing LLM workflow   | Design           | Makes the LLM/code boundary, typed decisions, durable state, pause/resume, retries, and verification explicit before framework choices harden. |
| Production-readiness architecture review    | Review           | Requires file/line or document evidence for each verdict and connects gaps to user-visible failure modes.                                      |
| Migrate away from framework-owned behavior  | Mixed            | Preserves working pieces, identifies which prompts/context/state/control-flow decisions are hidden, then defines a controlled target state.    |
| Build async or human-in-the-loop workflows  | Design or Review | Covers durable approval requests/responses, callbacks, timeouts, cancellation, idempotency, resume, and replay.                                |
| Investigate an agent that is "stuck at 80%" | Review           | Examines systemic boundaries such as context growth, unbounded retries, hidden state, and unvalidated model outputs.                           |

## Suitable with limitations

- **Incident diagnosis:** use it after reproducing the failure to find the architectural cause. It does not replace logs, traces, or runtime debugging.
- **Security-sensitive agents:** it identifies where model output reaches a high-risk effect, but a dedicated threat model and security review are still required.
- **Model quality problems:** it verifies context, prompt ownership, eval, and replay surfaces; it does not benchmark model accuracy by itself.
- **Implementation planning:** it can define interfaces and acceptance checks, but framework-specific code generation belongs to a separate implementation or scaffold workflow.

## Do not use it for

- ordinary [Twelve-Factor App](https://12factor.net/) deployment/configuration;
- rewriting one prompt when no application architecture is changing;
- comparing model prices, latency, benchmarks, or provider features;
- generic code review of software with no LLM decision boundary;
- generating a runnable starter project or selecting a framework solely from a feature checklist.

## What the skill produces

### Design mode

- system boundary and non-goals;
- LLM vs deterministic code vs human decision table;
- trigger/event/context/model/validation/handler/state flow;
- factor relevance and design decisions with acceptance checks;
- typed tool, state, human-response, failure, eval, and observability contracts;
- dependency-aware implementation sequence.

### Review mode

- inspected scope and evidence coverage;
- per-factor `Strong / Partial / Gap / N/A / Unverified` findings;
- consequence-based severity independent of factor number;
- strengths worth preserving;
- smallest remediation sequence and concrete verification steps.

The skill never emits a "12-factor compliance percentage." Factor 13 (pre-fetch context) is always labeled as an appendix extension rather than a canonical thirteenth factor.

## Example prompts

```
Design a refund-support agent for FastAPI + Postgres. It starts from email and
Slack, can refund up to $500 automatically, needs human approval above that,
and must resume safely after a worker restart.
```

```
Review src/agent/ and docs/refund-workflow.md against 12-Factor Agents. Cite
file:line evidence, distinguish gaps from unverified behavior, and prioritize
the smallest production-readiness fixes.
```

```
Our LangGraph workflow works in demos but loops on tool errors and cannot resume
after approvals. Review the current design first, then propose a target design
without assuming we must remove LangGraph.
```

## Sources and extensions

The canonical factor intent comes from HumanLayer. Conditional references also record useful ideas and limitations from:

- [`existential-birds/beagle@agent-architecture-analysis`](https://github.com/existential-birds/beagle/tree/main/plugins/beagle-analysis/skills/agent-architecture-analysis) — evidence gates, without its Python-specific implementation rubric;
- [`tika/12-factor-agent-skills`](https://github.com/tika/12-factor-agent-skills) — workflow decomposition, without its cross-skill dependency and scanner;
- [Adnan Masood's enterprise analysis](https://medium.com/@adnanmasood/12-factor-agents-framework-for-reliable-llm-agents-empirical-guidelines-for-scalable-auditable-4b758e0e7979) — auditability and idempotency lens;
- [HumanLayer Discussion #61](https://github.com/humanlayer/12-factor-agents/discussions/61) — scaffolding, observability, eval, and failure-mode handoff ideas.

## Canonical SKILL.md

See [skills/local/12-factor-agent-design-review/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/12-factor-agent-design-review/SKILL.md) for the full workflow, gotchas, templates, and conditional reference rules.

# agent-history-hygiene

Keep coding-agent chat transcripts and plan files in the same commit as the feature diff they produced, without leaking `.env` contents or API keys into Git history.

| Surface                        | Question it answers                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------- |
| `run-specstory-session.sh`     | "How do I give the recorder a provable end-of-session boundary?"                         |
| `queue-agent-commit.sh`        | "How does the live agent request one later commit without touching its transcript?"      |
| `finalize-agent-commit.sh`     | "How is that exact request sanitized, attributed, and committed after the writer exits?" |
| `find-session.sh`              | "Which transcript / plan file is *my* current session?"                                  |
| `stage-agent-artifacts.sh`     | "Which exact agent files belong in the prepared commit?"                                 |
| `agent-commit-metadata.sh`     | "Which harness/model and artifact trailers belong in it?"                                |
| `bootstrap-project.sh`         | "How do I install validation-only artifact hooks and secret scanners?"                   |
| `scan-staged.sh`               | "Is there a leaked secret in what I am about to commit?"                                 |
| `probe-specstory-redaction.py` | "What does SpecStory already redact, so we do not redo it?"                              |
| `references/remediation.md`    | "I already pushed a secret — now what?"                                                  |

The skill prevents four common failure modes:

1. Agents silently **drop** `.specstory/history/*.md` and plan files because they look generated.
1. A transcript captures a credential and sends it into Git history.
1. Pre-commit or a formatter rewrites a transcript while SpecStory is still writing it, then restores or checks out stale bytes over newer history.
1. A failed commit is retried through LazyGit or the CLI even though the first attempt may already have succeeded.

## Lifecycle invariant

A live transcript is not a normal source file. The safe boundary is:

1. **Record:** start one foreground SpecStory/Claude session in the target worktree. Stage only the intended feature snapshot while that session runs.
1. **Queue:** the agent records an inert request naming the exact session, rendered transcript, optional plan, staged tree, and base commit message. Queueing never reads, stages, sanitizes, or commits the live transcript.
1. **Exit:** after the request is accepted, the agent performs no more repository or index operations and exits. A signal or nonzero child exit retains the request but grants no finalization authority.
1. **Synchronize:** only after a normal child exit does the outer runner render the exact session and prove that synchronization completed.
1. **Finalize:** a parent-authorized finalizer revalidates the worktree, branch, HEAD, staged tree, selectors, absence of a writer, and absence of an active Git operation. It then stages and sanitizes the exact artifacts atomically, derives provenance from the prepared index, validates the message, and invokes one ordinary commit.
1. **Continue:** rebase, pull, switch, worktree removal, or a manual handoff may begin only after the finalizer proves `committed` or `already_committed`.

This preserves feature-plus-transcript same-commit semantics without asking a hook to mutate files at the least stable point in their lifecycle.

## Structure

```
skills/local/agent-history-hygiene/
├── SKILL.md
├── scripts/
│   ├── run-specstory-session.sh              # foreground lifecycle owner
│   ├── queue-agent-commit.sh                 # inert exact commit request
│   ├── finalize-agent-commit.sh              # quiescent one-shot finalizer
│   ├── find-session.sh                       # exact session discovery
│   ├── stage-agent-artifacts.sh              # atomic exact artifact preparation
│   ├── agent-commit-metadata.sh              # staged provenance trailers
│   ├── bootstrap-project.sh                  # validation/scanner bootstrap
│   ├── probe-specstory-redaction.py          # native coverage measurement
│   └── scan-staged.sh                        # staged gitleaks wrapper
├── references/
│   ├── transcript-session-discovery.md
│   ├── pre-commit-redaction-stack.md
│   ├── specstory-native-redaction.md
│   └── remediation.md
└── assets/
    ├── artifact-dirs.txt
    ├── pre-commit-config.yaml.template
    ├── gitleaks.toml.template
    └── redact_secrets.py                     # finalizer-only mutator
```

## Default workflow: finalize after the session

Launch the session from the target worktree. Parent authorization can permit one automatic finalizer call after a successful exit; without it, the runner still performs the exact post-exit sync and retains the request for explicit recovery.

```
# Parent shell: foreground recorder and lifecycle owner.
bash skills/local/agent-history-hygiene/scripts/run-specstory-session.sh \
  --allow-commit claude
```

Inside that agent session:

1. Stage the feature paths that belong in the commit.
1. Obtain the canonical session UUID and exact rendered transcript path; name the exact plan, or explicitly state that no plan exists.
1. Write the base subject/body to a message file. Do not pre-populate the lifecycle-managed provenance trailers.
1. Queue the commit request with `queue-agent-commit.sh` using those exact selectors and message.
1. Report `finalization queued` and exit immediately. Do not run `git add`, `git commit`, rebase, or another diagnostic that writes the repository.

Use each command's `--help` for its full selector and recovery flags. The important public contract is the boundary, not memorizing every low-level option.

The finalizer verifies that the staged feature tree is still the queued tree. It refuses stale HEAD/ref/index state, an active transcript writer, unrelated commit-message drafts, and active merge, cherry-pick, revert, bisect, rebase, sequencer, or index-lock state. A stale `REBASE_HEAD` file alone is not proof of an active rebase; `rebase-merge`, `rebase-apply`, and `sequencer` are active state.

### Commit before rebase

Finish and prove the feature-plus-history commit **before** rebasing it. Both a normal commit and a rebase can execute checkout/restore behavior in hooks or in Git itself, so neither is safe while a recorder can append to a tracked transcript. The ordering is:

```
stage feature → queue → exit recorder → exact sync → finalize and prove commit
→ rebase/pull/merge if needed → push or retire
```

Do not rebase a staged-but-unfinalized change, and do not treat a one-shot normal commit as safe merely because it snapshots the index once. A mutating pre-commit hook can still restore older working-tree bytes over a live write.

### LazyGit and CLI drafts are not retry authority

After preparing the exact tree and complete message, the finalizer writes matching private drafts for LazyGit and Git's CLI message location, then makes one ordinary commit attempt itself. It refuses to overwrite an unrelated or user-edited draft and avoids partial handoff.

Those drafts provide visibility and recovery context; they do **not** authorize a second commit path. Follow the bounded finalizer status:

- `committed` / `already_committed`: the exact parent, tree, and lifecycle trailer were proven; later Git operations may proceed.
- `commit_failed` with the exact prepared snapshot retained: fix the hook or dependency, then invoke the finalizer again with fresh explicit authorization. Do not click Commit in LazyGit or run a separate `git commit`.
- uncertain outcome, changed snapshot, or `commit_recovery_required`: reconcile HEAD and the private journal only. Never retry through LazyGit, raw Git, or the finalizer until the prior outcome is proven.
- `rotation_required`: rotate the exposed credential first, then use the explicit confirmed recovery path; prepared recovery does not restage.

## Validation-only hooks and mutator scope

`bootstrap-project.sh` installs a pinned validation-only agent-artifact check, gitleaks, and standard repository hygiene. The artifact check and scanners may inspect the staged snapshot but must never rewrite the index or working tree. Redaction is owned by the quiescent post-session finalizer.

Generic mutators—formatters, linter autofixes, codemods, `end-of-file-fixer`, and `trailing-whitespace`—must exclude every archival and skill-install root:

```
.agents  .claude  .codex  .cursor  .opencode  .specify  .specstory
```

Detection remains enabled for those roots. `.claude` must be excluded even when `.agents` is excluded because `.claude/skills/<name>` can symlink into the same installed tree. After the recorder itself, the finalizer is the sole sanctioned component that materializes sanitized transcript bytes, and it does so only after lifecycle quiescence.

The optional `prepare-commit-msg` integration is also validation-only. It checks explicit session identity against the commit's actual index, including temporary indexes used by normal Git modes, but never stages or repairs files. If `core.hooksPath` is configured—even to an empty, relative, or external value—bootstrap refuses automatic installation; integrate the check into the configured hook directory deliberately.

## Exact discovery and staging

`find-session.sh` is exact by default. It validates the SpecStory prologue, canonical lowercase UUID, direct non-symlink transcript path, strict Claude JSONL, and canonical worktree root. The same UUID can render more than one alias, so ambiguity requires an explicit transcript path; `--newest` is only a compatibility escape hatch.

`stage-agent-artifacts.sh` requires a non-artifact feature diff for the same-commit workflow. Preparation uses an alternate index under the real worktree index lock and publishes it atomically only on success. Validation mode never mutates an index. The finalizer uses the exact selector path; broad branch-wide staging remains compatibility mode, not the lifecycle default.

## SpecStory 2.10 checkout scoping

Rendered output and raw Claude-session discovery are scoped by **checkout path, not branch**. Switching branches in one checkout shares an artifact pool; separate worktrees have separate `.specstory/history/` roots and Claude project slugs.

Use **worktree first, recorder/session second**, with one SpecStory wrapper and Claude session per change stream. `EnterWorktree` does not rebind an existing watcher. Stop it and start the foreground runner in the target worktree.

## SpecStory native redaction (v2.4.0+)

SpecStory redacts on write by default using Betterleaks, covering local Markdown and cloud sync. The repository layer is still required because measured coverage is incomplete, especially for custom keys and webhook shapes in prose.

| Caught by             | Pairs (measured on 2.9.0) | Examples                                                  |
| --------------------- | ------------------------- | --------------------------------------------------------- |
| SpecStory             | 36 / 54                   | Major provider keys, PEM blocks, `.env` dumps             |
| Repository layer only | 15 / 54                   | Cursor, Tailscale, webhook and custom-key shapes in prose |
| Neither               | 3 / 54                    | Access-key IDs and a bot-token prose case                 |

Both layers use `[REDACTED:<rule-id>]`, and gitleaks allowlists that sentinel. The finalizer leaves bytes already sanitized by SpecStory unchanged. It never prints transcript, diff, scanner, or credential content to its bounded public output.

## Post-leak discipline

When any layer finds a real credential:

1. **Rotate it at the provider.** This is the only revocation action.
1. Assess whether it was staged, committed locally, pushed to a feature branch, or reached a shared branch.
1. Scrub history only when the rotate-first runbook says it is appropriate. Never use plain force-push on a shared branch.

See `references/remediation.md` before any history rewrite.

## Gotchas

- Never ignore `.specstory/` or `.specstory/history/` wholesale. Only machine-local identity and generated statistics are excluded precisely.
- A normal child exit and exact completed sync are lifecycle proof; possession of a request file is not commit authority.
- A live writer blocks artifact staging and commit preparation. Do not work around the guard with an ordinary commit or a pre-commit mutator.
- Branch names do not scope SpecStory discovery; checkout paths do.
- Native Claude/Cursor attribution is additive. The portable minimum is the final staged `AI-Assisted-By` plus transcript/plan block; message attribution is not cryptographic signing.
- A bare phrase discussing private keys is not key material. Shipped fixtures build scanner-sensitive headers at runtime rather than weakening scanner coverage.
- `pre-commit install` is per clone, and global `core.hooksPath` protects only repositories that actually carry the expected configuration.

## See also

- [Source](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/agent-history-hygiene)
- [Formatter rewrites committed agent transcripts](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/formatter-rewrites-committed-agent-transcripts.md)
- [Pre-commit restores over live SpecStory writes](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/pre-commit-restores-over-live-specstory-writes.md)
- [Rebase continue refuses on a clean index with a live transcript](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/rebase-continue-refuses-on-clean-index-live-transcript.md)
- [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) — complementary durable project memory; this skill supplies the Git lifecycle for agent review artifacts.

# anywidget (vendored)

Vendored from [marimo-team/skills/skills/anywidget](https://github.com/marimo-team/skills/tree/main/skills/anywidget). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/anywidget/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/anywidget/SKILL.md) locally — changes will be clobbered on the next sync.

> **Note on the runtime name:** the SKILL.md frontmatter declares `name: anywidget-generator`. Skill discovery uses the frontmatter name, not the directory name. The directory is kept as `anywidget/` to mirror the upstream path.

## What it teaches

Generating [anywidget](https://anywidget.dev/) components for marimo notebooks:

- Vanilla JavaScript in `_esm` with a `render({ model, el })` function.
- `_css` styling that works in both light and dark mode (via `@media (prefers-color-scheme: dark)`).
- The `model.get` / `model.set` / `model.save_changes` pattern for syncing state between Python (`traitlets.Int(0).tag(sync=True)`) and JS.
- Wrapping for marimo display: `widget = mo.ui.anywidget(MyWidget())`.
- Reading `_esm` / `_css` from external files via `pathlib` when the widget grows large.

## Quick example

```
import anywidget
import traitlets
import marimo as mo

class CounterWidget(anywidget.AnyWidget):
    _esm = """
    function render({ model, el }) {
      let count = () => model.get("number");
      let btn = document.createElement("button");
      btn.innerHTML = `count is ${count()}`;
      btn.addEventListener("click", () => {
        model.set("number", count() + 1);
        model.save_changes();
      });
      model.on("change:number", () => {
        btn.innerHTML = `count is ${count()}`;
      });
      el.appendChild(btn);
    }
    export default { render };
    """
    _css = "button { font-size: 14px; }"
    number = traitlets.Int(0).tag(sync=True)

widget = mo.ui.anywidget(CounterWidget())
widget
```

Then from another cell, `widget.value["number"]` gives you the current count.

## Related skills

- [`marimo-notebook`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/marimo-notebook/SKILL.md) — general marimo authoring (vendored from marimo-team).
- [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) — uses `mlflow-widgets` (an anywidget-based MLflow component library) for live training charts; this skill is what you'd reach for if you needed to build a custom variant.

## Canonical SKILL.md

See [skills/vendor/anywidget/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/anywidget/SKILL.md) for the full triggering description and best-practices section.

# clash-proxy-api

Discover and drive a running **Clash / mihomo** proxy through its external-controller REST API — from natural-language requests like "what's my node?", "switch to the JP node", "go global mode", "turn on TUN", "reload my config", or "the proxy API isn't reachable". Bundled scripts wrap the controller API and the OS system proxy; references cover enabling the API per client and the raw endpoint surface.

| Surface                                           | Question it answers                                                                                                             |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `clash_api.py doctor`                             | "Is the controller reachable, and if not, which client do I enable the API on?"                                                 |
| `clash_api.py status`                             | "What's my current node, mode, TUN state, ports, and groups?"                                                                   |
| `clash_api.py switch/mode/tun/reload/connections` | "Change the live proxy: pick a node, set rule/global/direct, toggle TUN, reload, close connections."                            |
| `clash_api.py delay/group-delay/proxies/rules`    | "Test latency, list nodes/rules."                                                                                               |
| `clash_sysproxy.sh`                               | "Toggle the OS system proxy where the client has no toggle (mihomo CLI, headless, Ubuntu)."                                     |
| `references/enable-api-by-client.md`              | "How do I turn on the API / find its address on Verge Rev / ClashX / mihomo? Where are System Proxy, TUN, Service Mode, Mixin?" |
| `references/api-endpoints.md`                     | "What endpoint do I curl for `/traffic`, `/providers`, `/dns/query`…?"                                                          |

The skill's whole point is to **not hardcode assumptions**. Controller discovery tries `--controller`/`--secret` → `CLASH_CONTROLLER`/`CLASH_SECRET` env → an optional Television hook → local config files → probes `127.0.0.1:9090` then `:9097` (Clash Verge Rev). First reachable wins. The proxy port is read from live config, not assumed to be `7890`.

## When the skill triggers

- "What node/mode am I on?" → `status`. "Switch PROXY to the Japan node" → `delay` then `switch`.
- "Go global / rule / direct mode" → `mode`. "Turn TUN on" → `tun on --restart`.
- "Reload my config", "close all connections", "what's my egress IP" → `reload` / `connections` / `egress`.
- "Is the Clash API on? / it's broken" → `doctor`, then the enable-API reference.
- "There's no system-proxy toggle on my Ubuntu box" → `clash_sysproxy.sh`.
- The user mentions Clash, mihomo, Clash Verge (Rev), ClashX, external-controller, `9090`/`9097`, or a node by name.

## When it doesn't

- Hand-editing subscription/rule YAML — the API reloads and toggles, it doesn't author config. Use the policy repository and the client deployment workflow.
- **Mixin / Merge** config — a client-side config-file feature (Clash Verge / CFW), not a runtime API. The skill guides; it doesn't script it.
- Buying/choosing nodes or managing subscriptions.

## Structure

```
skills/local/clash-proxy-api/
├── SKILL.md                        # intent→command map + gotchas
├── scripts/
│   ├── clash_api.py                # stdlib-only Python 3; controller API client
│   └── clash_sysproxy.sh           # bash 3.2; OS system-proxy toggle
├── references/
│   ├── enable-api-by-client.md     # per client×OS: enable API, System Proxy, TUN, Service Mode, Mixin
│   └── api-endpoints.md            # full endpoint catalog + raw curl recipes
└── agents/openai.yaml              # OpenAI-style launcher descriptor
```

## Design highlights

- **`clash_api.py` is stdlib-only** — no `uv`, no pip. It runs anywhere `python3` is present, which is the realistic downstream case. PyYAML is used if importable, else a small regex scanner reads the two config keys it needs.
- **Every write supports `--dry-run`**; destructive `connections close --all` requires `--yes`; secrets are never printed (`status` says `secret: yes/no`).
- **Exit codes branch retry behavior**: `0` ok, `1` usage, `2` group/proxy not found (message lists the real members), `3` controller unreachable, `4` op rejected. `clash_sysproxy.sh`: `0/1/2/3`.
- **Three-layer model** — controller API (reliable), enable/discover (when the API is off), OS/client toggles the API can't do (System Proxy, Service Mode, Mixin).

## Gotchas the skill encodes

- The controller is **not always `127.0.0.1:9090`** (Verge Rev is `9097`; GUIs pick random ports; routers are on the LAN) — always discover.
- The proxy port is **not always `7890`** — derive it from `status` → ports.
- **Enabling TUN via the API needs an elevated core** (Service Mode / root) and usually a `POST /restart`; a bare `PATCH` returns 204 but doesn't route.
- **System Proxy is an OS setting, not an API concept** — use the client toggle or `clash_sysproxy.sh`.
- `group-delay` / `/providers` / `/restart` are **mihomo-only** (404 on classic Premium cores).

## Verification

```
bash skills/local/skill-author/scripts/lint-skill.sh skills/local/clash-proxy-api
python3 skills/local/clash-proxy-api/scripts/clash_api.py doctor                     # discover + diagnose
python3 skills/local/clash-proxy-api/scripts/clash_api.py status                     # against a live controller
bash   skills/local/clash-proxy-api/scripts/clash_sysproxy.sh detect                 # read-only OS proxy state
```

Read commands are safe against a live controller; write commands (`switch`, `mode`, `tun`, `reload`, `connections close`) preview with `--dry-run`.

## Bounded diagnosis and managed routers

Use `--controller https://HOST:PORT --ca-cert PATH --secret-file PATH --read-only` for an explicit TLS target. Certificate and hostname validation remain enabled; redirects and environment proxies are disabled for controller requests. An explicit target never falls back to a local controller. Remote `egress` needs `--proxy`.

`observe DOMAIN --client IP --duration 20` combines filtered connection snapshots with routing logs. JSON includes core version, timestamps, matched rule, original chain order, collection warnings and an evidence state. It does not open the site, prove application success, or reconstruct past traffic; reports are private metadata.

For Nikki on the managed Pi, use the project `just diagnose-site` wrapper, which also checks client routes and binds the observation to the confirmed profile. Use device transactions for changes. See the skill's `references/managed-router-diagnosis.md` and the [policy knowledge base](https://github.com/daviddwlee84/clash-rules/blob/main/docs/diagnosis.md).

Transport and observation regression tests:

```
python3 -m unittest discover -s skills/local/clash-proxy-api/tests -v
```

# demo-evidence

Have an agent **leave behind acceptance evidence** — screenshots, screen/terminal recordings, HTTP logs — for a feature it just built, filed into a `.gitignore`-protected `.evidence/` tree, so a human (or a later agent) can validate the work asynchronously instead of reading the diff or booting the app by hand. This is the Cursor "Demos over diffs" idea, done locally and git-safe.

Each **bundle** is keyed to the coding-agent session that produced it and the git branch/commit at capture time, and self-describes via a `manifest.json` (machine-readable) + `MANIFEST.md` (human review page).

## Layout

```
.evidence/                                   # gitignored (root .gitignore entry)
  claude-5f932f43/                           # <agent>-<session>
    2026-07-07T11-11-29Z-6526681-login-flow/ # <UTC-ts>-<shortSHA>[-<title>]
      manifest.json
      MANIFEST.md
      login.png / login.webm / login-trace.zip
      run.log
      http/health.txt
```

## Lifecycle (three scripts)

1. **`new-bundle.sh`** — open a bundle: detect agent session + git branch/short-SHA/dirty, create the dir, scaffold manifests, guarantee `.evidence/` is gitignored, and record `.evidence/.current`.
1. **`capture.sh <web|term|http|screen>`** — add one artifact per surface and record it in `manifest.json`:
1. `web` → Playwright full-page screenshot + video + trace
1. `term` → asciinema recording (falls back to a tee'd log)
1. `http` → curl status + headers + body + timing
1. `screen` → ffmpeg screen recording (macOS avfoundation / Linux x11grab)
1. **`finalize.sh`** — stamp a verdict (`PASS`/`NEEDS_WORK`), append reproduction steps, refresh artifact sizes, optionally secret-scan text artifacts, and render the `MANIFEST.md` review page.

```
NB=skills/local/demo-evidence/scripts
BUNDLE=$(bash $NB/new-bundle.sh --title "login flow" --feature "login redirects to /dashboard" | jq -r .bundle_dir)
bash $NB/capture.sh term --cmd "mytool --demo" --name run
bash $NB/capture.sh http --url http://localhost:8000/health --name health
bash $NB/finalize.sh --verdict PASS --step "open /login" --step "submit creds" --scrub
```

## When to use / not use

Use it when the user wants **async 驗收 / sign-off** on an agent's work, says "record a demo", "leave evidence", "prove it works", or a reviewer asks "show me it works" without reading the diff. Skip it for changes with no runtime surface (docs, pure refactors covered by tests) — there's nothing to demo.

## Known limits (v1)

- **`.evidence/` media cannot embed in a GitHub PR** — a gitignored file has no public URL. PR posting (text manifest + gist-raw-URL image embed) is a tracked `P?` backlog item, out of scope for v1.
- **Screenshots/video can't be auto-scrubbed** for secrets — `finalize.sh --scrub` only reports on text artifacts via gitleaks; a human eyeballs the rest before sharing externally.
- **`capture.sh web` needs Node + Playwright** in the project; `screen` needs ffmpeg (+ macOS Screen Recording permission).

## Canonical SKILL.md

See [skills/local/demo-evidence/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/demo-evidence/SKILL.md) for the full triggering description, workflow, script flags/exit codes, and gotchas.

# dvc-ml-workflow

DVC ([Data Version Control](https://dvc.org/doc), upstream [treeverse/dvc](https://github.com/treeverse/dvc)) turns a git repo into a full ML lab: data and model files are versioned out-of-band, pipelines are declared in `dvc.yaml`, and experiments are run as **ephemeral git commits** with metrics and plots attached. No tracking server, no separate database — everything lives in your existing git history.

This skill is opinionated about the parts of DVC that matter for production ML work: pipelines, queued experiments with metrics auto-bound to commits, and remote storage. It defers to the official docs at [dvc.org/doc](https://dvc.org/doc) for everything else and links them inline.

> Iterative was acquired by Treeverse in 2024. `pip install dvc` resolves to [github.com/treeverse/dvc](https://github.com/treeverse/dvc) — the link redirects from the old `iterative/dvc`.

## What ships

- The full SKILL.md ([skills/local/dvc-ml-workflow/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/SKILL.md)) with a three-mode mental model (`add` / pipeline / `exp run`), a decision workflow, and a gotchas section calibrated to actual production failures.
- Four references — read on demand, not preloaded into context:
  - [`pipelines-and-stages.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/references/pipelines-and-stages.md) — `dvc.yaml` schema, `foreach` matrix stages, `frozen`, `always_changed`.
  - [`experiments-and-queue.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/references/experiments-and-queue.md) — `dvc exp run --queue`, `dvc queue start --jobs N`, ephemeral-commit semantics, `dvc exp apply` / `branch` / `gc`.
  - [`data-and-remotes.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/references/data-and-remotes.md) — S3 / GCS / Azure / SSH / GDrive / MinIO setup, credential handling.
  - [`plots-and-metrics.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/references/plots-and-metrics.md) — `dvc metrics diff`, plot templates, confusion matrices, VS Code extension.
- Three scripts:
  - [`init-dvc-project.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/scripts/init-dvc-project.sh) — idempotent `dvc init` + `.gitignore` + optional `dvc remote add` + drops the templates if missing.
  - [`queue-helper.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/scripts/queue-helper.sh) — agent-friendly wrapper around `dvc queue` with a `grid` subcommand that does cartesian-product enqueueing in one call. JSON stdout.
  - [`lint-dvcyaml.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/scripts/lint-dvcyaml.sh) — parse-only validator (`dvc dag --dot`), exits non-zero on schema errors without running any stage.
- Three templates in `assets/`: [`dvc.yaml.template`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/assets/dvc.yaml.template), [`params.yaml.template`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/assets/params.yaml.template), [`.dvcignore.template`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/dvc-ml-workflow/assets/.dvcignore.template).

## Why DVC (in one paragraph)

If you're already on git and want reproducibility without standing up a tracking server, DVC is hard to beat. The killer feature is that `dvc exp run --queue` + `dvc queue start --jobs N` runs a parameter sweep in parallel and **each completed run is a real commit** in `refs/exps/` with metrics, params, and outputs bundled — no separate database to correlate against. Promote one to a branch with `dvc exp apply`, garbage- collect the rest with `dvc exp gc`. The `dvc.yaml` pipeline format also gives you change-detection (`dvc repro` only re-runs stages whose deps changed), which `make` can't do for binary inputs.

## Quick start

```
# Initialize in current dir (in an existing git repo):
bash skills/local/dvc-ml-workflow/scripts/init-dvc-project.sh \
  --remote s3://my-bucket/dvc-store

# Edit the dvc.yaml + params.yaml templates, then:
dvc repro                                  # run the pipeline once
dvc exp run -S model.lr=1e-3              # try a different LR
dvc exp run --queue -S model.lr=5e-4      # queue a sweep entry
dvc queue start --jobs 4                  # parallel workers
dvc exp show                              # tabular comparison
```

## Cross-references

- Official docs: [dvc.org/doc](https://dvc.org/doc) — always link these, don't paraphrase from memory; DVC's CLI surface changes between minor versions.
- Upstream repo: [github.com/treeverse/dvc](https://github.com/treeverse/dvc).
- VS Code extension: [marketplace.visualstudio.com/items?itemName=Iterative.dvc](https://marketplace.visualstudio.com/items?itemName=Iterative.dvc) — adds a live experiments table, plot dashboard with parallel coordinates, and `dvc.yaml` schema validation in the editor.

# experiment-knowledge-harness

A file-based **research memory** for ML / DL / Quant projects. Sibling of `project-knowledge-harness`: that one remembers *engineering work*, this one remembers *what we believe and why*.

The problem it exists for: six months into a research project, nobody can answer "did we already try this?" — so the dead end gets re-run, and the GPU hours get spent twice.

| Surface                  | Question it answers                                        |
| ------------------------ | ---------------------------------------------------------- |
| `experiments/LEDGER.md`  | "What do we currently believe, and on what evidence?"      |
| `experiments/ROADMAP.md` | "What's worth running next, and why that order?"           |
| `experiments/INBOX.md`   | "Where do I dump a raw idea at 2am?"                       |
| `<NNN>-<slug>/REPORT.md` | "What exactly was run, under what spec, with what result?" |
| `experiments/README.md`  | Auto-rendered Mermaid map + index of everything            |

## The two ideas that make it work

**Findings are numbered and overturnable.** A finding is `F-007`, dated, tied to the experiment that produced it and a link to the evidence. When a later experiment contradicts it, `log-finding.py --overturns F-007` moves the old one to a graveyard lane with strikethrough — the history stays readable instead of being quietly edited away.

**Overturning a finding re-triages the queue.** ROADMAP items carry `depends-on: F-007`. When `F-007` falls, `retriage.py` lists every planned experiment resting on it and exits non-zero. Planned work that was justified by a belief you no longer hold gets flagged rather than silently executed.

## Pre-registration and the single-axis contract

Each REPORT is filled in **before running**:

- **Pre-registration** — hypothesis, success criteria, and a decision rule. If the decision rule's branches are identical, don't run the experiment. (That check alone kills a surprising number of experiments.)
- **One ablation axis**, declared in front-matter, compared against a *named* baseline.
- **Comparability spec** — every results table states the `spec:` (cost model, fee, eval-window version) it was produced under. Numbers from different specs never share a table.

[`references/anti-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/experiment-knowledge-harness/references/anti-patterns.md) names the failure modes this is defending against: HARKing, decision-less experiments, winner's curse, spec drift, and unwritten dead ends.

## During a long run

The harness covers *before* a run (pre-registration, triage) and *after* it (conclusion, findings, provenance). The window **during** a multi-day run is now covered too, because `status: running` is a note-to-self that nothing watches:

1. **The run writes a durable completion marker** — an atomic exit-code file, so a *later* session can tell "finished, exit 0" from "killed at 3am" without re-running GPU time. After a restart, reconcile every `status: running` REPORT against the actual markers rather than assuming.
1. **If the next experiment is already decided, chain it in the scheduler.** A `depends-on: #NNN` tag is documentation — it schedules nothing. When #008 genuinely runs after #007, submit it with a real dependency at the same time.

Explicitly *not* recommended: babysitting a long run with a self-rescheduling check-in that wakes, greps a log, finds nothing changed, and reschedules. See [`long-running-jobs`](https://daviddwlee84.github.io/agent-skills/skills/long-running-jobs/index.md).

## When the skill triggers

- "Have we tried X before?" / "別重複造輪子、別浪費算力"
- Recording which directions succeeded vs failed, so dead ends stay dead.
- Making results discoverable and comparable across months.
- Re-prioritizing planned work when a conclusion changes.
- "Give me the big picture of all experiments."
- Jotting a raw research idea, or sweeping the experiments inbox.

## When it doesn't

- A single ad-hoc calculation — no hypothesis, no experiment.
- Hypothesis-free engineering work → `TODO.md` / `project-knowledge-harness`.
- **Run-level metric streaming** → that's MLflow / W&B territory. This harness stores conclusions and references, not raw run telemetry.

## Structure

```
skills/local/experiment-knowledge-harness/
├── SKILL.md
├── scripts/
│   ├── init.sh                     # idempotent scaffold into a target repo
│   ├── new-experiment.py           # allocate #NNN, scaffold REPORT.md
│   ├── log-finding.py              # append F-NNN; --overturns moves the old one
│   ├── render-index.py             # validate all surfaces + rewrite Mermaid map
│   ├── sweep-inbox.py              # triage INBOX bullets into ROADMAP items
│   ├── retriage.py                 # flag items resting on overturned findings
│   ├── snapshot-provenance.py      # collect git SHA, versions, host, timestamp
│   └── _lib.py                     # shared stdlib-only parsers/validators
├── references/                     # report-format, ledger-format, tag-schema,
│                                   # provenance, when-to-log-what, anti-patterns
└── assets/                         # 6 templates incl. agent-guidance snippet
```

Everything is stdlib Python + bash 3.2 — deliberately harness-agnostic, so it works the same under Claude Code, Cursor, Codex, or a human.

## Reproducibility ladder

[`references/provenance.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/experiment-knowledge-harness/references/provenance.md) grades provenance rather than demanding perfection:

| Rung       | Meaning                                    |
| ---------- | ------------------------------------------ |
| Anecdote   | a number in a message                      |
| Recorded   | number + REPORT with a spec                |
| Replayable | + git SHA, config hash, data window, seeds |
| Pinned     | + environment and artifact paths           |

Default assumption is **no tracking server**. When run telemetry is worth keeping, it suggests a local SQLite MLflow backend so the store stays a single portable file.

## Validation

`render-index.py` is the gate: it validates REPORT front-matter against the status enum, checks ledger syntax and cross-references, verifies ROADMAP item grammar (mandatory `payoff:` and `cat:`), and flags experiment folders missing a REPORT.md — then rewrites the map. `retriage.py` exits `1` when re-triage is needed, so it can run in CI.

# fastapi-ai-interview-prep

A question bank and mock-interviewer toolkit for FastAPI + AI-engineering roles. Ten topic files hold ten questions each (100 total), every answer written to the **senior signal** an interviewer listens for — the production consequence or trade-off that separates "knows the API" from "has run this at scale."

> Inspired by the topic coverage of *FastAPI for AI Engineers* (AI Engineering Insider, 2026). All questions and answers are written from scratch; this is not a reproduction of the book's question set.

## What ships

- The full SKILL.md ([skills/local/fastapi-ai-interview-prep/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/SKILL.md)) — three session modes (mock interview, topic drill, self-test) and a grading rubric (correctness → senior signal → scenario method).
- Ten reference files (`references/ch01-intro.md` … `ch10-deployment.md`), one per chapter, 10 self-written Q&A each: [intro/ASGI](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch01-intro.md), [Pydantic](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch02-pydantic.md), [endpoints](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch03-endpoints.md), [dependency injection](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch04-dependency-injection.md), [databases](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch05-database.md), [security](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch06-security.md), [testing](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch07-testing.md), [async](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch08-async.md), [AI serving](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch09-ai-serving.md), [deployment](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/references/ch10-deployment.md).
- One script:
  - [`quiz.py`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-interview-prep/scripts/quiz.py) — draws/lists/reveals questions parsed live from the references. Stdlib only.

## Quick start

```
cd skills/local/fastapi-ai-interview-prep

python3 scripts/quiz.py --topics              # chapters + counts
python3 scripts/quiz.py --random 5            # ask 5 (no answers)
python3 scripts/quiz.py --answer ch09-q4      # reveal one rubric
python3 scripts/quiz.py --topic ch08 --random 4 --with-answers
python3 scripts/quiz.py --random 3 --seed 42 --json   # reproducible, machine-readable
```

Run a mock interview by drawing questions without answers, letting the candidate respond, then revealing the rubric per id to score against the senior signal.

## Cross-references

- To *apply* these patterns: [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md).
- To *build* a service: [`fastapi-ai-scaffold`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-scaffold/index.md).

# fastapi-ai-patterns

Production patterns and gotchas for FastAPI services, with the focus on what makes **AI/ML/LLM serving** different from ordinary CRUD. It's a knowledge skill: the `SKILL.md` body carries the cross-cutting decisions and traps an agent gets wrong by default, then routes to one of eight per-topic references for depth.

> Inspired by *FastAPI for AI Engineers: From First Endpoint to Production-Scale AI Systems* (AI Engineering Insider, 2026). All content is re-expressed in original wording — ideas and facts, not the book's prose or code listings.

## What ships

- The full SKILL.md ([skills/local/fastapi-ai-patterns/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/SKILL.md)) with the `endpoint = typed contract` mental model, the **`def` vs `async def` decision table**, and the highest-value gotchas (blocking the event loop, model loading in `lifespan`, `response_model` leak prevention, BOLA in the query, the LLM generate→validate→retry loop) up front.
- Eight references covering all 10 chapters of the book — read on demand:
  - [`api-design.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/api-design.md) — ASGI vs WSGI, REST/idempotency, status codes, pagination, Pydantic v2 (Ch 1–3).
  - [`architecture-di.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/architecture-di.md) — `Depends()` resolution + caching, `yield` deps, layering (Ch 4).
  - [`database.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/database.md) — sessions, N+1, SQLModel vs SQLAlchemy, Alembic, pool sizing (Ch 5).
  - [`security.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/security.md) — password hashing, JWT pinning, CORS, rate limiting, BOLA (Ch 6).
  - [`testing.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/testing.md) — `TestClient`, `dependency_overrides`, test DB tiers, coverage honesty (Ch 7).
  - [`async-and-external.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/async-and-external.md) — event loop, retries + circuit breakers, queues, webhooks, streaming (Ch 8).
  - [`ai-ml-serving.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/ai-ml-serving.md) — model loading, batching, LLM gateway + SSE, RAG, guardrails, cost (Ch 9).
  - [`deployment-observability.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-patterns/references/deployment-observability.md) — workers, probes, observability, caching, degradation (Ch 10).

## The one table worth memorizing

| Workload                                        | Correct handler          |
| ----------------------------------------------- | ------------------------ |
| Async-capable I/O (`httpx`, `asyncpg`)          | `async def` + `await`    |
| Blocking-only library (`requests`, classic ORM) | plain `def` (threadpool) |
| Light CPU (< a few ms)                          | either                   |
| Heavy CPU (inference, parsing)                  | plain `def`, or offload  |

The deadliest FastAPI bug is an `async def` handler that makes a blocking call: it passes every single-request test, then freezes the whole event loop under load and p99 explodes for every endpoint at once.

## When to use it

Reach for this skill when building, reviewing, or debugging a FastAPI service — especially one serving models, embeddings, RAG, or an LLM. For generating a whole project see [`fastapi-ai-scaffold`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-scaffold/index.md); for interview drills see [`fastapi-ai-interview-prep`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-interview-prep/index.md).

## Cross-references

- FastAPI docs: [fastapi.tiangolo.com](https://fastapi.tiangolo.com) — link, don't paraphrase from memory; the API surface changes between minor versions.
- Pydantic v2: [docs.pydantic.dev](https://docs.pydantic.dev).

# fastapi-ai-scaffold

Generates a runnable, production-shaped FastAPI AI/ML service from a bundled skeleton, so you don't re-derive the same wiring every time. The generated tree encodes the patterns from [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md) as working code — the boring-but-correct baseline an inference service needs before it sees traffic.

> Inspired by *FastAPI for AI Engineers* (AI Engineering Insider, 2026). All generated code is original.

## What ships

- The full SKILL.md ([skills/local/fastapi-ai-scaffold/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-scaffold/SKILL.md)) — when to use, what's generated, and how to replace the stubs with your model.
- One script:
  - [`new-fastapi-ai-service.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/fastapi-ai-scaffold/scripts/new-fastapi-ai-service.sh) — copies the skeleton, strips each file's `.tmpl` suffix, substitutes the project slug. Bash 3.2; `--help` / `--dry-run` / `--name` / `--force`; JSON summary on stdout.
- A 44-file skeleton under [`assets/project/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/fastapi-ai-scaffold/assets/project) (every file `*.tmpl`): clean-architecture `app/` (router → service → repository), `lifespan`-loaded model + shared `httpx.AsyncClient` + DB engine, `/health` + `/ready` probes, JWT auth (pinned algorithm, bcrypt), SQLModel + Alembic, an SSE LLM gateway, guardrails + a Pydantic validation loop, structured JSON logging, `tests/` using `dependency_overrides` + in-memory SQLite, plus `Dockerfile`, `gunicorn_conf.py`, `pyproject.toml`, and `.env.example`.

## Quick start

```
# Preview, write nothing:
bash skills/local/fastapi-ai-scaffold/scripts/new-fastapi-ai-service.sh --dry-run ./my-service

# Generate:
bash skills/local/fastapi-ai-scaffold/scripts/new-fastapi-ai-service.sh ./my-service

cd ./my-service
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env          # set JWT_SECRET, DATABASE_URL, MODEL_PATH
uvicorn app.main:app --reload # http://127.0.0.1:8000/docs
pytest -q                     # bundled tests pass immediately
```

The bundled tests and a real-lifespan boot are verified before shipping, so a freshly generated project runs green out of the box.

## Notes

- The generated package is always `app`; only project *metadata* (pyproject name, README title, `.env` `APP_NAME`) uses the slug.
- The model + LLM in `app/ml/model.py` are deterministic stubs — replace them with your real artifact; the structure and offloading stay.

## Cross-references

- Pattern rationale for every generated piece: [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md).
- FastAPI docs: [fastapi.tiangolo.com](https://fastapi.tiangolo.com).

# frontend-design (vendored)

Vendored from [anthropics/skills/skills/frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/frontend-design/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/frontend-design/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

## What it teaches

Aesthetic direction skill — encourages a bold, intentional point of view (brutally minimal, maximalist, retro-futuristic, editorial, …) and refined typography choices instead of default Inter/Arial. Anti-AI-slop guardrails. Use as the creative counterpart to [`web-design-guidelines`](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md)'s audit role.

## Related fullstack-nextjs skills

- [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md) — components to express the chosen aesthetic
- [`web-design-guidelines`](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md) — a11y/perf audit after the look is in
- [`webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md) — Playwright loop to verify the result visually

## Also published as a Claude Code plugin

The same skill is republished as the [`frontend-design`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/frontend-design) plugin on the [`claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) marketplace, which is why Claude Code's startup tip sometimes recommends `/plugin install frontend-design@claude-plugins-official`. **Do not install it on top of the vendored copy** — both pull from the same source; the only difference is the frontmatter `description` line, and the `anthropics/skills` upstream we vendor from has richer trigger phrasing (mentions artifacts, posters, landing pages, dashboards, and HTML/CSS layouts in addition to components/pages/applications).

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/frontend-design/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/frontend-design/SKILL.md) for the full instructions. Upstream source: [anthropics/skills](https://github.com/anthropics/skills).

# git-workflow

One opinionated, scale-aware git workflow that stays consistent from a solo weekend repo to a multi-person, multi-month project — so commit messages, branch names, merge strategy, and release tags stop being improvised per project. Commits are **English and follow Conventional Commits**, even when the prompt is in another language.

| Surface                                   | Question it answers                                         |
| ----------------------------------------- | ----------------------------------------------------------- |
| `references/project-tiers.md`             | "Do I commit to `main`, use a `dev` branch, or open PRs?"   |
| `references/conventional-commits.md`      | "What goes in the commit message, including AI provenance?" |
| `references/worktrees-parallel-agents.md` | "How do I run parallel agents without collisions?"          |
| `references/versioning-and-releases.md`   | "When and how do I tag a version?"                          |
| `references/branch-hygiene.md`            | "Which local branches are done vs still in-dev?"            |
| `scripts/branch-status.sh`                | The same, as data — classify every local branch.            |
| `scripts/check-commit-msg.sh`             | "Is this commit message valid?"                             |
| `references/lazygit-cheatsheet.md`        | "How do I do this in lazygit?" (learning aid)               |

If you want the *why* behind the defaults — the concepts, not the skill mechanics — read the companion explainer: [Git workflow best practices](https://daviddwlee84.github.io/agent-skills/reference/git-workflow/index.md).

## When the skill triggers

- "Commit this" / "幫我 commit" / "整理一下 git" / "write a commit message".
- "Should I branch or just commit to main?" / "should I open a PR?".
- "Set up worktrees for parallel agents" / "carry my `.env` into the worktree".
- "How do I tag / release a version?" / "bump the version".
- "My local branches are a mess — which ones are done?" / "clean up branches".
- Starting a new repo and wanting one consistent commit/branch/release convention for you and your agents.

## The three tiers

Match ceremony to real collaboration needs; promote only when the signal appears.

| Tier                             | Shape                                  | Branching                                       | Integration                                |
| -------------------------------- | -------------------------------------- | ----------------------------------------------- | ------------------------------------------ |
| **1 — Solo / early**             | one `main`                             | commit to `main`; short local branches optional | `pull --rebase`, `merge --ff-only`         |
| **2 — prod/dev split**           | `main` = released, `dev` = integration | feature branches off `dev`                      | merge to `dev`; ff `dev`→`main` at release |
| **3 — Team / grown vibe-coding** | `main` always deployable               | short `feat/…` → PR                             | PR review/CI → squash-merge                |

A solo vibe-coding project can jump straight to Tier 3: the PR becomes the "ship a feature" boundary and a place for CI to run, even with one human.

## Defaults at a glance

- **Commits**: English `type(scope): subject`; non-trivial agent commits add a why/outcome body plus `AI-Assisted-By`, `Agent-Transcript`, and conditional `Agent-Plan` trailers. `feat!`/`BREAKING CHANGE:` drives a major bump.
- **History**: linear — `pull.rebase=true`, `merge.ff=only`; squash-merge noisy vibe-coding PRs, rebase-merge curated ones.
- **Branches**: `feat/ fix/ chore/ docs/ refactor/ exp/` for human intent, `agent/…` for agent/vibe work, `worktree-*` for Claude worktrees.
- **Worktrees**: `claude --worktree <name>`; `.worktreeinclude` (gitignored files only) to carry `.env` in; gitignore `.claude/worktrees/`.
- **Releases**: SemVer, annotated `v`-prefixed tags; for a Python package let the git tag drive the version (setuptools-scm / hatch-vcs).
- **Forge CLIs**: `gh` (GitHub) / `glab` (GitLab) for PRs from the terminal — recommended, never hard-required.

## Structure

```
skills/local/git-workflow/
├── SKILL.md
├── scripts/
│   ├── branch-status.sh        # classify branches: active/merged/gone/stale
│   └── check-commit-msg.sh     # validate header + optional agentic contract
├── tests/
│   └── test_check_commit_msg.sh
├── references/
│   ├── project-tiers.md        # main vs dev vs PR + GitHub Flow
│   ├── conventional-commits.md # the commit message spec, condensed
│   ├── worktrees-parallel-agents.md
│   ├── versioning-and-releases.md
│   ├── branch-hygiene.md
│   └── lazygit-cheatsheet.md   # learning aid
└── assets/
    ├── commit-template.txt      # git config commit.template
    └── worktreeinclude.template # example .worktreeinclude
```

## Relationship to secret hygiene

This skill **defers** all secret scanning and agent-transcript handling to [`agent-history-hygiene`](https://daviddwlee84.github.io/agent-skills/skills/agent-history-hygiene/index.md). At commit/merge time it calls that skill's `scan-staged.sh` (exit `0` clean / `10` redacted / `20` leaks) and points at its rotate-first remediation runbook rather than reimplementing any of it. When a project doesn't check agent transcripts in, drop them before a squash-merge; when it does, stage them with that skill.

## Cross-harness agentic commits

Keep the human as Git author/committer and use one portable final trailer block:

```
feat(scope): add concise imperative summary

Explain why the change was needed, its outcome, and meaningful validation.

AI-Assisted-By: Codex CLI (gpt-5.6-sol)
Agent-Transcript: .specstory/history/session.md
Agent-Plan: .claude/plans/plan.md
```

Native Claude/Cursor attribution or signing remains additive. The companion `agent-history-hygiene/scripts/agent-commit-metadata.sh` derives this block from staged artifacts; `check-commit-msg.sh --agentic --staged` validates the full message. Signing is separate and opt-in—this skill never changes Git or harness configuration unless the user explicitly asks.

The dated behavior matrix and the distinction between co-author trailers, Cursor line tracking/cloud signatures, and Codex's currently undocumented attribution setting are in [Git workflow best practices](https://daviddwlee84.github.io/agent-skills/reference/git-workflow/#agentic-commit-provenance).

## Gotchas

- `merge.ff only` refuses a diverged pull on purpose — resolve with `git pull --rebase`.
- A squash-merged branch never shows under `git branch --merged`; it shows as `gone` upstream. `branch-status.sh` classifies this correctly (delete with `-D`, after confirming no unpushed work).
- Tracked files in `.worktreeinclude` do nothing — it copies **only gitignored** matches; a committed `.vscode/settings.json` is already in the worktree.
- The English-commit rule holds under Chinese prompts — translate the intent, don't mirror the prompt language into the log.
- Commit templates do not affect `git commit -m`, which agent harnesses commonly use; validate with `check-commit-msg.sh --agentic` instead.
- Squash/amend creates a new commit object, so copy canonical trailers into the squash message and do not amend a vendor-signed commit solely for metadata.

## See also

- [Source](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/git-workflow)
- [Git workflow best practices](https://daviddwlee84.github.io/agent-skills/reference/git-workflow/index.md) — the concepts explainer (Conventional Commits, SemVer, GitHub Flow, worktrees).
- [`agent-history-hygiene`](https://daviddwlee84.github.io/agent-skills/skills/agent-history-hygiene/index.md) — secret + transcript hygiene this skill defers to at commit/merge time.

# go-cli-tui

Build Go command-line tools, terminal dashboards, and guided configuration with Lazygit-inspired interaction: visible state, fast context switching, discoverable actions, and immediate feedback. The default stack is Cobra plus compatible Bubble Tea, Bubbles, Lip Gloss, and optional Huh versions.

This is a standalone owned development skill, maintained in [awesome-lazy-tools](https://github.com/daviddwlee84/awesome-lazy-tools/tree/main/skills/go-cli-tui) and synced here for distribution under MIT. Edit the canonical source, not this mirror. It contains instructions and ten references, not a starter application. It primarily serves new tools and new features, while respecting existing frameworks and public behavior.

## Install and use

```
npx skills@latest add daviddwlee84/agent-skills/skills --skill go-cli-tui
```

The grouped picker lists it under **go-cli**. Example requests:

- "Build a Go resource manager with a Lazygit-style list and preview, arrow/Vim navigation, and background refresh."
- "Add a guided `hosts add` wizard so users do not need to memorize flags."
- "Improve this Bubble Tea v1 app's focus, search, and refresh behavior without changing its framework version."
- "Let agents use this CLI reliably, with bundled operational guidance and machine output, then prepare a first `go install` release."
- "Add an upgrade command that updates the running copy and respects source builds, published release assets, and package-manager ownership."

For an implementation request, the skill leads through a compact interaction contract, shared domain operations, implementation, and verification. It does not stop at recommending a layout.

## Interaction defaults

| Area            | Behavior                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| Navigation      | Arrows and j/k together; Tab/Shift+Tab for focus; contextual h/l; gg/G for long lists                     |
| Mouse           | Shared pure layout/hit geometry, semantic press/release actions, modal capture, optional native selection |
| Editing         | Printable keys stay text; no required normal/insert mode                                                  |
| Discoverability | Contextual footer, help, and action menu share effective bindings                                         |
| Continuity      | Keep valid selection, filter, and scroll across views, refresh, and wizard return                         |
| Responsiveness  | Initial UI before slow work; reject stale results; distinguish cached, unknown, empty, and failed states  |
| Preferences     | Optional TOML; XDG on macOS/Linux, native Windows directories; flags → env → file → defaults              |

Bare dashboard apps open their UI in a TTY. A designated wizard command such as `hosts add` guides on bare invocation; ordinary command groups show help. Partial business flags with missing data produce a usage error. Explicit `--interactive` starts a prefilled wizard. Global options such as `--config` alone do not change a bare wizard entry into command mode.

Unknown flags/invalid values report errors before prompting. Non-TTY and JSON execution never prompt; contradictory interactive/output modes fail clearly. Wizards retain answers on Back, validate through the shared service, and review consequential changes before applying them. Prefilled local settings forms can offer Ctrl+S from any field with optional Review, preserving validation and drafts on failure; verify raw Ctrl+S and terminal flow control in a real PTY.

## Agent use and staged installation

For tools that need an agent-facing interface, the skill covers embedding one operational guide in the binary, static offline `--skill`/topic output, JSON errors, noninteractive authentication behavior, and bounded log streams. CLI, TUI, and agent calls use the same domain operations. Command help remains the syntax authority; the guide explains workflow, scope, and uncertain mutation results. It does not require every tool to ship a skill or skill installer.

An early Go release can start with `go install` using the actual main-package path, including `/cmd/<name>` when that is the repo layout. Document the Go requirement and binary `PATH`, recover the installed module version when linker flags are absent, and verify both a public fixed tag and `@latest` from outside the checkout. `@latest` does not generally mean the newest main commit. Prebuilt archives, checksums, and a Homebrew tap can follow when distribution needs justify them; they are not prerequisites for the first source release.

Source packaging distinguishes binary archives, Git source archives, Go module ZIPs and clone history. Narrow `export-ignore` rules can omit development records from source archives; Go downloads instead need module boundaries around pure evidence directories. Preserve embedded build inputs, and verify both extracted distributions with real builds and isolated runtime smoke checks. The guide also covers the false-positive risk of testing Go ZIPs with ordinary Git export attributes still enabled. New exclusions apply to new immutable versions.

An explicit upgrade feature selects a strategy from published artifacts and the running executable's ownership. A source-only release can build an exact tag with installed Go; published archives need checksum and executable verification; package-owned copies update through their manager. Build metadata describes provenance, not who installed the file. A copied Go binary must update at its resolved current path, independent of today's `GOBIN` or another copy on `PATH`. Local/dirty builds are preserved by default. Staging, destination locking, identity rechecks and atomic replacement retain the old file on failure. Check-only/JSON/read-only behavior and Go toolchain selection are explicit; the updater does not bootstrap a missing Go command or invoke `sudo`. Embedded `--skill` content updates with the binary; end users do not run `npx skills` for that content.

Mouse verification combines state tests with SGR events sent through a real PTY, including modal capture and stale button presses after resize/target changes. Monitoring guidance covers timestamped bounded history, source-specific freshness, real gaps, counter resets and exact drilldowns. Settings editor entry points stay usable when the file is malformed and retain edits that fail validation.

Maintain a user-facing changelog, pass checks on the exact release source, and keep changelog version, immutable tag, release notes and installed binary version consistent. These are completion checks, not a requirement to add packaging.

## Completion and shared operation lessons

Completion setup separates generation, user-file installation, parent-shell activation and offline candidate queries. Native zsh bridges can query the current binary; legacy Bash output may need regeneration. Verify actual Tab input in an isolated shell, not just generated script syntax.

Cross-target and persistent-owner workflows share a reviewed plan between CLI and TUI. A digest detects stale observations but does not make remote writes atomic. Keep saved source, owner activation and observed runtime behavior separate. Background discovery must not replace pending operation surfaces; after an operation, invalidate affected cached views while retaining stale data.

SSH authentication releases the terminal to native SSH through an explicit action. Background checks never prompt; configured shared masters and app-owned fallback sessions have separate lifetimes and cleanup responsibilities.

Standalone shell integration uses a narrow generated environment handoff, preserves prior values/functions/exit hooks, and keeps authentication outside captured output. Persistent shell connections have explicit ownership and crash cleanup; generated container settings identify the actual consumer and preserve existing config owners. Reverse SSH guidance separates command, shell and service lifetimes, checks the actual remote bind address, keeps allocated-port stdout separate from diagnostics, and preserves login-rc precedence with an explicit clean-shell alternative. Dashboard actions can release the terminal to the same CLI wizard, retain results until acknowledgement, and refresh the correct target on return. Empty searches and clipped Apply buttons cannot submit hidden choices.

## References included

| Reference                                                                                                                               | Load for                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [Interaction design](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/interaction-design.md)   | Layout, focus, dual navigation, filtering, help, Unicode, and resize                                                      |
| [CLI, wizards, config](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/cli-wizards-config.md) | Entry policy, form behavior, shared validation, XDG, and precedence                                                       |
| [Charm stack](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/charm-stack.md)                 | Version selection and routing needs to libraries/tools                                                                    |
| [Async and terminal](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/async-terminal.md)       | Generations, cancellation, startup, terminal ownership, and dev-cli lessons                                               |
| [Agent-facing CLI](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/agent-facing-cli.md)       | Embedded knowledge, static documentation, machine errors, noninteractive calls, and bounded streams                       |
| [Go distribution](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/go-distribution.md)         | Main-package install paths, versions, source/module boundaries and packaging verification                                 |
| [Self-update](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/self-update.md)                 | Conditional source/asset/manager strategies, provenance and ownership, current-copy replacement, and failure preservation |
| [Shell completion](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/shell-completion.md)       | Install/status, zsh fpath, offline candidates, update freshness and actual Tab verification                               |
| [Shell context](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/shell-context.md)             | Parent environment, persistent connections, legacy adapters and consumer configuration ownership                          |
| [Verification](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/references/verification.md)               | State tests, real PTY checks, Unicode emulator limits, and three acceptance walkthroughs                                  |

The Charm map includes Glamour, Log, Wish, ANSI/terminal utilities, Harmonica, Gum, Glow, VHS, and Freeze as optional capabilities. It does not make all of them dependencies. New code checks current compatible stable releases; existing code reads its module versions before borrowing examples.

## Sources and limits

[Lazygit](https://github.com/jesseduffield/lazygit/blob/master/AGENTS.md) uses its own in-tree gocui fork. Its UX is the inspiration; the new-project implementation preference is [Charm](https://charm.land/). This skill also extracts lessons from [dev-cli](https://github.com/daviddwlee84/dev-cli), including live filtering, generation handling, shared wizards, terminal handoffs, embedded skills, and version reporting, without depending on that project or copying its domain model.

The [external catalog](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/#go-clitui-candidates) records the 2026-09-20 comparison of `golang-cli`, `tui-design`, and `bubbletea`, their manual-install paths, and why this repo chose local integration.

Verification guidance includes deterministic state tests, bad-input/JSON/config checks, and actual terminal operation. A concrete lazyclash case records pyte 0.8.2's VS16/ZWJ replay limitation and why direct View checks complement PTY input tests. The three walkthroughs remain specifications, not pre-executed applications or measured skill benchmarks. Distribution work can use the optional [CLI release skill](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/cli-release-distribution).

## Canonical SKILL.md

See [Canonical go-cli-tui/SKILL.md](https://github.com/daviddwlee84/awesome-lazy-tools/blob/main/skills/go-cli-tui/SKILL.md).

# herdr (vendored)

Vendored from the official [`herdrdev/herdr/skills/herdr`](https://github.com/herdrdev/herdr/tree/master/skills/herdr) skill under Apache-2.0. It is synchronized through `vendor.yaml`; do not edit the vendored files locally because `make sync` replaces them.

## What it teaches

The skill gives an agent the safe operating model for Herdr's session, workspace, tab, pane, and recognized-agent APIs. It emphasizes explicit IDs, JSON responses, `--current`, non-destructive background panes, lifecycle-aware waiting, and the difference between raw pane control and agent control.

It intentionally triggers only when the user explicitly asks to use Herdr and requires `HERDR_ENV=1` before controlling a live session.

## Version alignment

This vendored copy is suitable for catalog discovery and generic installs. A machine that also installs the Herdr binary should prefer the exact skill emitted by that binary:

```
herdr --skill > ~/.agents/skills/herdr/SKILL.md
```

That keeps CLI syntax and skill guidance on the same release, including preview builds. The accompanying dotfiles implement this automatically.

## Canonical SKILL.md

See [`skills/vendor/herdr/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/herdr/SKILL.md) for the full instructions.

# long-running-jobs

Decide **how an agent should wait** for work that outlives a single turn — training runs, Slurm jobs, sweeps, long builds. The skill exists because the obvious approach is the expensive one.

## The problem it solves

An agent babysitting an 8-hour training run tends to arm a scheduled check-in: wake at 16:31, run `squeue`, see "still epoch 21", schedule the next wake-up. It works, and it is the worst option available.

> **Polling is not the problem. Polling with the model inside the loop is.**

```
until squeue -h -j "$JID" | grep -q .; do sleep 60; done   # 8 hours, ~0 tokens
```

```
CronCreate -> wake -> squeue -> "still epoch 21" -> reschedule
                                # 1 full context read PER TICK
```

Both poll. In a session carrying 400k+ tokens, only one of them costs a context window every 60 seconds. The skill's whole thesis is **move the timer out of the context window** — into the scheduler, a blocked shell, or onto disk.

## The ladder

Pick the lowest-numbered tier that applies.

| Tier  | Mechanism                                                                 | Use when                                                                |
| ----- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **0** | Scheduler owns the chain (`sbatch --dependency=afterok`, `pueue --after`) | There is a next step. Survives session death, compaction, laptop sleep. |
| **1** | One blocking wait, backgrounded (`sbatch --wait`, `run-and-mark.sh`)      | You must react at completion. Zero in-context polls.                    |
| **2** | Stream shell-filtered events                                              | You must react *mid-run* — OOM, early stopping, a threshold.            |
| **3** | Scheduled check-in                                                        | Last resort: a remote system you hold no handle to.                     |

Tier 0 is the one people skip. It requires knowing the next command *before* the first finishes — and when you do, the agent is removed from the loop entirely.

## The invariant

Orthogonal to all four tiers: **whatever waits, something must survive not waiting.**

```
python train.py; rc=$?
printf '%s\n' "$rc" > runs/v2.exit.tmp && mv runs/v2.exit.tmp runs/v2.exit
```

Temp-file-then-`mv` is a `rename(2)` within one filesystem, so a reader sees either no marker or a complete one — never a half-written exit code read as success.

The reading rule that falls out of it:

| Observed                   | Means                                               |
| -------------------------- | --------------------------------------------------- |
| marker, `0`                | succeeded                                           |
| marker, non-zero           | failed                                              |
| no marker, never started   | not started                                         |
| **no marker, but started** | **unknown** — killed, node died, *or still running* |

**Absence is never success and never failure.** Treating "unknown" as "not done, so re-run" is how you end up with two copies of an eight-hour job.

| Surface                                                                                                                                                              | Question it answers                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `run-and-mark.sh`                                                                                                                                                    | "Run this, block, and leave a record that outlives my session."        |
| `check-runs.sh`                                                                                                                                                      | "What finished while I was away?"                                      |
| [`references/claude-code-mechanisms.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/long-running-jobs/references/claude-code-mechanisms.md) | "Which harness tool implements each tier?"                             |
| [`references/scheduler-chaining.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/long-running-jobs/references/scheduler-chaining.md)         | "How do I wire Phase A → Phase B so nothing has to stay awake?"        |
| [`references/completion-contracts.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/long-running-jobs/references/completion-contracts.md)     | "How do I record completion so it survives the queue and the session?" |
| [`assets/chained.sbatch.template`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/long-running-jobs/assets/chained.sbatch.template)             | "Give me the dependency plumbing already correct."                     |

## Two facts worth the skill's existence

**Backgrounded shell commands wake the agent on exit.** Verified by experiment against Claude Code 2.1.220, and stated in the harness's own guidance:

> "Use the Monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use Bash with `run_in_background` instead."

This makes Tier 1 a single call, not a loop. Public documentation summaries claiming the agent must poll for completion are stale — the skill says so explicitly, because acting on the stale version reintroduces the polling the skill is trying to remove.

**A failed Slurm parent leaves its child pending forever.** From `sbatch(1)`:

> "By default the job stays pending with reason DependencyNeverSatisfied"
>
> "Once a job dependency fails due to the termination state of a preceding job, the dependent job will never be run, even if the preceding job is requeued"

So Phase B does not fail when Phase A does — it parks indefinitely, looking in `squeue` exactly like a job waiting its turn, and requeueing Phase A does not release it. Every chain in the skill therefore carries `--kill-on-invalid-dep=yes` and `--mail-type=INVALID_DEPEND`. This one has its own [pitfall page](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/slurm-dependent-job-pends-forever-after-failed-parent.md).

## When the skill triggers

- A job "takes hours" / "runs overnight" / "will finish tomorrow morning".
- "Check back when it's done", "wait for training to finish", "run B after A".
- **You are about to arm a recurring check-in, or repeat a `squeue` / `nvidia-smi` / `ls checkpoints/` poll to see whether something finished.** That impulse is the trigger.

## When it doesn't

- The command finishes in seconds — just run it.
- Metrics, curves, parameter tracking → `mlflow-tracking`.
- Recording what the run *meant* → `experiment-knowledge-harness`.
- Resource requests and GPU isolation → `slurm-hpc`.

## Structure

```
skills/local/long-running-jobs/
├── SKILL.md                                # the ladder, the invariant, 8 gotchas
├── scripts/
│   ├── run-and-mark.sh                     # bash 3.2; own the child, block, atomic marker
│   └── check-runs.sh                       # bash 3.2; marker reader, exit 0/3/4
├── references/
│   ├── claude-code-mechanisms.md           # which tool per tier; blocked foreground sleep; cron limits
│   ├── scheduler-chaining.md               # Slurm dependency matrix + traps; pueue; DVC
│   └── completion-contracts.md             # atomic markers; sacct states; wait-primitive portability
└── assets/
    └── chained.sbatch.template             # Phase A/B chain, correct by construction
```

## Own the process, or own a marker

The portability table in `completion-contracts.md` drives one design decision worth calling out:

| Primitive           | Works on                                            |
| ------------------- | --------------------------------------------------- |
| `wait "$PID"`       | everywhere — **children of the current shell only** |
| `tail --pid=PID`    | GNU coreutils only; BSD/macOS `tail` rejects it     |
| `pidwait`           | Linux (procps-ng)                                   |
| `inotifywait`       | Linux; **races** if the marker predates the watch   |
| `flock` / `fswatch` | not on stock macOS                                  |

There is no portable way to wait on a *foreign* PID. So `run-and-mark.sh` runs its command as its own child, which makes plain `wait` — the one primitive available everywhere — sufficient.

## Verification

Every claim in the skill was tested rather than assumed:

```
bash skills/local/skill-author/scripts/lint-skill.sh --strict skills/local/long-running-jobs

# exit-code contract, under stock macOS bash 3.2
/bin/bash scripts/run-and-mark.sh --marker-dir .r --name ok  -- /bin/sh -c 'exit 0'   # 0
/bin/bash scripts/run-and-mark.sh --marker-dir .r --name oom -- /bin/sh -c 'kill -9 $$'  # 137
/bin/bash scripts/check-runs.sh --marker-dir .r --json | python3 -m json.tool
```

- Backgrounding `run-and-mark.sh` fires a real completion notification carrying the command's exit code — the Tier 1 mechanism, proven end to end.
- `SIGKILL` is preserved as **137**, so an OOM stays distinguishable from `exit 1` — which `sbatch --wait` alone cannot do (it collapses every signal death to `1`).
- A stubbed `sbatch` emitting `999;clus` yields `--dependency=afterok:999`, confirming the `${JID%%;*}` cluster-suffix strip.
- `check-runs.sh` returns `4` for unknown ahead of `3` for failed — unknown is the state that needs a human, so it outranks.

# marimo-batch-mlflow

Opinionated fork of [marimo-team/skills/marimo-batch](https://github.com/marimo-team/skills/tree/main/skills/marimo-batch) that swaps three things:

| Concern      | upstream `marimo-batch`                                 | this skill                                                                                                      |
| ------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| CLI parsing  | `mo.cli_args()` + hand-rolled `rich.Table` for `--help` | `tyro.cli(ModelParams)` — auto `--help`, type coercion, validation                                              |
| Params model | Pydantic `BaseModel`                                    | `dataclass` (primary) or `pydantic.BaseModel` (alternative)                                                     |
| Tracking     | Weights and Biases                                      | MLflow (`mlflow` + optional [`mlflow-widgets`](https://github.com/daviddwlee84/mlflow-widgets) for live charts) |

Pick this skill when the user has (or is happy with) MLflow and prefers strongly-typed CLIs. Pick upstream when the user is already on W&B.

## What ships

- The full SKILL.md ([skills/local/marimo-batch-mlflow/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/marimo-batch-mlflow/SKILL.md)) with a decision matrix vs upstream, a dual-mode pattern recipe, and cell-level templates for params / EnvConfig / training loop / live chart.
- A reference notebook ([starting-point.py](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/marimo-batch-mlflow/references/starting-point.py)) — full PyTorch training notebook with dataclass params, Tyro CLI, MLflow logging, and a live `MlflowChart` cell that's gated off in script mode.
- A Pydantic-variant snippet ([params-pydantic.py](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/marimo-batch-mlflow/references/params-pydantic.py)) — only the params cell differs; rest of the notebook is identical.
- A grid-search launcher ([grid.py](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/marimo-batch-mlflow/references/grid.py)) — randomized sweeps via Hugging Face Jobs with MLflow secrets injected. Dry-run by default; `--launch` actually submits.

## Dual-mode pattern (the core idiom)

```
import marimo as mo
import tyro

is_script_mode = mo.app_meta().mode == "script"

if is_script_mode:
    params = tyro.cli(ModelParams)        # CLI flags
else:
    mo.stop(form.value is None, mo.md("*Submit form to start.*"))
    params = ModelParams(**form.value)    # UI form

# Every cell below uses `params.epochs`, `params.batch_size`, ...
# unaware of which branch produced it.
```

Same notebook serves as the UI for fast iteration **and** the entry point for `uv run notebook.py --epochs 50` batch jobs. No code duplication.

## Why a fork instead of vendoring

The upstream `marimo-batch` skill is opinionated towards W&B and `mo.cli_args()`. Vendoring + patching would be clobbered every sync; a local fork in `skills/local/` keeps the divergence safe and explicit. The SKILL.md cross-references upstream so users can pick the right variant.

## Cross-references

- Upstream [`marimo-batch`](https://github.com/marimo-team/skills/tree/main/skills/marimo-batch) — the W&B variant; pick this if the user is already on W&B.
- [`marimo-notebook`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/marimo-notebook/SKILL.md) — general marimo authoring patterns (vendored from marimo-team).
- [`anywidget-generator`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/anywidget/SKILL.md) — for building custom live-chart widgets if `mlflow-widgets` doesn't cover the case (vendored from marimo-team).
- [`mlflow-widgets`](https://github.com/daviddwlee84/mlflow-widgets) — the anywidget-based MLflow chart/table/parallel-coordinates components used in `starting-point.py`'s live-chart cell.
- [Tyro docs](https://brentyi.github.io/tyro/) — CLI generation reference; supports dataclass, Pydantic, attrs.

# marimo-notebook (vendored)

Vendored from [marimo-team/skills/skills/marimo-notebook](https://github.com/marimo-team/skills/tree/main/skills/marimo-notebook). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/marimo-notebook/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/marimo-notebook/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Write a marimo notebook in a Python file in the right format.

## What it teaches

General-purpose marimo authoring conventions — how cells, reactive dependencies, and the `.py` notebook file format work. This is the foundational skill you want loaded any time a user is writing marimo code from scratch.

## Related local skills

- [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) — dual-mode (UI + batch CLI) notebooks with Tyro + MLflow, built on top of these authoring conventions.

## Canonical SKILL.md

See [skills/vendor/marimo-notebook/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/marimo-notebook/SKILL.md) for the full instructions. Upstream source: [marimo-team/skills](https://github.com/marimo-team/skills).

# mkdocs-site-bootstrap

Bootstrap a MkDocs Material documentation site for a repo and (optionally) deploy it to GitHub Pages — including the same stack this very docs site uses (Material + `mkdocs-llmstxt` + `mkdocs-copy-to-llm` + `pymdownx.snippets`, GitHub Pages workflow with paths-filter). Multilingual sites use a strict two-pass build so root llms files remain complete and default-language-only.

This skill is **consent-gated**. It records preferences in `.skills/preferences.yaml` so it doesn't re-ask on every session, never auto-migrates a user's existing `docs/` content, and gates the `gh api -X POST .../pages` call on explicit user confirmation.

Already using an older version of this skill?

Updating the installed skill only downloads the fixed build and migration tools; it does **not** change your project. If i18n made `llms.txt` nearly empty, switched it to the final locale, or forced CI to drop strict, follow [Migrate an existing site](#migrate-an-existing-site) below.

## Quick start

```
# 1. Scaffold the site files
bash skills/local/mkdocs-site-bootstrap/scripts/init-docs-site.sh \
  --site-name "My Project" \
  --repo-slug owner/repo \
  --site-url https://owner.github.io/repo/

# 2. Build the complete strict artifact (HTML + default-language llms)
uv sync --extra docs
uv run python scripts/build-docs-site.py

# 3. Enable GitHub Pages and trigger first deploy (consent gate)
bash skills/local/mkdocs-site-bootstrap/scripts/enable-pages.sh \
  --repo owner/repo

# 4. Add new pages over time
bash skills/local/mkdocs-site-bootstrap/scripts/add-docs-page.sh \
  --section Reference --title "API schema"
```

## Bundled scripts

| Script                    | Purpose                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `init-docs-site.sh`       | Scaffold config, docs, workflow, and the managed production build helper              |
| `build-docs-site.py`      | Strict production build; isolates multilingual HTML from default-language llms output |
| `enable-pages.sh`         | Enable Pages via `gh api` and trigger first deploy                                    |
| `add-docs-page.sh`        | Create a new `docs/` page and insert it into `mkdocs.yml` nav                         |
| `check-preferences.sh`    | Read/set/reset entries in `.skills/preferences.yaml`                                  |
| `add-language.sh`         | Add a suffix-layout non-default language and translation stubs                        |
| `migrate-i18n-llmstxt.sh` | Audit or conservatively migrate an older i18n + llmstxt scaffold                      |

All scripts support `--help` and `--dry-run`.

## Production build vs preview

Use this for anything you deploy:

```
uv run python scripts/build-docs-site.py
```

On a multilingual site with llmstxt, the helper runs a strict default-language llmstxt pass, a separate strict multilingual HTML pass, validates both, merges the root artifacts, and only then replaces `site/`. `/llms.txt`, `/llms-full.txt`, and the raw `.md` sidecars intentionally represent the default language only.

Direct `uv run mkdocs build --strict` and `uv run mkdocs serve` are safe HTML-only previews because the scaffold disables llmstxt unless the helper enables it. Do not deploy a direct multilingual build if llms output is part of the site's contract.

## Preferences

The skill writes to `<repo>/.skills/preferences.yaml`:

```
mkdocs_site_bootstrap:
  enabled: true
  decided_at: "2026-04-23"
  stack: mkdocs-material
  auto_deploy: true
  pages_deployed: true
  existing_docs_decision: skipped
  site_url: https://owner.github.io/repo/
  repo_slug: owner/repo
```

To change your mind:

```
# Reset (returns to "never asked" state)
bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --reset mkdocs_site_bootstrap

# Or explicitly opt out so the agent stops asking
bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --set mkdocs_site_bootstrap.enabled=false
```

See [`references/preferences-schema.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/preferences-schema.md) for the full schema and conventions for cross-skill preference use.

## Existing `docs/` content

The skill detects pre-existing `docs/` content and asks before doing anything. It will **never** auto-migrate, rename, or rewrite user files. Three consent options:

- **skip** — leave docs alone, just create `mkdocs.yml` with empty nav (auto)
- **wrap** — same, but populate `nav:` from existing files alphabetically
- **manual** — bail out, user reorganizes first then re-runs

See [`references/existing-docs-handling.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/existing-docs-handling.md) for the full decision tree.

## Bilingual / multilingual docs

Add a suffix-layout locale such as zh-TW without moving existing pages:

```
bash skills/local/mkdocs-site-bootstrap/scripts/add-language.sh --lang zh-TW
uv sync --extra docs
uv run python scripts/build-docs-site.py
```

The script creates `*.zh-TW.md` stubs, adds/configures `mkdocs-static-i18n`, and preserves strict plus default-language llms output. `--remove-llmstxt` is the explicit opt-out. The legacy `--drop-strict` flag is a deprecated no-op because dropping strict hid warnings without fixing the corrupted files; `--keep-llmstxt` is a deprecated alias for the default. Exit `11` means the language was added but custom downstream build files still need the migration tool's reported manual actions.

See the [`i18n guide`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/i18n-guide.md) for the terminology rule, plugin guards, output contract, and build details.

## Migrate an existing site

Run the migration audit from the downstream project root:

```
npx skills@latest update mkdocs-site-bootstrap --project --yes

bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --json
```

Exit `10` means the affected legacy shape was found and nothing was changed. Preview, then apply and verify:

```
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --apply --dry-run --json

bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --apply --verify --json
```

The tool only patches recognizable scaffold-owned config, workflow, Makefile, and managed-helper shapes. Custom values or a foreign same-named helper are reported in `manual_actions[]` and left untouched; exit `11` keeps that work visible. It also reports unsafe relative llms/sidecar links in localized source pages for manual replacement with full `site_url`-based URLs. See the full [`migration guide`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/i18n-llmstxt-migration.md).

## Why a skill, not a one-shot script?

Because docs sites are not a one-shot setup — they evolve. The skill exists to:

1. Get the initial scaffold right (consent-gated, idempotent).
1. Keep helping with `add-docs-page.sh` over time.
1. Remember what the user already decided so future sessions don't pester.
1. Provide a place to encode the gotchas (linking rules, snippets dir, `pages: write` permission, i18n/llmstxt lifecycle isolation, etc.) so they don't get re-discovered every project.

The bundled `references/docs-stack-recipe.md` documents what the stack actually is, so a user who wants to apply pieces manually has the recipe without invoking the skill.

## Canonical SKILL.md

See [skills/local/mkdocs-site-bootstrap/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/SKILL.md) for the full triggering description, workflow, and gotchas.

# mlflow-tracking

Generic [MLflow](https://mlflow.org/docs/latest) skill (upstream [mlflow/mlflow](https://github.com/mlflow/mlflow)) — covers experiment tracking, model registry, and LLM tracing for any Python project.

This is the **general-purpose** MLflow skill. For the marimo-specific dual-mode (UI + batch CLI) variant, see [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) instead — that one is a specialization built on top of marimo notebooks.

## Three deployment modes (pick one before writing code)

| Mode                        | Tracking URI                            | When to choose                                                      |
| --------------------------- | --------------------------------------- | ------------------------------------------------------------------- |
| File                        | `file:./mlruns` (default)               | One-off experiments, no UI, no model registry                       |
| **SQLite + `mlflow ui`** ⭐ | `sqlite:///mlflow.db`                   | Solo work, want UI without running a server, model registry support |
| **Docker Compose stack** ⭐ | `http://host:8000` (PostgreSQL + MinIO) | Team use, production, parallel jobs, large artifacts                |
| Databricks-managed          | `databricks://`                         | Already paying for Databricks (out of scope)                        |

The two starred modes cover ~95% of real use. **File mode does NOT support the model registry** — if the user wants `register_model`, they need SQLite or a server.

## What ships

- The full SKILL.md ([skills/local/mlflow-tracking/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/SKILL.md)) with the deployment-mode decision table, the Manual-vs-Autolog choice, and a gotchas section calibrated to actual production failures (the `mlflow ui` `--backend-store-uri` trap, autolog ordering, deprecated stages, etc.).
- Six references — read on demand:
  - [`sqlite-local.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/sqlite-local.md) — SQLite mode setup, the `--backend-store-uri` gotcha, when to migrate to PostgreSQL.
  - [`docker-compose-server.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/docker-compose-server.md) — production stack ops, `.env` customization, AWS S3 swap, basic auth, backup strategy.
  - [`llm-tracing.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/llm-tracing.md) — autolog by provider (OpenAI, Anthropic, LangChain, LlamaIndex, DSPy, AutoGen, CrewAI, LiteLLM, Bedrock, Gemini, …), `@mlflow.trace`, span types, `search_traces`, comparison vs Weave/LangSmith/Langfuse.
  - [`model-registry.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/model-registry.md) — **aliases** (current API: Champion / Challenger) vs deprecated stages, registration patterns, webhooks.
  - [`autologging-by-framework.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/autologging-by-framework.md) — every officially-supported framework with per-library gotchas (sklearn, pytorch, lightning, tensorflow, keras, xgboost, lightgbm, catboost, statsmodels, spark, fastai, paddle, transformers, …).
  - [`mlflow-widgets-anywidget.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/references/mlflow-widgets-anywidget.md) — using [mlflow-widgets](https://github.com/daviddwlee84/mlflow-widgets) for live charts inside marimo / Jupyter without launching the full UI.
- Three scripts:
  - [`init-mlflow-sqlite.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/scripts/init-mlflow-sqlite.sh) — idempotent SQLite-mode setup; prints the exact `mlflow ui` command with the right `--backend-store-uri` (the #1 SQLite gotcha).
  - [`start-mlflow-server.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/scripts/start-mlflow-server.sh) — copies the bundled docker-compose stack into a target dir, generates `.env` with rotated random secrets, runs `docker compose up -d`, waits for the healthcheck, prints the URLs and client env vars to export.
  - [`tail-runs.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/scripts/tail-runs.sh) — PEP 723 inline-deps Python script (runs via `uv run`, no env setup) that wraps `mlflow.search_runs` with JSON or CSV output for terminal use.
- The vendored production stack in `assets/docker-compose-stack/`:
  - [`docker-compose.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/assets/docker-compose-stack/docker-compose.yaml) — PostgreSQL + MinIO + tracking server + bucket bootstrap, with healthchecks and `depends_on` ordering.
  - [`Dockerfile`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/assets/docker-compose-stack/Dockerfile) — pinned MLflow image + `psycopg2-binary` + `boto3`.
  - [`.env.example`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/assets/docker-compose-stack/.env.example) — all knobs documented; default port 8000 to dodge macOS AirPlay on 5000.
  - [`README.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mlflow-tracking/assets/docker-compose-stack/README.md) — quick-start, troubleshooting, when to outgrow this stack.

## Why this exists alongside `marimo-batch-mlflow`

| Concern                | `mlflow-tracking` (this)                             | `marimo-batch-mlflow`                              |
| ---------------------- | ---------------------------------------------------- | -------------------------------------------------- |
| Scope                  | Any Python project, any trainer                      | marimo notebooks specifically                      |
| Focus                  | Tracking server setup, registry, LLM traces, autolog | Dual-mode notebook pattern (UI + CLI) using MLflow |
| Includes Docker stack? | Yes, vendored from production                        | No                                                 |
| Includes LLM tracing?  | Yes, full reference                                  | No                                                 |

Use this skill when the user wants MLflow as a general tracking backend. Use `marimo-batch-mlflow` when they're specifically writing marimo notebooks that need to run as both an interactive UI and a batch CLI.

## Quick start

**SQLite (solo)**:

```
bash skills/local/mlflow-tracking/scripts/init-mlflow-sqlite.sh
# → prints the exact `mlflow ui --backend-store-uri sqlite:///mlflow.db --port 5001`
```

**Docker Compose stack (team)**:

```
bash skills/local/mlflow-tracking/scripts/start-mlflow-server.sh \
  --target-dir infra/mlflow
# → copies stack, rotates secrets in .env, launches, waits for healthcheck,
#   prints the env vars to export on client machines
```

**In your training code** (works for any of the modes):

```
import mlflow

mlflow.set_tracking_uri("http://localhost:8000")    # or "sqlite:///mlflow.db"
mlflow.set_experiment("my-project")
mlflow.autolog()                                    # zero-touch logging

with mlflow.start_run():
    model.fit(X, y)                                 # params, metrics, model all logged
```

## Cross-references

- Official docs: [mlflow.org/docs/latest](https://mlflow.org/docs/latest) — always link these. MLflow ships every 4–6 weeks; LLM tracing especially is a moving target.
- Upstream repo: [github.com/mlflow/mlflow](https://github.com/mlflow/mlflow).
- [`mlflow-widgets`](https://github.com/daviddwlee84/mlflow-widgets) — anywidget-based charts/tables for embedding live MLflow data in marimo / Jupyter cells. Demo: [daviddwlee84.github.io/mlflow-widgets](https://daviddwlee84.github.io/mlflow-widgets/).
- [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) — the marimo-specific variant for dual-mode (UI + batch CLI) notebooks.

# nautilus-trader

Write, debug, review and migrate code that uses **NautilusTrader**, in Python (`nautilus_trader`) or through the `nautilus-*` Rust crates. This local skill belongs to the `quantitative-finance` marketplace group with [vectorbt](https://daviddwlee84.github.io/agent-skills/skills/vectorbt/index.md) and [quantatitive-factor-researcher](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md).

NautilusTrader is mid-transition. The legacy Cython core (v1, `1.x`, final release 1.231.0) and the Rust core with PyO3 bindings (v2, `2.0.0rcN`) both install and import as `nautilus_trader`, but their Python APIs differ widely. While 2.0 is a release candidate, `pip install nautilus_trader` without `--pre` still installs v1, and the hosted `latest` docs describe v2. No v1 docs are hosted anymore. The skill therefore identifies the generation and exact version before using any example, then reads documentation from the matching git tag.

VectorBT remains the tool for vectorized signal research and parameter grids. This skill covers event-driven backtests (order books, fill and latency models) and the path from the same strategy code to sandbox, testnet and live nodes, including adapters for venues and data providers.

## What ships

- A short entrypoint plus on-demand references: generations and installation, v1 → v2 migration tables, live/sandbox trading, Rust crates, and sources.
- `nt_context.py doctor` inspects the project's interpreter and reports:
- the installed version and native core (`cython` or `pyo3`);
- lock and requirement pins, and `nautilus-*` crates;
- v1-only or v2-only names in code that imports `nautilus_trader`;
- PyPI stable vs pre-release state;
- a recommendation with a docs git ref and any conflicts.
- `nt_context.py docs` copies `docs/`, `examples/`, `MIGRATION_V2.md`, `RELEASES.md`, `ADAPTERS.md` and `ROADMAP.md` for one tag or branch into an XDG cache. It uses a sparse, partial `git clone`, with no GitHub token, API quota or embeddings.
- Live-trading gates: real accounts, credentials and non-sandbox orders need explicit user authorization; sandbox and testnet come first.
- Offline tests using local git remotes, synthetic packages and PyPI JSON.

Source: [the local skill](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/nautilus-trader).

## Quick start

Commands are relative to the installed skill directory; they need Python 3.11+ and git on macOS or Linux.

```
python3 scripts/nt_context.py doctor --project /path/to/project --python /path/to/env/bin/python
python3 scripts/nt_context.py docs --project /path/to/project --python /path/to/env/bin/python
# Documentation only, for an explicit tag or branch:
python3 scripts/nt_context.py docs --ref v2.0.0rc5
```

Search the returned `docs_dir` and `examples_dir` with `rg`, read the complete page or example, then confirm signatures in the project's interpreter. The tag above is an example, not a default.

## Generations

|               | v1                                  | v2                                   |
| ------------- | ----------------------------------- | ------------------------------------ |
| Versions      | `1.x` (final 1.231.0)               | `2.0.0rcN`                           |
| Core          | Cython (`.pyx`/`.pxd` in the wheel) | Rust, `nautilus_trader._libnautilus` |
| Live node     | `TradingNode` + config dicts        | `LiveNode.builder(...)`              |
| Configs       | msgspec `Struct`                    | PyO3 types                           |
| Branch / docs | `develop_v1`, git tags only         | `develop`, hosted `latest`/`nightly` |

The skill preserves existing v1 projects, recommends v2 with an exact pin for new work, and states RC status explicitly. Upstream does not recommend release candidates for live trading with real capital.

## XDG and freshness

The cache root is `--cache-dir`, then an absolute `$XDG_CACHE_HOME/nautilus-trader-agent`, then `~/.cache/nautilus-trader-agent`. Each ref lives in `refs/<ref>/` with an atomically replaced manifest and immutable generations. The previous generation is kept for one swap.

- Tags are immutable. Once cached they return `cached` without network until `--refresh` compares the peeled remote commit.
- Branches recheck after 24 hours with `git ls-remote`, returning `unchanged` or `updated`.
- A failed remote check with valid cache returns `stale` (exit 0), which must be reported. `--offline` uses only valid cache, and `--dry-run` writes nothing.
- No background scheduler is installed.

## Validation baseline

Validated on 2026-09-17 on macOS ARM64 with Python 3.12.10:

- `doctor` identified `nautilus_trader` 1.231.0 (`cython`) and 2.0.0rc5 (`pyo3`) in separate uv environments. It reported `pre_flag_required: true` from live PyPI metadata.
- `docs` synced `v1.231.0` (393 files) and `v2.0.0rc5` (353 files) in about 8 seconds each. A second run returned `cached` in 0.06 seconds.
- The v1/v2 name markers found no v1 names in the rc5 docs and examples. The v1 tag produced v2 hits only from its `interactive_brokers_v2` preview examples.
- The rc5 quickstart ran in a fresh v2 process with 902 fills and 451 positions. The same file under v1 failed with `ImportError: cannot import name 'OrderSide' from 'nautilus_trader.model'`.
- A v2 sandbox `LiveNode` built, registered a strategy and disposed without credentials. Nothing ran against a venue.

These are tested versions, not dependency pins.

## Sources

- [Documentation](https://nautilustrader.io/docs/latest/), [llms.txt](https://nautilustrader.io/docs/llms.txt) and the [Python API reference](https://nautechsystems.github.io/nautilus_docs/python-api-latest/)
- [Repository](https://github.com/nautechsystems/nautilus_trader), [`MIGRATION_V2.md`](https://github.com/nautechsystems/nautilus_trader/blob/develop/MIGRATION_V2.md) and [releases](https://github.com/nautechsystems/nautilus_trader/releases)
- [PyPI](https://pypi.org/project/nautilus_trader/) and [crates.io](https://crates.io/crates/nautilus-model)
- Community: [Discord](https://discord.gg/NautilusTrader) and [GitHub Discussions](https://github.com/nautechsystems/nautilus_trader/discussions)

The community skills surveyed during authoring had no license, and one targeted only v1, so this skill is independently authored.

# nextjs (vendored)

Frozen

Upstream removed this skill in [vercel/vercel-plugin#282](https://github.com/vercel/vercel-plugin/pull/282) (2026-10-01). `vendor.yaml` marks it `frozen:`, so `make sync` keeps the last-synced copy and no longer updates it. Next.js now ships version-matched docs in `node_modules/next/dist/docs/` (16.3+ `next dev` also generates `AGENTS.md`); prefer those for current APIs.

Vendored from [vercel/vercel-plugin/skills/nextjs](https://github.com/vercel/vercel-plugin/tree/main/skills/nextjs) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/nextjs/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/nextjs/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Next.js App Router expert guidance. Use when building, debugging, or architecting Next.js applications — routing, Server Components, Server Actions, Cache Components, layouts, middleware/proxy, data fetching, rendering strategies, and deployment on Vercel.

## What it teaches

The flagship Next.js skill in this repo. Ships an 18 KB SKILL.md plus 20+ reference files under `references/` (app-router-files, async-patterns, hydration-error, parallel-routes, rsc-boundaries, …) and an `overlay.yaml` metadata layer with `pathPatterns` for `app/**`, `pages/**`, `tailwind.config.*`, `tsconfig.json`. Triggers automatically when editing Next.js code.

## Related fullstack-nextjs skills

- [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md) — UI component layer on top of Next.js
- [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md) — TSX-level review checklist
- [`vercel-storage`](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md) — DB / Blob / KV integration patterns

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/nextjs/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/nextjs/SKILL.md) for the full instructions. Upstream source: [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin).

# openui-direct-provider

Local, provider-neutral companion to the vendored [`openui`](https://daviddwlee84.github.io/agent-skills/skills/openui/index.md) skill. It teaches an agent to add [OpenUI](https://www.openui.com/) generative UI to an app **while keeping inference on the user's own model provider**: OpenAI, Anthropic, Google, or any OpenAI-compatible or local endpoint. No hosted service sits in the request path.

## Why it exists

The official skill defaults to the paid OpenUI Gateway (see [Gateway-first by default](https://daviddwlee84.github.io/agent-skills/skills/openui/#gateway-first-by-default)). The OpenUI language, prompt generator, parser, and renderer are MIT-licensed packages that work with any provider. This skill builds on those packages and the MIT [`thesysdev/openui`](https://github.com/thesysdev/openui) docs, and adds a **neutrality rule**: Gateway and Autofix come up only if the user asks, or needs something only they provide. Even then, the agent labels them as paid hosted services and names the self-hosted alternative.

The pairing works like [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md) (local) and [`skill-creator`](https://daviddwlee84.github.io/agent-skills/skills/skill-creator/index.md) (vendored): each covers its own half and defers to the other. Both skills trigger on "OpenUI", so install the one that matches how you run inference:

| You want                                                        | Install                  |
| --------------------------------------------------------------- | ------------------------ |
| Your own provider, keys, and storage                            | `openui-direct-provider` |
| OpenUI Gateway / Cloud, managed history, Reliability Monitoring | `openui`                 |

## What it teaches

- The core flow:
- `defineComponent` / `createLibrary`
- `openui generate --spec`
- `generateSystemPrompt({ library, promptOptions })` **without** `cloud: true`
- the provider's own SDK
- `<Renderer>` with `onAction` / `onError`
- Backend recipes ([`references/backend-recipes.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/openui-direct-provider/references/backend-recipes.md)): OpenAI SDK, Vercel AI SDK with any provider, OpenAI-compatible/local base URLs, plain-text streams, and LangGraph, each paired with its Agent Interface stream adapter.
- Self-hosted repair ([`references/self-repair.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/openui-direct-provider/references/self-repair.md)):
- prevent errors with library design;
- detect them with the streaming parser or `Renderer onError`;
- repair with one bounded retry on the user's own model.
- Gotchas:
- agent runs of `openui create` scaffold the **Cloud** template (ask the user to pick *OpenUI Self-hosted* interactively);
- the CLI sends telemetry (`--no-telemetry`);
- npm lags behind `main`;
- model-id formats differ from Gateway's;
- UI-side `Query`/`Mutation` arguments are untrusted.

## Install

```
npx skills@latest add daviddwlee84/agent-skills/skills -s openui-direct-provider
```

## Canonical SKILL.md

See [`skills/local/openui-direct-provider/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/openui-direct-provider/SKILL.md).

# openui (vendored)

Vendored from [`thesysdev/skills/skills/openui`](https://github.com/thesysdev/skills/tree/main/skills/openui), the official coding-agent skill for [OpenUI](https://www.openui.com/). The [`thesysdev/openui`](https://github.com/thesysdev/openui) repo itself ships no `SKILL.md`; its `docs/public/AGENTS.md` and the `@openuidev/cli` scaffold point agents at this skill. It is synchronized through `vendor.yaml`. Do not edit the vendored files locally because `make sync` replaces them.

## What it teaches

OpenUI turns model output into live UI. The model writes **OpenUI Lang**, a compact line-oriented language, using the components of a **component library**. The server builds the system prompt from the library spec, and a streaming **renderer** in the browser draws the program with the same library.

`SKILL.md` is a router. It tells the agent to read `package.json`, the lockfile, and the installed `@openuidev/*` code first, and then to pick one reference per job:

| Job                                                          | Reference                                                                  |
| ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| New app or agent / add to an existing app                    | `new-app.md`, `existing-app.md`                                            |
| Backend on OpenUI Gateway (Chat Completions / Responses API) | `gateway.md`, `gateway-responses.md`                                       |
| Call your own provider directly                              | `direct-provider.md`, `autofix.md`                                         |
| Component libraries, Agent Interface, artifacts, theming     | `component-library.md`, `agent-interface.md`, `artifacts.md`, `theming.md` |
| Broken renders, monitoring, deploy, the language itself      | `reliability.md`, `deploy.md`, `openui-lang.md`                            |

It also includes a package map for `@openuidev/*` (lang-core, react-lang, react-ui, react-headless, server, the Vue/Svelte/Angular renderers, cli, …). Its rules cover API keys (never handle them), keeping an existing app's stack, and porting to Python from the JS packages.

## Gateway-first by default

This skill recommends a paid service

The upstream rule "Use OpenUI Gateway for inference" makes the agent route model calls through **OpenUI Gateway** (part of OpenUI Cloud) and list its benefits the first time it comes up. That happens even when you name OpenAI, Anthropic, or Google: the agent suggests using them through Gateway with BYOK. The provider-direct path (`references/direct-provider.md`) is used only when you ask for it explicitly. To get it, tell the agent something like *"call my provider directly, no Gateway"*.

Because vendored content is kept unedited, the rule stays as it is upstream. For a provider-neutral alternative, install the local [`openui-direct-provider`](https://daviddwlee84.github.io/agent-skills/skills/openui-direct-provider/index.md) skill. Both trigger on "OpenUI", so install the one that matches how you run inference.

## Install

```
npx skills@latest add daviddwlee84/agent-skills/skills -s openui
# or straight from upstream
npx skills@latest add thesysdev/skills
```

## Canonical SKILL.md

See [`skills/vendor/openui/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/openui/SKILL.md) for the full instructions.

# project-knowledge-harness

A lightweight, file-based memory harness that gives any software project three sharply-separated surfaces:

| Surface              | Time direction | Question it answers                             | Access pattern                      |
| -------------------- | -------------- | ----------------------------------------------- | ----------------------------------- |
| `TODO.md`            | Future         | "What might we do later?"                       | Read top to bottom (priority lanes) |
| `backlog/<slug>.md`  | Future         | "What was the analysis behind this idea?"       | Indexed from `TODO.md`              |
| `pitfalls/<slug>.md` | **Past**       | **"I see error X — has this happened before?"** | **Grep symptom keywords**           |

The skill exists to stop two common failure modes: valuable investigation evaporating from chat history, and the graveyard of `IDEAS.md` / `ROADMAP.md` / `WISHLIST.md` / `LESSONS.md` files that nobody maintains.

## When the skill triggers

Future-direction signals: "where should ideas go?", "maybe later", "nice to have", "工程量太大需要再評估", "先記下來".

Past-direction signals: "save this troubleshooting", "踩過的坑", scattered "Common issues" sections across `docs/`.

Either: "is there a place for X?" where X is metadata about decisions or history rather than current features.

## Structure of the skill itself

```
skills/local/project-knowledge-harness/
├── SKILL.md                      # ~170-line entry point; loads on activation
├── assets/                       # Copied into target projects
│   ├── TODO.md.template
│   ├── backlog-README.md.template
│   ├── backlog-doc.md.template
│   ├── pitfalls-README.md.template
│   ├── pitfall-doc.md.template
│   ├── agent-guidance.md.template   # Snippet for AGENTS.md / CLAUDE.md
│   ├── readme-roadmap.md.template   # Snippet for README.md
│   └── td-routing.md.template       # td ↔ TODO.md routing snippet (when td is present)
├── scripts/                      # Executed during setup or by the agent
│   ├── init.sh                   # One-shot setup of all of the above
│   ├── todo-kanban.sh            # Validator + Markdown / JSON board renderer
│   ├── promote-todo.sh           # Atomic active → ## Done move + re-validate
│   ├── start-todo.sh             # Optional td bridge: start an item as a td issue
│   └── _lib/                     # Shared TODO parser + td bridge (sourced)
└── references/                   # Loaded on demand from SKILL.md links
    ├── tag-schema.md             # Priority × effort schema and exact syntax
    ├── when-to-add-docs.md       # Backlog vs pitfall vs invariant decision rules
    ├── anti-patterns.md          # Mistakes to avoid
    ├── deployment-exclusion.md   # Per-mechanism ignore-rule cheatsheet
    └── integrating-trackers.md   # td / GitHub Issues / Linear layering
```

`SKILL.md` is intentionally short and points to `references/*.md` so the agent only loads decision detail when it needs it ([progressive disclosure](https://agentskills.io/specification#progressive-disclosure)).

## How to apply the skill in a fresh repo

The default workflow is one command:

```
skills/local/project-knowledge-harness/scripts/init.sh \
  --target /path/to/project \
  --project-name "My Project" \
  --deployment chezmoi   # or npm | pip | docker | none
```

This is idempotent — re-running it skips files that already exist and snippets whose sentinel marker is already present. Pass `--force` to overwrite the three template files; snippets are still appended only once.

`init.sh` performs:

1. Render `TODO.md`, `backlog/README.md`, `pitfalls/README.md` from `assets/*.template`, substituting `<PROJECT NAME>`, `<DEPLOYMENT MECHANISM>`, `<IGNORE FILE>`.
1. Append the agent guidance snippet to `AGENTS.md` / `CLAUDE.md` (auto-detected; override with `--agent-contract`).
1. Append the "Roadmap & lessons learned" snippet to `README.md` (skip with `--readme ""`).
1. Run `todo-kanban.sh --validate-only TODO.md` to confirm the file is machine-readable.
1. Print the deployment-specific lines you should add to your ignore file.

`init.sh` deliberately does **not** edit `.gitignore` / `.chezmoiignore.tmpl` / `.dockerignore` — the blast radius is too high for an automated tool. Use the printed cheatsheet as your TODO.

## Bundled scripts in detail

### `scripts/todo-kanban.sh`

Validates the format and renders a kanban-style board.

```
scripts/todo-kanban.sh                    # default: TODO.md, Markdown board
scripts/todo-kanban.sh path/to/TODO.md    # explicit file
scripts/todo-kanban.sh --validate-only    # exit code only
scripts/todo-kanban.sh --json             # machine-readable lane summary
```

Validation rules:

- First non-empty heading must be `# TODO`.
- Sections must appear in order: `## P1`, `## P2`, `## P3`, `## P?`, `## Done`. Additional headings after `## Done` are allowed (e.g., a `## Notes` or prune log section).
- Top-level list items are validated:
- `P1` / `P2` / `P3`: `- [ ] **[Effort] Title** — description`
- `P?`: `- [ ] **[?/Effort] Title** — description`
- `Done`: `- ✅ [YYYY-MM-DD] [P#/Effort] Title — summary` Effort is one of `S`, `M`, `L`, `XL`. Active items may end with `→ [research](backlog/<slug>.md)`.
- Anything that is **not** a top-level `- [ ]` / `- ✅` item — prose, blockquotes, HTML comments, `---` rules, indented sub-bullets — is ignored and does not count toward lane totals. This lets you write inline guidance under each section without breaking the validator.
- Compatible with macOS system Bash 3.2 (no associative arrays, no `readarray`).

### `scripts/promote-todo.sh`

Move an active item from `P1` / `P2` / `P3` / `P?` into `## Done` with the dated `Done` syntax, then re-validate.

```
scripts/promote-todo.sh \
  --title "<substring of the item's title>" \
  --summary "<one-line shipped summary>"
```

Behaviour:

- Substring match against the title field (case-sensitive). Refuses to run if zero or multiple active items match — refine the substring.
- Inserts the new `Done` entry immediately after the `## Done` heading, using `date -u +%Y-%m-%d` (override with `--date YYYY-MM-DD`).
- Looks up the validator next to itself; if validation fails after the edit, the original file is restored.
- Use `--dry-run` to preview the rewritten file without mutating.

### `scripts/start-todo.sh` (optional td bridge)

For projects that also use [td](https://github.com/marcus/td) for in-flight agent work. Git stays the source of truth, and the link runs one way: a td issue labelled `pkh` with the item's exact title points at the `TODO.md` item. `TODO.md` never stores td ids, because they are machine-local unless td-sync is set up.

```
scripts/start-todo.sh --title "<substring>"   # create or reuse the issue, then td start
```

- `PKH_TD=auto|on|off` (default `auto`): the bridge is active only when td resolves a project from the current directory, including worktrees. Without td every script behaves as before.
- `promote-todo.sh` prints a harvest-then-review hint for the open issue and never closes it.
- `todo-kanban.sh` marks in-flight items with `🔧 td-xxxx` and lists orphaned `pkh` issues. `--validate-only` never queries td.
- `init.sh --td auto|on|off` appends the routing snippet to the agent contract.

### `scripts/init.sh`

See the workflow above. Notable flags:

- `--agent-contract FILE` — override the auto-detected `AGENTS.md` / `CLAUDE.md` / `.opencode/AGENTS.md` / `.cursorrules` choice.
- `--readme ""` — skip the README snippet (useful for repos with their own conventions).
- `--no-validate` — skip the final `todo-kanban.sh --validate-only` pass (for scripted bootstraps where validation is checked separately).
- `--td auto|on|off` — append the td ↔ `TODO.md` routing snippet when td is detected (`auto`), always (`on`), or never (`off`).

## Reference docs the skill loads on demand

- [`references/tag-schema.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/tag-schema.md) (also surfaced as a human-readable page: [Tag schema](https://daviddwlee84.github.io/agent-skills/reference/tag-schema/index.md))
- [`references/when-to-add-docs.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/when-to-add-docs.md)
- [`references/anti-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/anti-patterns.md)
- [`references/deployment-exclusion.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/deployment-exclusion.md)
- [`references/integrating-trackers.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/integrating-trackers.md)

## How this repo uses the skill on itself

The repo's own [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md), [`backlog/`](https://github.com/daviddwlee84/agent-skills/tree/main/backlog) (when populated), [`pitfalls/`](https://github.com/daviddwlee84/agent-skills/tree/main/pitfalls) (when populated), and [`scripts/`](https://github.com/daviddwlee84/agent-skills/tree/main/scripts) `todo-kanban.sh` / `promote-todo.sh` are a live example of the harness applied to a real project. The [`make kanban`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile) target wraps the validator/renderer.

# pueue-job-queue

Drive [Nukesor/pueue](https://github.com/Nukesor/pueue) — a daemon-backed shell job queue — for queued, parallel, scheduled, and lightly-DAG'd shell work. The skill is a **CLI bridge**, not a custom scheduler: it wraps `pueue add --after`, `pueue status --json`, and `pueue log --json` so an agent can submit, batch, chain, wait, and retry without losing track of what's running.

| Surface                                                                                                                                                  | Question it answers                                                                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `check-daemon.sh`                                                                                                                                        | "Is `pueued` running, and where do logs live on this OS?"                                                         |
| `submit.sh`                                                                                                                                              | "Submit one task and give me a parseable `{task_id, label, group, after}`."                                       |
| `submit-dag.py`                                                                                                                                          | "Submit this whole fan-out / fan-in pipeline with deps wired — in a fresh isolated group sized to the DAG width." |
| `wait.py`                                                                                                                                                | "Block until these tasks finish, then summarize success/failure."                                                 |
| `cleanup.sh`                                                                                                                                             | "Reclaim disk + status latency: prune old tasks, empty groups, log files."                                        |
| [`references/cli-cheatsheet.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/cli-cheatsheet.md)       | "What un-wrapped `pueue` subcommand do I reach for?"                                                              |
| [`references/json-schema.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/json-schema.md)             | "What does `pueue status --json` actually look like? What's the QUERY DSL syntax?"                                |
| [`references/dag-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/dag-patterns.md)           | "How do I express fan-out / fan-in / diamond shapes?"                                                             |
| [`references/daemon-and-config.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/daemon-and-config.md) | "How do I auto-start `pueued` on macOS / Linux?"                                                                  |
| [`references/remote-daemon.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/remote-daemon.md)         | "The daemon is on another machine — can I drive it, and should I?"                                                |

The skill exists to keep three things out of an agent's way:

1. **Bookkeeping** — task ids, dependency wiring, group autocreate, defensive id parsing of `pueue add --print-task-id`.
1. **Schema drift** — `pueue status --json` uses serde tagged enums (`{"Done": {"result": "Success" | "DependencyFailed" | "Killed" | {"Failed": <int>}}}`). `wait.py` classifies all variants and returns predictable exit codes (`0` ok, `5` any failure, `6` timeout).
1. **Footguns** — `pueue add -- bash -c 'sleep 60'` does NOT preserve the inner quote (pueue re-shells); `pueue kill --all` also pauses every group; `pueue restart` (default) creates a NEW id; `pueue clean` (default) wipes failures too. The SKILL.md has a 10-item gotcha list covering each of these.

## When the skill triggers

- "Run these 30 commands, max 4 at a time" → set group parallelism, loop `submit.sh --group sweep`.
- "Kick off a long training job and let me close my laptop" → `submit.sh -- ./train.sh` (pueue persists across reboots).
- "Run task B only after task A succeeds" → `submit.sh --after $A_ID -- ./b.sh`.
- "Fan out 4 trainings, then evaluate" → `submit-dag.py dag.yaml`.
- "Schedule this for tonight" → `submit.sh --delay 6h -- ./nightly.sh`.
- The user says **pueue / pueued / pueue add / pueue queue / pueue group** or asks about a "task queue for shell jobs".

## When it doesn't

- One short shell command — just run it. Pueue adds daemon overhead.
- Cross-host scheduling, OR-deps, conditional branching, retry-with-backoff, typed task IO — escalate to **Airflow / Prefect / Dagster / DVC / Slurm**. [`references/dag-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/dag-patterns.md) has a decision table.
- Long-running services — that's `systemd` / `launchd`.

## Structure

```
skills/local/pueue-job-queue/
├── SKILL.md                                  # ~275 lines
├── scripts/
│   ├── check-daemon.sh                       # bash; daemon health + auto-start
│   ├── submit.sh                             # bash; submit-one wrapper, JSON out, group autocreate
│   ├── wait.py                               # PEP 723; block until terminal, state-change events, JSON summary
│   ├── submit-dag.py                         # PEP 723 (pyyaml); DAG submitter with --isolated-group / --auto-parallel
│   └── cleanup.sh                            # bash; prune tasks + empty groups + old log files
├── references/
│   ├── cli-cheatsheet.md                     # un-wrapped commands
│   ├── json-schema.md                        # observed status --json shape (4.0.2) + QUERY DSL + jq recipes
│   ├── dag-patterns.md                       # fan-out / fan-in / diamond + escalation table
│   ├── daemon-and-config.md                  # pueued setup per OS, config knobs, log paths
│   └── remote-daemon.md                      # SSH socket forwarding, TCP+TLS, the client-resolved-cwd trap
├── assets/
│   ├── dag.example.yaml                      # 5-task fan-out / fan-in fixture
│   └── pueue.yml.example                     # config with `pause_group_on_failure: true`
└── tests/
    ├── conftest.py                           # isolated pueued fixture, skip if pueue absent
    ├── test_submit.py                        # submit.sh paths + dependency failure
    ├── test_dag.py                           # topo invariant, cycle/unknown/missing-cmd, isolated-group
    ├── test_wait.py                          # success/failure/timeout exit codes
    ├── test_contracts.sh                     # bash --help/error-code contract
    └── fixtures/simple-dag.yaml              # 4-task diamond
```

## Always pass a label

`pueue status` shows the **label** column before the command. In a busy queue, scanning labels is the only way to tell `train.py` runs apart at a glance. The skill's gotchas section opens with:

> Always pass `--label` when submitting, and bias toward names that distinguish *this* task from its siblings.

Convention: `<verb>-<subject>-<key>` (≤30 chars). Encode the discriminator (seed, dataset slice, model variant) — not the command:

| Good                      | Bad                               |
| ------------------------- | --------------------------------- |
| `train-baseline-seed1`    | `task1`                           |
| `eval-prod-2026q1`        | `python eval.py --quarter 2026q1` |
| `nightly-featurize` (DAG) | `step-2-of-5`                     |

`submit-dag.py --label-prefix <run>-` produces `<run>-<task_name>` so `wait.py --label-prefix <run>-` selects the whole graph and `pueue clean` can be filtered later.

## Empirical schema

Pueue's JSON output isn't formally documented in the wiki. The skill ships the observed shape on **pueue 4.0.2** in [`references/json-schema.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/json-schema.md), including the diagnostic snippet to re-verify on a different major. Key shape:

```
{
  "tasks": {
    "<id>": {
      "id": 17,
      "label": "train-baseline-seed1",
      "group": "ml",
      "dependencies": [12, 14],
      "status": {
        "Done": {
          "enqueued_at": "...", "start": "...", "end": "...",
          "result": "Success"            // or "DependencyFailed" | "Killed" | {"Failed": 1}
        }
      }
    }
  },
  "groups": {
    "default": {"status": "Running", "parallel_tasks": 1}
  }
}
```

`wait.py` classifies every variant; if a future pueue release adds one (say `Suspended`), the test suite catches it before the skill goes silent.

## Verification

The skill ships **22 pytest cases** that spin up an isolated `pueued` under a tempdir-scoped config — your real queue is never touched — plus a bash exit-code contract test. Both auto-skip if `pueue` / `pueued` aren't on `PATH`. `lint-skill --strict` is clean (0 errors, 0 warnings).

```
uv run --extra dev pytest skills/local/pueue-job-queue/tests/ -q
bash skills/local/pueue-job-queue/tests/test_contracts.sh
bash skills/local/skill-author/scripts/lint-skill.sh skills/local/pueue-job-queue --strict
```

The pytest fixture uses `pueue reset --force` between tests because plain `pueue kill --all` also pauses every group — a non-obvious failure mode worth documenting (see SKILL.md gotchas).

## Remote daemons: yes, but submit over SSH

Pueue can't schedule *across* hosts, but a local client **can** drive a single remote `pueued` — with full control (`add`, `kill`, `log`, `follow`), not just status. [`references/remote-daemon.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/pueue-job-queue/references/remote-daemon.md) covers the setup; the short version is that the recommended path changes nothing on the server:

```
# forward the daemon's own unix socket — no server reconfiguration, no TLS
ssh -f -N -L ~/.config/pueue/remote/remote.sock:/run/user/1000/pueue_you.socket myhost
pueue -c ~/.config/pueue/remote/client.yml status
```

Verified end to end with a macOS client (4.0.4) against a Linux daemon (4.0.2). Findings worth knowing before you try it:

- **`read_local_logs: false` is mandatory** on the client, or `log` / `follow` look for the daemon's logs on your own disk and find nothing.
- **A version mismatch warns but works** — `Different protocol version detected '0.30.1'` on every command, then normal behaviour. Filter it from stderr; stdout JSON stays clean.
- **Submitting is the part that doesn't travel.** `pueue add` records the working directory and canonicalizes it *on the client*, so a remote submit fails three ways: the local cwd gets sent and the task ends `FailedToSpawn`; a remote-only path is rejected outright (`Failed to canonicalize given working directory path`); and on macOS `/tmp` is silently rewritten to `/private/tmp`. Only a path that exists and resolves identically on both machines works.

So the honest split is **`ssh host 'pueue add ...'` to submit, forwarded client to read and control.**

That investigation also surfaced a real bug in this skill, now fixed: pueue's `result` is a tagged enum and `FailedToSpawn` is dict-shaped (`{"FailedToSpawn": "<os error>"}`), but `wait.py` matched against an enumerated list of *bad* variants — so it fell through and **`wait.py` returned exit 0 for a task that never started**. It now allowlists `Success` and fails closed on anything else, which also makes it safe against future pueue variants. See [the pitfall](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/pueue-remote-add-fails-to-spawn-on-client-resolved-cwd.md).

# python-project-best-practice

An opinionated baseline for Python projects that both people and agents work in — and the two entry points that get you there: **scaffold a new project**, or **score and modernize an existing one**. Same conventions, one skill.

The bias throughout: every operation has one canonical, discoverable, non-interactive command. That is what makes a repo workable by an agent, and it happens to be what makes it pleasant for humans.

> Scope note: this skill deliberately does **not** restate [`verifiable-surfaces`](https://daviddwlee84.github.io/agent-skills/skills/verifiable-surfaces/index.md) (CLI surface design), [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) (dual-mode notebooks), [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md) (production FastAPI), or [`mkdocs-site-bootstrap`](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md) (docs sites). It links to them and fills the gap none of them covered: the project itself.

## The defaults it argues for

| Concern       | Default                                                         | Why not the alternative                                                                                        |
| ------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Environment   | `uv` + committed `uv.lock` + `.python-version`                  | poetry/pip-tools/conda all solve less of it; `uv.lock` never constrains your users                             |
| Layout        | `src/<pkg>/`                                                    | a flat layout imports the source dir, so missing `__init__.py` / package data passes tests and breaks installs |
| Dev deps      | PEP 735 `[dependency-groups]`                                   | an extra is **published**; your test runner should not be in your users' dependency graph                      |
| Lint + format | `ruff check` + `ruff format`                                    | `ruff format` *is* a black reimplementation — running both makes them fight                                    |
| Types         | `ty` (pinned exactly), mypy documented as the conservative swap | `ty` is 0.0.x: fast enough that people run it, unstable enough that `>=` is a trap                             |
| CLI           | Tyro, one frozen dataclass per subcommand                       | commands as data are testable without argv or subprocesses                                                     |
| Completion    | `--tyro-write-completion`                                       | built in; shtab/argcomplete wiring is redundant                                                                |
| Logging       | loguru at entry points, stdlib in library code                  | a library that calls `loguru.logger.add()` hijacks the importing program's logging                             |
| Config        | pydantic-settings, defaults < `.env` < environment              | and `<tool> info` prints what actually resolved                                                                |
| Task runner   | `Justfile` (taskipy noted)                                      | `just` needs no Python, so `just setup` can bootstrap the venv itself                                          |

## What ships

- The full SKILL.md ([SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/SKILL.md)) — decision spine, two workflows, and a 22-item gotchas section.
- **Nine references**, loaded on demand:
  - [`uv-and-pyproject.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/uv-and-pyproject.md) — commands, groups vs extras, lockfile policy, interpreter pinning, build backends, `uv tool install` / Trusted Publishing, workspaces.
  - [`tyro-cli.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/tyro-cli.md) — dataclass commands, subcommand unions, module splits, completion, config objects.
  - [`quality-gates.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/quality-gates.md) — ruff rule selection, `ty` vs mypy, pytest layout, coverage placement, CI, pre-commit.
  - [`logging-and-config.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/logging-and-config.md) — the app/library layering rule, the three loguru traps, pydantic-settings, direnv.
  - [`notebooks-and-widgets.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/notebooks-and-widgets.md) — where notebooks live, dual mode, ruff conflicts, packaged anywidgets.
  - [`api-and-services.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/api-and-services.md) — the FastAPI stub's boundary, and a decision rule for **skill vs MCP** (usually: neither, add a subcommand).
  - [`rust-pyo3.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/rust-pyo3.md) — maturin layout, abi3, the stale-binary trap, why type checkers need a hand-written `.pyi`.
  - [`agent-interface.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/agent-interface.md) — AGENTS.md vs README vs the package's own skill, the symlink rule, the docs-drift gate.
  - [`legacy-refactor.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/references/legacy-refactor.md) — the migration ladder, one rung per PR, and what *not* to migrate.
- **Two PEP 723 scripts** (`uv run`, inline deps, JSON on stdout):
  - [`new-python-project.py`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/scripts/new-python-project.py) — scaffold from the bundled template tree. `--profile {minimal,cli,lib,api,ml,rust}`, `--dry-run`, `--force`, `--no-git`. Offline; writes nothing outside the target directory.
  - [`audit-python-project.py`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/scripts/audit-python-project.py) — 26 read-only checks with evidence and a fix hint, plus an ordered `migration_plan[]`. `--format {json,table}`, `--fail-on {fail,warn,never}`. Deliberately has **no `--fix`**.
- **A template tree** (`assets/project/`, 29 `.tmpl` files) plus [`assets/manifest.toml`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/python-project-best-practice/assets/manifest.toml) mapping each destination to the profiles that get it. A file not in the manifest is never copied, and the generator exits 4 if the manifest and the tree disagree either way.

## Profiles

Additive, so "agentic later" costs nothing now.

| Profile           | Adds                                                     |
| ----------------- | -------------------------------------------------------- |
| `minimal`         | package, tests, Justfile, CI, AGENTS.md                  |
| `cli` *(default)* | Tyro CLI, loguru, pydantic-settings, `[project.scripts]` |
| `lib`             | publishing metadata, `py.typed`                          |
| `api`             | FastAPI app with `/docs` and `/openapi.json`             |
| `ml`              | a marimo notebook that is also a batch CLI               |
| `rust`            | maturin backend, PyO3 crate, `.pyi` stubs                |

## The docs-drift gate

The piece worth stealing even if you use none of the rest. Prose about a CLI rots the first time someone renames a flag, so the generated project makes it a build artifact instead:

```
just docs-sync     # rewrite the CLI block in AGENTS.md + .agents/skills/ from --help
just docs-check    # exit 1 if the committed block is stale — part of `just check`
```

`scripts/sync_agent_docs.py` runs `python -m <pkg>.cli --help` plus each subcommand's `--help`, strips ANSI, and splices the result between `<!-- BEGIN CLI -->` markers. Because `--check` runs in the gate and in CI, a flag rename that skips the docs fails the build.

## Verified, not asserted

Every profile was generated and run before shipping: `uv sync` → `just check` (ruff format, ruff lint, `ty`, pytest, docs-drift) green on all six, coverage between 89% and 100%, and `uv tool install` → run → uninstall exercised end-to-end. Two claims changed as a result of checking them:

- **Tyro already ships shell completion.** The first draft told you to wire up shtab. It does not need it — `--tyro-write-completion {bash,zsh,tcsh,fish} PATH` is built in, and `--tyro-print-completion` is deprecated because a stray `print()` corrupts the output.
- **`uv sync` silently keeps a stale Rust binary.** Editing `rust/src/lib.rs` and re-running `uv sync` leaves the old `.so` in place with no warning — including any debug prints you just added. Confirmed by experiment; `uv sync --reinstall-package <slug>` is the fix.

## Related

[`verifiable-surfaces`](https://daviddwlee84.github.io/agent-skills/skills/verifiable-surfaces/index.md) · [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) · [`agent-history-hygiene`](https://daviddwlee84.github.io/agent-skills/skills/agent-history-hygiene/index.md) · [`mkdocs-site-bootstrap`](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md) · [`git-workflow`](https://daviddwlee84.github.io/agent-skills/skills/git-workflow/index.md) · [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) · [`fastapi-ai-patterns`](https://daviddwlee84.github.io/agent-skills/skills/fastapi-ai-patterns/index.md) · `cli-release-distribution`

# quantatitive-factor-researcher

A persona-style skill that turns the agent into a quantitative factor researcher for Python-based investment-strategy work. Use it when the user wants help designing, evaluating, or implementing factor-based strategies end-to-end: data acquisition → feature engineering → signal testing → risk control → backtest and performance evaluation.

## When the skill triggers

- The user asks for help building or analysing alpha / risk factors.
- The user mentions tools like `pandas`, `numpy`, `scikit-learn`, `vectorbt`, `PyTorch`, MLflow, or DVC in the context of trading research.
- The user wants performance metrics interpreted (Sharpe Ratio, IR, Tracking Error, Drawdown, etc.).
- The user requests time-series-aware cross-validation (Purged Group-Time-Series Split, walk-forward).

Do **not** use this skill for general Python coding, generic data analysis, or unrelated finance topics (accounting, macro forecasts) — those don't benefit from the persona overhead.

## Structure of the skill

```
skills/local/quantatitive-factor-researcher/
└── SKILL.md   # persona + responsibilities + style/technical conventions
```

Single-file skill — no `assets/`, `scripts/`, or `references/`. The content is mostly persona + style guidance, which is the "right size" for inline content. If future additions grow beyond ~500 lines (e.g., reusable backtest scaffolding, evaluation report templates), promote the extra material into `references/` and `assets/` rather than letting `SKILL.md` swell.

## What the skill encodes

### Core responsibilities

1. Provide a rigorous, reproducible quant-research pipeline.
1. Write and explain high-quality Python with type hints and English comments.
1. Explore and optimise alpha / risk factors with statistical and ML methods (genetic algorithms, tree models, deep learning, Bayesian).
1. When useful, supply LaTeX (English variables) and Matplotlib / Plotly chart suggestions to explain methodology and results.
1. Interpret backtest metrics and suggest improvements.

### Language & style rules

- If the user opens in Chinese, reply in Traditional Chinese with English terminology in parentheses; specialist terms always carry the English form.
- LaTeX formulas use English variables and comments.
- Python comments are in English; every function has type annotations and a docstring.
- Replies are structured (sections, bullets) but not verbose.
- External references (papers, GitHub repos, datasets) include full citation format.

### Technical conventions

- Vectorised operations and built-ins by default; explain parallel / GPU acceleration when relevant.
- Configuration-driven pipelines, with hooks into MLflow / DVC for experiment tracking.
- Strict against data leakage: Purged Group-Time-Series Split, walk-forward validation, out-of-sample testing.

## Limitations and known gaps

- The skill ships no example notebooks or backtest scaffolding yet — it is purely a persona. Adding `assets/` with reusable factor-evaluation scaffolds is a candidate `[?/L]` item for [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md).
- It does not currently bundle a "preferred data source" decision — that interacts with the broader "Financial data sources skill set" P? item already in the repo backlog.

# raycast-extension-dev

Build, verify, and ship [Raycast](https://developers.raycast.com/) extensions in TypeScript. Raycast's own docs cover what `List` and `Form` accept; this skill covers the other 20% — **what the toolchain does not check, what the runtime does not provide, and what the Raycast Store checks that the linter does not**.

Every claim in it was paid for once while building [Pueue for Raycast](https://github.com/daviddwlee84/Pueue-Raycast-Extension), and most of them trace back to a file in that repo's [`pitfalls/`](https://github.com/daviddwlee84/Pueue-Raycast-Extension/tree/main/pitfalls).

| Surface                                                                                                                                                                  | Question it answers                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `new-raycast-extension.sh`                                                                                                                                               | "Scaffold me an extension that is gated from the first commit."               |
| `check-store-readiness.sh`                                                                                                                                               | "What will store review reject that `ray lint` just passed?"                  |
| [`references/runtime-and-subprocess.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/runtime-and-subprocess.md) | "Why is my binary not found, when `which` finds it instantly?"                |
| [`references/manifest-and-commands.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/manifest-and-commands.md)   | "What can a `package.json` command / preference / argument actually declare?" |
| [`references/data-and-state.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/data-and-state.md)                 | "Why does my action flash, revert, and then re-apply?"                        |
| [`references/ui-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/ui-patterns.md)                       | "Which List/Form/ActionPanel idiom, and why did my dropdown reset itself?"    |
| [`references/menu-bar.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/menu-bar.md)                             | "How do I show a count without opening Raycast, and why is mine stale?"       |
| [`references/store-publishing.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/references/store-publishing.md)             | "What is left before I can submit, and what can never be automated?"          |

## The gate, and why it is four commands

The single most expensive fact about the Raycast toolchain:

| Command                | Catches                                                                | Misses                                           |
| ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
| `tsc --noEmit`         | types                                                                  | manifest, formatting, runtime shape              |
| `node dev-check.js`    | your own invariants, wire shapes, generated argv                       | anything you did not assert                      |
| `ray lint`             | manifest schema, icons, ESLint, Prettier, reserved-shortcut collisions | types                                            |
| `ray build` (`-e dev`) | syntax, that esbuild can bundle it                                     | **types — esbuild strips them without checking** |
| `ray build -e dist`    | the above **plus types** (it runs `tsc -p tsconfig.json --noEmit`)     | manifest, formatting                             |

Measured on a scaffold carrying one genuine `TS2345`: `ray build` exits **0** and prints `ready - built extension successfully`; `ray build -e dist` exits **1** and reports it. The dist build is therefore a stronger pre-submit check than most people realise — but `npm run build`, `just build`, and `ray develop` are all the *dev* build, which is precisely why a type error survives long enough to ship.

Two real bugs took that route in the source extension: a `MutatePromise<GroupMap>` passed where `MutatePromise<State>` was expected — which at runtime would have emptied the list on every action — and a `ReactNode`/`JSX.Element` clash caused by `@raycast/api` bundling its own copy of `@types/react`. Neither produced a single line of output.

The skill ships that gate as `assets/Justfile.template`, and the scaffolder writes it into every new extension.

## What `ray lint` does not check

Verified, not assumed: **`ray lint` exits 0 with a completely empty `metadata/` directory.** Its "validate extension metadata" stage passes. So the linter cannot be your submission gate — screenshot count and dimensions, icon size, whether the icon is still a placeholder, the CHANGELOG placeholder, and a real `author` are all review-time requirements nothing runs locally.

`check-store-readiness.sh` covers exactly that column, emitting a JSON array of `{id, status, detail, fix}` and exiting `4` when something fails, `3` when a check had to be skipped for a missing tool (skipped is never reported as passed).

## When the skill triggers

- "Build me a Raycast extension for X" / "wrap this CLI in Raycast"
- "It works in `npm run dev` but not from Raycast" — the launchd PATH trap, which the dev console structurally cannot reproduce
- "The menu bar shows the wrong count / nothing / stale data"
- "My action flashes the new state, reverts, then re-applies"
- "Get this ready for the Raycast Store"

## When it doesn't

- **Raycast Script Commands** — a separate repo, no manifest, no React.
- **Generic React/TSX quality** → `react-best-practices`.
- **The wrapped CLI's own semantics** → that tool's skill, or its `--help`.
- **AI Extensions without Raycast Pro** — `tools[]` is Pro-gated, and there is no confirmation surface inside a tool call, so a first version must be read-only.
- **Taking the screenshots.** The skill verifies their count and dimensions. It cannot capture a window, and neither can any CLI.

## Structure

```
skills/local/raycast-extension-dev/
├── SKILL.md                              485 lines — workflows A-F + 27 gotchas
├── references/
│   ├── runtime-and-subprocess.md         launchd env, path probing, execFile, streaming, error taxonomy
│   ├── manifest-and-commands.md          every manifest field + the schema length minimums
│   ├── data-and-state.md                 hooks, cache-key scoping, the reconcile measurement loop
│   ├── ui-patterns.md                    List/Detail/Form/ActionPanel, dropdowns, shortcuts, markdown fencing
│   ├── menu-bar.md                       every MenuBarExtra constraint with its consequence
│   └── store-publishing.md               checklist, screenshot mechanics, review criteria
├── scripts/
│   ├── new-raycast-extension.sh          scaffold a gated extension (exit 0/1/2/3/4)
│   └── check-store-readiness.sh          the store checks ray lint skips (exit 0/1/2/3/4)
└── assets/
    ├── Justfile.template                 the four-stage gate
    ├── tsconfig.json.template            note: include must list raycast-env.d.ts
    ├── eslint.config.mjs.template        flat config for @raycast/eslint-config v2
    ├── package.json.template             manifest skeleton, known-good deps
    ├── dev-check.ts.template             the no-test-runner harness
    ├── transport.ts.template             the Mutation data-union seam
    ├── error-descriptor.tsx.template     one descriptor, four renderers
    ├── metadata-README.md.template       makes "Save to Metadata" appear
    └── extension-icon.placeholder.png    512x512 — its sha256 is its own tripwire
```

## Three ideas the skill argues for

**Model mutations as a data union, not argv strings.** A `Mutation` type with one variant per operation is what makes the transport a swappable seam. If `mutate()` took a `string[]` of argv, a socket or HTTP transport would have to parse argv back into intent — which is not a seam, it is a shell.

**There is no test runner, and adding one is store-review noise.** Keep every pure module free of `@raycast/api` imports, and assert them from one `dev-check.ts` compiled by the already-installed `tsc` and run under `node`. That import discipline is the whole precondition — a barrel that pulls in the transport pulls in `@raycast/api` with it, and then nothing is assertable.

**One error descriptor, N renderers.** A `structural` flag decides whether cached data is a moment stale or a snapshot of a system nobody can reach; actions stay data rather than JSX so the menu bar — which cannot render a `List.EmptyView` — maps them to its own primitives instead of growing a second copy that drifts.

## Verification

The skill was built against the real toolchain, not from documentation:

```
# scaffold, then run every stage of the gate on the result
bash scripts/new-raycast-extension.sh --dir /tmp/trial --name trial --author me \
  --command tasks:view --command queue-menu:menu-bar --command quick:no-view
cd /tmp/trial && npm install
npx ray build && npx tsc --noEmit && npx ray lint    # all three exit 0
```

And the claim the skill rests on, reproduced:

```
npx ray lint;                              echo $?   # 0 — with metadata/ EMPTY
bash scripts/check-store-readiness.sh .;   echo $?   # 4 — names the screenshots
```

Adding three correctly-sized PNGs shrinks the failure list by exactly one id and still reports `icon-not-placeholder`, which is how you know the checker discriminates rather than merely counting files.

The canonical source is [`SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/raycast-extension-dev/SKILL.md).

# react-best-practices (vendored)

Vendored from [vercel/vercel-plugin/skills/react-best-practices](https://github.com/vercel/vercel-plugin/tree/main/skills/react-best-practices) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/react-best-practices/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/react-best-practices/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> React best-practices reviewer for TSX files. Triggers after editing multiple TSX components to run a condensed quality checklist covering component structure, hooks usage, accessibility, performance, and TypeScript patterns.

## What it teaches

70+ rules across 8 categories from Vercel Engineering. Includes a `validate` rule that nudges legacy CSS-in-JS / MUI / Chakra users toward shadcn/ui + Tailwind for the modern Vercel stack. Auto-triggers when editing `src/components/**/*.tsx`, `app/components/**/*.tsx` etc.

## Related fullstack-nextjs skills

- [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md) — same upstream repo, deeper Next.js framework knowledge
- [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md) — component library this skill explicitly recommends

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/react-best-practices/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/react-best-practices/SKILL.md) for the full instructions. Upstream source: [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin). See also [Introducing: React Best Practices (Vercel blog)](https://vercel.com/blog/introducing-react-best-practices).

# security-audit (vendored)

Vendored from Cloudflare's [`cloudflare/security-audit-skill/skills/security-audit`](https://github.com/cloudflare/security-audit-skill/tree/main/skills/security-audit) skill under MIT. It is the single-repo starting point behind Cloudflare's vulnerability discovery harness (see [Build your own vulnerability harness](https://blog.cloudflare.com/build-your-own-vulnerability-harness)). It is synchronized through `vendor.yaml`, and `license_path: LICENSE` copies the repo-root license into `LICENSE.txt`. Do not edit the vendored files locally because `make sync` replaces them.

## What it teaches

The skill makes an agent a defensive, source-first security reviewer. A finding counts only if it crosses a real trust boundary: the agent must name the lower-trust principal, the input, the control that was bypassed, the affected resource, and the observed result. It then recommends the smallest source fix that closes the hole.

It has two operating modes:

- **Guidance mode** (default) is for security questions, focused reviews, and triage. The agent uses only the relevant parts and writes no audit files.
- **Full audit mode** runs only when the user explicitly asks for an audit, a pen test, a comprehensive review, or report artifacts. It has six phases: reconnaissance, coverage-led hunting waves, candidate validation, structured `findings.json`, independent record verification, and a target-neutral report. Output goes outside the target, by default under `~/security-audit-skill/<repo>/run-<N>`.

## Safety model

Reading source is always allowed. Target code may run only inside an OS-enforced sandbox with no external network, an allowlisted environment, a read-only target, and hard resource limits. If the sandbox cannot be enforced, the agent does not execute code and records a `needs_validation` blocker. The skill forbids probing deployed endpoints, shared infrastructure, or live identities.

## Bundled files

| File                                                             | Purpose                                                                                                                                                 |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RECONNAISSANCE.md`, `HUNTING.md`, `VALIDATION-AND-REPORTING.md` | Phase instructions and sub-agent prompts                                                                                                                |
| `ATTACK-CLASSES.md` + 10 domain companions                       | Hunting classes for web/auth, client-side, AI/LLM, memory safety, supply chain, cloud, RPC, resource exhaustion, data isolation, and desktop/mobile IPC |
| `report-schema.json`                                             | Schema for `confirmed` / `needs_validation` / `rejected` records                                                                                        |
| `validate-findings.cjs`, `validate-coverage-ledger.cjs`          | Zero-dependency Node validators, plus their `*.test.cjs` suites                                                                                         |

The validators need only Node. To check a synced copy, run `node --test validate-findings.test.cjs validate-coverage-ledger.test.cjs` from the skill directory.

## Canonical SKILL.md

See [`skills/vendor/security-audit/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/security-audit/SKILL.md) for the full instructions.

# shadcn (vendored)

Frozen

Upstream removed this skill in [vercel/vercel-plugin#291](https://github.com/vercel/vercel-plugin/pull/291) (2026-10-02). `vendor.yaml` marks it `frozen:`, so `make sync` keeps the last-synced copy and no longer updates it. `shadcn-ui/ui` now publishes its own [`skills/shadcn`](https://github.com/shadcn-ui/ui/tree/main/skills/shadcn); switching the source is tracked separately.

Vendored from [vercel/vercel-plugin/skills/shadcn](https://github.com/vercel/vercel-plugin/tree/main/skills/shadcn) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/shadcn/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/shadcn/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> shadcn/ui expert guidance — CLI, component installation, composition patterns, custom registries, theming, Tailwind CSS integration, and high-quality interface design. Use when initializing shadcn, adding components, composing product UI, building custom registries, configuring themes, or troubleshooting component issues.

## What it teaches

Covers the full shadcn workflow: `init`, `add`, `build`, `search`, `migrate`, `info`, `view`, custom registries, theming, Tailwind integration. Triggers on `components.json`, `components/ui/**`, and any `npx shadcn@latest <subcmd>`. Includes a `validate` rule warning about Base UI / Radix incompatibility with AI Elements.

## Related fullstack-nextjs skills

- [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md) — App Router context where shadcn components live
- [`web-design-guidelines`](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md) — a11y/perf review for shadcn UIs
- [`frontend-design`](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md) — aesthetic direction beyond default shadcn looks

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/shadcn/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/shadcn/SKILL.md) for the full instructions. Upstream source: [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) (shadcn was acquired by Vercel; this is the same canonical guidance redistributed under the Vercel plugin).

# skill-author

Authoring helper for **new agent skills**. Ships:

- A scaffolder ([`new-skill.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/scripts/new-skill.sh)) that creates `skills/local/<name>/` with the standard layout pre-seeded.
- A linter ([`lint-skill.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/scripts/lint-skill.sh)) that checks frontmatter, script hygiene, and reference reachability. It enforces the repo's portable agent-skill compatibility budget for `name` and `description`.
- Two reference docs that condense the agentskills.io guides: [authoring-patterns.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/references/authoring-patterns.md) and [script-design.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/references/script-design.md).
- A repo-specific conventions reference ([this-repo-conventions.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/references/this-repo-conventions.md)) that explains layout, mirroring, and bash 3.2 compatibility.
- Templates for SKILL.md, reference docs, bash scripts (with `--help` / `--dry-run` / strict-mode boilerplate), and Python scripts (with PEP 723 inline deps).

## Cross-agent compatibility

This repo keeps local skills portable across Codex, Claude Code, Cursor, OpenCode, and `npx skills` installs. The short version:

- `name`: hyphen-case, \<=64 chars.
- `description`: required, \<=1024 chars; 120-500 chars preferred.
- First 60 description chars should be useful in picker UIs.
- Product-specific frontmatter is allowed only when deliberate.

See [Agent skill compatibility](https://daviddwlee84.github.io/agent-skills/reference/agent-skill-compatibility/index.md) for the full matrix of tool preferences, limits, source links, and this repo's tier policy.

## When to use this vs `skill-creator`

| Task                                       | Use                                        |
| ------------------------------------------ | ------------------------------------------ |
| "I want to make a new skill for X"         | **skill-author**                           |
| Scaffold SKILL.md / a reference / a script | **skill-author**                           |
| Lint a draft skill                         | **skill-author**                           |
| Skill isn't triggering when expected       | `skill-creator` (description optimization) |
| Run test cases / benchmark a skill         | `skill-creator` (eval loop)                |

If both apply, start with `skill-author`, then hand off to `skill-creator` once the structure is right.

## Quick start

```
# 1. Scaffold
bash skills/local/skill-author/scripts/new-skill.sh my-skill

# 2. Edit skills/local/my-skill/SKILL.md to fill in the description and workflow

# 3. Lint
bash skills/local/skill-author/scripts/lint-skill.sh skills/local/my-skill

# 4. (Optional) hand off to skill-creator for quantitative validation
```

## Why a separate skill?

`skill-creator` (the Anthropic-published skill bundled at `.agents/skills/`) is the canonical authority for skill creation, but it's heavily focused on the **eval/iterate loop**: spawning subagents, grading, benchmarking, optimizing the description triggering rate. `skill-author` covers the **authoring patterns** that the agentskills.io best-practices and using-scripts pages document — gotchas sections, output templates, validation loops, calibrated specificity, and agentic CLI design — plus repo-specific conventions and working scaffolder/linter scripts.

The two are complementary and explicitly cross-reference each other.

## Canonical SKILL.md

See [skills/local/skill-author/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/skill-author/SKILL.md) for the full triggering description and workflow.

# skill-creator (vendored)

Vendored from [anthropics/skills/skills/skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/skill-creator/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/skill-creator/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

## What it teaches

Anthropic's own methodology for authoring skills, including:

- Evaluation harness for measuring how reliably a skill's `description` actually triggers on the prompts it should.
- Benchmarking with variance analysis (repeat runs to distinguish real gains from noise).
- Optimization loops for iterating on the `description` field until trigger rate meets target.

## `skill-creator` vs local `skill-author`

| Aspect      | `skill-creator` (vendored, this)                               | [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md) (local) |
| ----------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Focus       | **Evaluation** — test cases, trigger-rate benchmarks, variance | **Authoring** — scaffolding, linting, agentskills.io best practices                                |
| Scripts     | Eval harness, benchmarking                                     | `new-skill.sh`, `lint-skill.sh`                                                                    |
| When to use | After authoring, to measure & optimize                         | While writing the SKILL.md + references + scripts                                                  |

The two are complementary — use `skill-author` to build the skill, then `skill-creator` to evaluate and tune its trigger description.

## Canonical SKILL.md

See [skills/vendor/skill-creator/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/skill-creator/SKILL.md) for the full instructions. Upstream source: [anthropics/skills](https://github.com/anthropics/skills).

# slurm-hpc

Portable Slurm know-how for **any** cluster — authoring `sbatch` scripts, choosing resource requests, chaining jobs, and reasoning about what actually isolates a misbehaving job. Deliberately site-agnostic: for one cluster's specific partitions and recipes, that repo's own skill wins.

| Surface                                                                                                                                    | Question it answers                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Batch script skeleton                                                                                                                      | "What does a correct `#SBATCH` header look like?"                             |
| Resource requests                                                                                                                          | "What do `--mem` / `--cpus-per-task` / `--gres` / `--time` actually enforce?" |
| Chaining and waiting                                                                                                                       | "How do I run B after A without babysitting the queue?"                       |
| Isolation section                                                                                                                          | "If my neighbour's job goes wrong, do I go down with it?"                     |
| [`references/gpu-isolation.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/slurm-hpc/references/gpu-isolation.md) | "How do I cap GPU VRAM — shard vs MPS vs MIG?"                                |

## The question the skill is really built around

**Does a misbehaving job fail alone?** For CPU and RAM, yes: with `task/cgroup` the job is pinned to its cores and hard-capped at `--mem`, and exceeding it triggers the kernel OOM killer *inside that job's cgroup only*. Neighbours are untouched.

For GPU memory, **allocating a GPU does not cap its memory** — and the options differ in whether they actually fence anything:

| Method                                              | VRAM isolation             | Fails alone?              |
| --------------------------------------------------- | -------------------------- | ------------------------- |
| `--gres=gpu:N` (whole card)                         | n/a (owns it)              | —                         |
| `--gres=shard:N`                                    | **none** — accounting only | ❌ can OOM the whole card |
| `--gres=mps:N` (plain)                              | none                       | ❌                        |
| `--gres=mps:N` + `CUDA_MPS_PINNED_DEVICE_MEM_LIMIT` | enforced cap               | ✅                        |
| **MIG** (`--gres=gpu:1g.5gb:1`)                     | **hardware slice**         | ✅ strongest              |

Sharing a GPU is not the same as isolating one. Slurm's own docs say sharding "does not fence the processes" — so a wrong batch size takes down the card and its neighbours. [`references/gpu-isolation.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/slurm-hpc/references/gpu-isolation.md) has the `slurm.conf` / `gres.conf` snippets, the TaskProlog wiring for the MPS memory limit, and the MIG prerequisites.

## Chaining and waiting

Added because the skill previously had **no** answer to "how do I run B after A?" — only one-shot `squeue` / `sacct` inspection.

```
JID=$(sbatch --parsable phase_a.sbatch); JID=${JID%%;*}   # strip ";cluster"
sbatch --dependency=afterok:"$JID" \
       --kill-on-invalid-dep=yes \
       --mail-type=INVALID_DEPEND,END,FAIL \
       phase_b.sbatch
```

| Dependency         | Fires when the parent…                   |
| ------------------ | ---------------------------------------- |
| `afterok:<id>`     | succeeded (exit 0)                       |
| `afternotok:<id>`  | failed — the hook for alerting / cleanup |
| `afterany:<id>`    | terminated, either way (**the default**) |
| `after:<id>[+min]` | started                                  |
| `aftercorr:<id>`   | array task N follows parent array task N |
| `singleton`        | previous job of the same name+user ended |

`,` means **all** must be satisfied; `?` means **any**.

To block instead of chain: `sbatch --wait` — *"Do not exit until the submitted job terminates"*, with the job's exit code.

For the agent-side question — *how should* *I* *wait?* — the skill defers to [`long-running-jobs`](https://daviddwlee84.github.io/agent-skills/skills/long-running-jobs/index.md), which ranks scheduler chaining, one blocking backgrounded wait, filtered event streams, and scheduled check-ins.

## The four gotchas that cost the most

- **`afterany` is the default dependency type.** A bare `-d 12345` runs the child after the parent terminates *either way* — including after it crashed. Always spell out `afterok:`.
- **A failed parent leaves the child `PENDING` forever.** Slurm's default is *"the job stays pending with reason DependencyNeverSatisfied"*, which looks identical to waiting for resources; and *"the dependent job will never be run, even if the preceding job is requeued"*. Pass `--kill-on-invalid-dep=yes`. This has its own [pitfall page](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/slurm-dependent-job-pends-forever-after-failed-parent.md).
- **`--parsable` prints `jobid;cluster`**, not a bare id, when a cluster name is configured. Strip with `${JID%%;*}` — otherwise the dependency string is malformed *and* the `;` truncates your shell command.
- **`sbatch --wait` collapses every signal death to exit 1.** An OOM kill, a `TIMEOUT`, a `scancel`, and a plain `exit 1` are indistinguishable. Read `sacct -j <id> --format=State,ExitCode` — states like `OUT_OF_MEMORY` / `TIMEOUT` / `NODE_FAIL` are what tell you whether a retry could work.

Plus: `--mem` is a hard cgroup cap, not a hint; `sacct` needs `slurmdbd` configured (fall back to `scontrol show job`, live only); a failing site `Prolog`/`Epilog` drains the node; `srun --oversubscribe` is ignored under consumable resources.

## When the skill triggers

- Writing or fixing an `sbatch` script or `srun` command line.
- Choosing resource requests (CPUs, memory, GPUs, time, partition).
- Reading job/queue/node state (`squeue`, `sacct`, `sinfo`, `scontrol`).
- Chaining jobs, or asking why a dependent job never started.
- Reasoning about cgroups and what fences GPU VRAM.

## When it doesn't

- Operating a specific project's cluster with its own recipes → that repo's skill.
- Designing cluster provisioning / `slurm.conf` from scratch → admin work.
- "How should the *agent* wait for this job?" → [`long-running-jobs`](https://daviddwlee84.github.io/agent-skills/skills/long-running-jobs/index.md).

## Structure

```
skills/local/slurm-hpc/
├── SKILL.md                        # skeleton, resources, chaining, isolation, gotchas
└── references/
    └── gpu-isolation.md            # shard vs mps vs MIG, config snippets, enforcement details
```

# streamlit-to-marimo (vendored)

Vendored from [marimo-team/skills/skills/streamlit-to-marimo](https://github.com/marimo-team/skills/tree/main/skills/streamlit-to-marimo). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/streamlit-to-marimo/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/streamlit-to-marimo/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Convert a Streamlit app to a marimo notebook.

## What it teaches

Migration patterns from Streamlit's imperative, re-run-the-whole-script model to marimo's reactive DAG. Covers how `st.session_state`, `st.cache_data`, and Streamlit widgets map to marimo equivalents — typically `mo.state`, `@functools.cache` or cell-level reactivity, and `mo.ui.*`.

## Related local skills

- [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) — if the Streamlit app was being used as both an interactive UI and a script, the converted marimo notebook can adopt the dual-mode pattern.

## Canonical SKILL.md

See [skills/vendor/streamlit-to-marimo/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/streamlit-to-marimo/SKILL.md) for the full migration checklist. Upstream source: [marimo-team/skills](https://github.com/marimo-team/skills).

# supabase-postgres-best-practices (vendored)

Vendored from [supabase/agent-skills/skills/supabase-postgres-best-practices](https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/supabase-postgres-best-practices/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/supabase-postgres-best-practices/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

## What it teaches

Performance rules across 8 categories — query performance, indexes, connection management, RLS, pooling — prioritized by impact. Each rule has incorrect-vs-correct SQL examples, query-plan analysis, and target performance metrics. Complementary to the broader [`supabase`](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md) skill which covers the full product surface.

## Related fullstack-nextjs skills

- [`supabase`](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md) — full Supabase product coverage (auth, storage, edge fns, …)
- [`vercel-storage`](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md) — Vercel-side integration patterns

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/supabase-postgres-best-practices/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/supabase-postgres-best-practices/SKILL.md) for the full instructions. Upstream source: [supabase/agent-skills](https://github.com/supabase/agent-skills).

# supabase (vendored)

Vendored from [supabase/agent-skills/skills/supabase](https://github.com/supabase/agent-skills/tree/main/skills/supabase) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/supabase/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/supabase/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector).

## What it teaches

The single canonical Supabase skill. Covers the entire Supabase surface + explicit `@supabase/ssr` Next.js patterns. Includes a security checklist for Supabase-specific traps (e.g. **never use `user_metadata` in JWT-based authorization**, deleting a user does not invalidate tokens, RLS-by-default on exposed schemas).

## Related fullstack-nextjs skills

- [`supabase-postgres-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/supabase-postgres-best-practices/index.md) — performance rules from same upstream
- [`vercel-storage`](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md) — Vercel-side integration patterns (its pathPatterns include `supabase/**`)
- [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md) — App Router context where `@supabase/ssr` is used

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/supabase/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/supabase/SKILL.md) for the full instructions. Upstream source: [supabase/agent-skills](https://github.com/supabase/agent-skills).

# superproject-workspace

Keep a **git-submodule superproject** usable as one agent entry point across many repos, without letting it drift. Use it for an umbrella of parallel repos, or for a workspace hub that mixes core, personal, and reference repos.

A gitlink records a commit, not a branch, so drift is the default: child PRs merge and the pointer silently falls behind, checkouts end up detached or dirty, and pointers reference commits nobody pushed. The skill makes drift **visible** and moves pointers **by policy**.

| Surface                                   | Question it answers                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `scripts/superproject.py status`          | "Which children are behind, drifted, dirty, or pointing at unpushed commits?" |
| `scripts/superproject.py pull` / `bump`   | "How do I move pointers safely, all in one outer commit?"                     |
| `scripts/superproject.py worktree`        | "Where do I put a feature branch for a child?"                                |
| `scripts/superproject.py audit` / `adopt` | "How do I bring an older superproject up to this standard?"                   |
| `assets/superproject-bump.yml`            | "How do pointers keep up without me remembering?"                             |
| `references/decision-guide.md`            | "Monorepo, submodules, manifest of clones, or Project add-dir?"               |

## Policy lives in `.gitmodules`

```
[submodule "app"]
    path = app
    url = git@github.com:me/app.git
    branch = main
    x-policy = track     # track | pin | lazy
    x-bump = pr          # pr | direct | manual   (track only)
    x-tier = core
```

| Policy                   | Pointer moves                                                              | Initialized     |
| ------------------------ | -------------------------------------------------------------------------- | --------------- |
| `track`                  | ff-only `pull`, then `bump`; optionally automated by CI (`pr` or `direct`) | by default      |
| `pin`                    | only `bump --reason`                                                       | by default      |
| `lazy` (`update = none`) | only `bump --reason`                                                       | only when named |

## Core workflow

```
sp status --fetch
sp worktree add app feat/login   # .worktrees/app/feat-login
# ...commit + push + PR inside the child...
sp pull
sp bump --all-track --commit     # preflighted, one outer commit
```

To adopt an existing superproject, run `audit`, then `adopt --dry-run --policy-default pin --set app=track:pr`. After review, run `adopt`. It writes an AGENTS.md block, `sub-*` justfile recipes, the `.worktrees/` ignore entry, local git config, and, optionally, the CI workflow and pre-commit hook.

The CLI is **referenced, not copied**: recipes resolve the installed skill (`~/.agents/skills/superproject-workspace`) and fall back to GitHub raw at `$SUPERPROJECT_CLI_REF`. One `npx skills update` upgrades every superproject. Rerun `adopt` to refresh the managed blocks; `audit` flags them when stale.

(`sp` = `uv run --script ~/.agents/skills/superproject-workspace/scripts/superproject.py`, or the `just sub-*` recipes.)

## See also

- [Source](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/superproject-workspace)
- [`git-workflow`](https://daviddwlee84.github.io/agent-skills/skills/git-workflow/index.md): single-repo commits, branches, and worktrees.
- [`forge-native-dev`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/forge-native-dev): issue and PR lifecycle inside each child.

# userscript-development

Develop userscripts with explicit runtime and testing boundaries. This owned skill is maintained in [Tampermonkey-Scripts](https://github.com/daviddwlee84/Tampermonkey-Scripts); the collection distributes its copy under `skills/owned/userscript-development/`. See [owned workflow](https://daviddwlee84.github.io/agent-skills/workflows/adding-owned-skills/index.md) for updates.

## What it captures

| Experience                                        | Skill guidance                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------------------ |
| A button vanishes after navigation                | Idempotent reconciliation, target replacement, route invalidation              |
| A title keeps acquiring prefixes                  | Observer callbacks are asynchronous; compare desired state before writing      |
| Console succeeds, manager fails                   | Diagnose grants, sandbox, matching, injection permission and timing separately |
| Export includes its own panel or translated text  | Clone and clean, isolate owned UI, retain the source snapshot                  |
| UI screenshots look right but output is wrong     | Inspect clipboard text, downloaded files and partial-export reports            |
| A userscript conflicts with site/native shortcuts | Test real keyboard input, Shadow DOM paths, IME and focus ownership            |
| Chromium/Firefox fixtures pass                    | Report DOM/shim evidence separately from real-manager evidence                 |
| Native reference data agrees                      | Distinguish static-model agreement from loading the actual reference extension |

The main skill is 146 lines with six references, a runnable three-file test example, and an output-ignore file. Detailed sources and corrected assumptions live in its [provenance reference](https://github.com/daviddwlee84/Tampermonkey-Scripts/blob/main/.agents/skills/userscript-development/references/provenance.md).

Installed resources resolve from the loaded skill directory. Project commands, dependencies and test outputs belong to the user's working project; the author's checkout is not required. Source-specific commands remain in that project's CLAUDE.md, while public source links provide optional attribution.

## Browser and extension testing

The skill covers installing browser binaries through the project's locked Playwright, writing local HTML fixtures, injecting explicit GM shims in a known order, exercising UI with Chromium and Firefox, and preserving screenshots and actual output. On 2026-09-09, a real `skills@1.5.25 add --copy` installation in a fresh project whose path contained spaces passed **6/6 tests** across both engines. Playwright 1.62.1 was independently installed in that project, and the copy/run instructions were executed directly from the installed reference. Screenshots were inspected and all 11 installed skill files remained unchanged.

For real-manager tests, it explains bundled Chromium's persistent context, isolated profiles, official extension artifacts, runtime ID discovery, permission controls, and importing `.user.js` through the actual manager UI. Reference tests compare extension alone, userscript alone, and coexistence on the same fixture.

This procedure draws from the source project's [actual VM/TM + Vimium C validation](https://github.com/daviddwlee84/Tampermonkey-Scripts/blob/d7525d2/userscripts/vimium-c-companion/VALIDATION.md) and inspected local experiments. Those historical results were reviewed, not rerun during skill authoring. Firefox DOM tests are supported; the source's real Firefox manager attempt did not establish successful userscript injection.

## Existing skills considered

Discovery used the skills.sh leaderboard, `skills@1.5.25 find userscript`, and `find tampermonkey`, followed by upstream inspection. Counts below are a 2026-09-09 snapshot and do not establish correctness.

| Candidate                                                                                      | Discovery evidence                                                                          | Decision                                                                                                                                         |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [henkisdabro tampermonkey](https://skills.sh/henkisdabro/wookstar-claude-plugins/tampermonkey) | 225 installs; GitHub repository 86 stars; SKILL.md and patterns inspected at `5091ecc`      | `skipped` for vendoring: useful TM API reference, but the local project needs a compact cross-manager lifecycle and fixture/native-test workflow |
| [xixu-me develop-userscripts](https://skills.sh/xixu-me/skills/develop-userscripts)            | 12 installs; directory description includes Tampermonkey/ScriptCat; GitHub API returned 404 | `evaluated` at listing level only; canonical source, stars and installability unverified                                                         |
| [andradeatdev userscript-creator](https://skills.sh/andradeatdev/skills/userscript-creator)    | 1 install; GitHub API returned 404                                                          | `wishlist`; content not evaluated and not recommended for installation yet                                                                       |

The first candidate's inspected source is [here](https://github.com/henkisdabro/wookstar-claude-plugins/blob/5091eccfb7cf09275f20fda850c190dff83be100/plugins/tampermonkey/skills/tampermonkey/SKILL.md). Its manual install command is `npx skills@1.5.25 add henkisdabro/wookstar-claude-plugins --skill tampermonkey`. No external skill was installed or copied into this collection.

The new skill uses original wording and the owner's project evidence. Its added value is specific failure modes and repeatable verification; it is not a generic JavaScript tutorial. A controlled with/without-skill model benchmark has not been run; `skill-creator` can evaluate output quality and triggering separately.

## Installation and maintenance

The canonical path is `.agents/skills/userscript-development/` in the source project. The source is published and the owned entry tracks its upstream commit in `vendor.yaml`. Install directly from the published source:

```
npx skills@1.5.25 add daviddwlee84/Tampermonkey-Scripts --skill userscript-development
```

After the collection's updated mirror is published, its grouped installation is:

```
npx skills@1.5.25 add daviddwlee84/agent-skills/skills --skill userscript-development
```

During local development, install from a local checkout or use the source project's discovery directory. Edit the source project, not the owned mirror.

# vectorbt

Develop, debug, optimize and migrate code using **VectorBT OSS or PRO as a Python library**. This local skill belongs to the `quantitative-finance` marketplace group with [quantatitive-factor-researcher](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md).

The skill verifies the edition and installed API before using examples. For new work it prefers PRO when access is confirmed; existing OSS projects keep their edition unless a feature requirement, measured bottleneck or migration request warrants a change. Users without PRO access can use public OSS documentation and their installed package normally.

## What ships

- A short skill entrypoint and on-demand OSS, PRO, migration and MCP references.
- `vbt_context.py doctor`: inspect the project's interpreter, actual imports, package versions, PRO repository access and available caches.
- `vbt_context.py sync-pro`: download release assets with the existing GitHub CLI login, verify checksums, and generate searchable Markdown with source URLs and a page/object index. It also works without installing VBT when given a release.
- `vbt_mcp.py config`, `serve`, `check`: project-scoped Codex/Claude Code setup, launch the installed official PRO server, and verify real MCP calls.
- Offline tests using synthetic documents and a fake GitHub CLI; no membership or private documentation is needed in CI.

Source: [the local skill](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/vectorbt).

## Quick start

Commands are relative to the installed skill directory. Pass the strategy project's Python explicitly if it is not under `.venv`.

```
python3 scripts/vbt_context.py doctor --project /path/to/strategy
python3 scripts/vbt_context.py sync-pro --python /path/to/strategy/.venv/bin/python
# Or inspect documentation without installing PRO (choose the desired release):
python3 scripts/vbt_context.py sync-pro --release v2026.9.5
```

Use the returned `index` and `markdown_dir` with `rg`, then read complete relevant sections and confirm the installed signature. No embeddings or extra LLM API key is required. Default assets are pages and examples; add `--messages` for Discord discussions or MCP setup. The example release is not a default pin.

## XDG and freshness

macOS and Linux share the same precedence: `--cache-dir`, then an absolute `$XDG_CACHE_HOME/vectorbt-agent`, then `~/.cache/vectorbt-agent`. Empty or relative XDG values fall back to the default. Caches are shared across projects and isolated by edition/release; downloads and credentials never belong in Git.

Sync checks remote metadata after 24 hours or with `--refresh`. Asset ID, timestamp, size and digest detect changes even within the same release tag. Validated generations are selected atomically, leaving active readers on a consistent old generation. No background scheduler is installed.

`--offline` uses valid local data; a failed metadata request with valid cache returns an explicit `stale` status. Neither claims the live website is current. Missing remote digests are reported; invalid checksums or JSON do not replace the last valid cache. Stop old readers before deleting obsolete cache generations.

## Optional MCP

When requested, prepare the target release's MCP/knowledge dependencies, sync all three assets, and use the helper to preview/apply the project server entry. The launcher reuses the same cache and official tools, not a new retrieval engine. Existing conflicting server entries require a focused merge rather than being overwritten; unrelated settings are preserved.

`check` verifies the server protocol, environment, document reading and BM25 search. A native client must then load the entry and successfully call a tool; server validation alone does not establish client connection.

## Validation baseline

Validated on Python 3.12 with OSS 1.1.0 (Plotly 5.24.1) and PRO 2026.9.5 (MCP SDK 2.2.0): fresh-process synthetic backtests, private asset synchronization, official MCP page/BM25 calls, and isolated native marketplace loading in both clients. This is a tested baseline, not a universal dependency pin. The OSS reference records the observed Plotly 7 import incompatibility.

## Sources

- [OSS documentation](https://vectorbt.dev/) and [source](https://github.com/polakowo/vectorbt)
- [PRO AI integration](https://members.vectorbt.pro/using-ai/), [downloads](https://members.vectorbt.pro/downloads/) and [releases](https://github.com/polakowo/vectorbt.pro/releases)
- [XDG specification](https://specifications.freedesktop.org/basedir/latest/)

The official source trees checked during authoring did not ship a skill. The surveyed third-party skills used different workflow assumptions, including OpenAlgo-specific indicator defaults; this skill is independently authored.

# vercel-storage (vendored)

Vendored from [vercel/vercel-plugin/skills/vercel-storage](https://github.com/vercel/vercel-plugin/tree/main/skills/vercel-storage) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/vercel-storage/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/vercel-storage/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.

## What it teaches

Storage selection + integration for Vercel apps. Notably its `pathPatterns` include `supabase/**`, `lib/supabase.*`, `prisma/schema.prisma`, `prisma/**` — so the skill auto-triggers on Supabase and Prisma projects too, not just on Vercel-native storage.

## Related fullstack-nextjs skills

- [`supabase`](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md) — full Supabase coverage when you go beyond integration
- [`supabase-postgres-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/supabase-postgres-best-practices/index.md) — Postgres-side performance rules

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/vercel-storage/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/vercel-storage/SKILL.md) for the full instructions. Upstream source: [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin).

# verifiable-surfaces

Design and verify exercisable surfaces on apps, CLIs, services, and config. This skill operates in two complementary modes:

- **Authoring mode** — when creating a new CLI, tool, library, or service, ensure it exposes `--help`, `--dry-run`, `--print-config`, isolated-state smoke entrypoints, and an explicit exit-code contract.
- **Verification mode** — when editing config, CLI args/env parsing, dotfiles, Ansible, IaC, or generated/rendered config, walk the verification ladder until the highest *harmless* gate has passed.

The invariant: a surface that cannot be exercised cheaply and harmlessly was not actually verified, regardless of how much linting passed.

## When the skill triggers

**Authoring mode:**

- Writing a new Python CLI with uv + tyro / click / argparse, a Node CLI with commander/yargs/oclif, or a Bash script that takes args or has side effects
- Adding a new subcommand, flag, or env var to an existing tool
- Building a service/daemon with a config file or an SDK that loads config

**Verification mode:**

- Editing app/tool config (`next.config.*`, `pyproject.toml`, `mkdocs.yml`, `docker-compose.yml`, `pueue.yml`, DVC/MLflow config, service manifests)
- Changing CLI args, env parsing, config discovery order, or startup-time defaults
- Updating dotfiles or generated config (chezmoi templates, shell init files, Git hooks, editor config, launchd/systemd units, Ansible, Terraform, Kubernetes, CI, deploy manifests)

## Authoring checklist (universal)

1. `--help` lists usage, every flag, examples, and exit codes
1. `--dry-run` exists for any side-effecting operation and **still loads the real config / resolves the real plan**
1. `--print-config` (or `--show-config`) prints the fully-merged effective config when the program loads config
1. `--config <path>` accepted; `$HOME` / `$XDG_CONFIG_HOME` respected
1. Exit-code contract documented in `--help`
1. Stdout is data; stderr is logs and diagnostics
1. Self-verification before declaring done: `--help`, `--dry-run`, `--print-config`, intentionally-bad input → non-zero, isolated-state smoke (`env -i HOME=$(mktemp -d) ...`)

## Verification ladder

1. Syntax/schema gate
1. Rendered/applied config gate (validate output, not template source)
1. App/tool-native loader gate (`config check`, `doctor`, `--print-config`, `plan`, `--dry-run`)
1. Compile/build gate
1. Harmless runtime smoke (temp `$HOME`, `/tmp`, container, `--check`, limited tag/target)

## Examples

The bundled references cover both modes:

- [`references/authoring-checklist.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/verifiable-surfaces/references/authoring-checklist.md) — Python (tyro/click), Node (commander/yargs), Bash templates plus a five-command self-verification snippet
- [`references/config-examples.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/verifiable-surfaces/references/config-examples.md) — chezmoi (`apply --dry-run --verbose`, `diff`, `execute-template`), Ansible (`--syntax-check` is gate 1 only; then `--check`/`--diff`/ `--tags`/`--limit`), JS/TS, Python settings, Docker Compose, Kubernetes, Terraform/OpenTofu

## Canonical SKILL.md

See [skills/local/verifiable-surfaces/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/verifiable-surfaces/SKILL.md) for the full triggering description, dual-mode workflow, gotchas, and reference links.

# web-design-guidelines (vendored)

Vendored from [vercel-labs/agent-skills/skills/web-design-guidelines](https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/web-design-guidelines/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/web-design-guidelines/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

## What it teaches

A reviewer skill — fetches the latest Web Interface Guidelines from `vercel-labs/web-interface-guidelines` and audits files against the rule set, returning findings in `file:line` format. Covers a11y, perf, and UX. Pairs naturally with [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md) and [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md).

## Related fullstack-nextjs skills

- [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md) — UI components that this skill audits
- [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md) — overlapping component-level review
- [`frontend-design`](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md) — aesthetic direction (this skill is the auditor; that one is the creator)

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/web-design-guidelines/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/web-design-guidelines/SKILL.md) for the full instructions. Upstream source: [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills).

# webapp-testing (vendored)

Vendored from [anthropics/skills/skills/webapp-testing](https://github.com/anthropics/skills/tree/main/skills/webapp-testing) (part of the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) series). Synced via [`make sync`](https://github.com/daviddwlee84/agent-skills/blob/main/Makefile); do not edit [`skills/vendor/fullstack-nextjs/webapp-testing/SKILL.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/webapp-testing/SKILL.md) locally — changes will be clobbered on the next sync.

## Upstream frontmatter description

> Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

## What it teaches

Native Python Playwright workflow with a `scripts/with_server.py` helper that manages server lifecycle (multiple servers supported). Decision tree: static HTML → read selectors directly; dynamic webapp → use the helper + write a simplified Playwright script. Black-box scripts run with `--help` first to keep them out of the context window.

## Related fullstack-nextjs skills

- [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md) — the dev server that webapp-testing drives
- [`frontend-design`](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md) — close the loop: build → screenshot → critique

## Canonical SKILL.md

See [skills/vendor/fullstack-nextjs/webapp-testing/SKILL.md](https://github.com/daviddwlee84/agent-skills/blob/main/skills/vendor/fullstack-nextjs/webapp-testing/SKILL.md) for the full instructions. Upstream source: [anthropics/skills](https://github.com/anthropics/skills).

# zensical-site-bootstrap

An English-only Zensical documentation pilot with safe initialization, locked uv documentation dependencies, native LLM exports, and build-only CI.

[Canonical skill and helpers](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/zensical-site-bootstrap)

## What it provides

- Explicit-target dry runs and refusal to overwrite existing site configurations.
- Optional preservation of a reviewed `docs/` tree, without reorganizing content.
- Zensical 0.0.73 in a docs dependency group, not application runtime dependencies.
- Native `llms.txt`, `llms-full.txt`, Markdown exports, and Copy as Markdown.
- Mermaid fences and preview commands with configurable host/port.
- A project-owned checker for content coverage, copy targets, and Pages subpaths.
- Optional GitHub Actions build checks with no deployment permissions.

The first dogfood project is [ferry](https://github.com/daviddwlee84/ferry). Generated files belong to the consuming project and do not depend on a checkout of this skills repository.

## Scope limits

This is not a MkDocs migration tool or a multilingual fallback solution. For English plus selected Traditional Chinese with missing-translation fallback, continue using [mkdocs-site-bootstrap](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md) until the Zensical content-i18n contract has been verified. A language dropdown alone does not implement it. Publishing to GitHub Pages requires separate approval.

## Installation

After the skill is available in the published catalog:

```
npx skills@latest add daviddwlee84/agent-skills/skills --skill zensical-site-bootstrap
```

Installing or updating the skill does not overwrite the consuming project's docs, config, checker, or workflow. Review those changes explicitly when adopting new template or builder versions.
# Catalog

# Catalog

A curated index of **external skills, MCP servers, and domain hubs** — distinct from [Skills](https://daviddwlee84.github.io/agent-skills/skills/index.md) (what we ship) and [Reference](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md) (how *our* tooling works).

The catalog exists because:

- Some skills are worth knowing about but not vendoring (license, scope, niche, plugin-only) — we still want them findable from the docs.
- MCP servers don't fit cleanly into the skill model — they need a separate record area.
- A domain practitioner (finance, ML, quant, …) wants one entry point that lists relevant local + vendored + external skills + MCPs + backlog items together.

## What's in here

| Subarea                                                                                           | Purpose                                                                                                                                       | Start here                                                                                                                                    |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [Domains](https://daviddwlee84.github.io/agent-skills/catalog/domains/index.md)                   | One hub page per professional domain — pulls together skills + MCPs + backlog from the domain's perspective.                                  | [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) is the most-populated example.                        |
| [External skills](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/index.md) | Single curated index of upstream skill collections + adjacent reading. Replaces the historical `Collections.md` + README "Resources" section. | The full table at the top of the page.                                                                                                        |
| [Curiosity shelf](https://daviddwlee84.github.io/agent-skills/catalog/curiosities/index.md)       | Docs-only collection of amusing, provocative, or highly personal skills that should not enter routine discovery or workflows.                 | Persona and meta-skill experiments.                                                                                                           |
| [MCP wiki](https://daviddwlee84.github.io/agent-skills/catalog/mcp/index.md)                      | Personal-knowledge area for MCP servers — one page per MCP with frontmatter for future automation.                                            | [Financial Datasets MCP](https://daviddwlee84.github.io/agent-skills/catalog/mcp/financialdatasets-ai/index.md) is the first populated entry. |

## How catalog status works

Every external entry carries a `status:` value (`vendored / deferred / skipped / evaluated / wishlist`) that doubles as a vendoring decision log. The full enum lives in [`docs/_snippets/external-install.md`](https://github.com/daviddwlee84/agent-skills/blob/main/docs/_snippets/external-install.md) and is included at the top of every catalog page that lists external entries.

Workflow for status changes — see [Adding catalog entries](https://daviddwlee84.github.io/agent-skills/workflows/adding-catalog-entries/index.md).

## See also (Reference landscapes)

The [Reference](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md) section already contains landscape pages for tooling we *consume* but don't ship:

- [Browser automation skills & MCPs](https://daviddwlee84.github.io/agent-skills/reference/browser-automation-skills/index.md) — Playwright vs agent-browser vs browser-use vs stagehand vs Playwright MCP comparison.
- [Deep Research landscape](https://daviddwlee84.github.io/agent-skills/reference/deep-research-landscape/index.md) — survey of deep-research tools and personas.
- [SDD frameworks & agent harnesses](https://daviddwlee84.github.io/agent-skills/reference/sdd-and-harnesses/index.md) — spec-kit / GSD / GSD-2 / OpenClaw / Pi SDK comparison. Cross-listed in the [Agent Harness](https://daviddwlee84.github.io/agent-skills/catalog/domains/agent-harness/index.md) hub.
- [Warp Oz skills](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md) — Warp Oz skills vendoring rationale.
- [Karpathy's LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — the pattern the [MCP wiki](https://daviddwlee84.github.io/agent-skills/catalog/mcp/index.md) is modeled after.

These pages stay in `Reference` (not `Catalog`) because they document *conventions* we follow, not *external entries* we track. Catalog cross-links them where relevant.

# Skill curiosity shelf

Interesting, playful, provocative, or highly personal agent skills that are worth remembering but are intentionally kept outside this repo's daily workflow.

Entries on this page are **docs-only**. They are not copied into `skills/vendor/`, listed in `vendor.yaml`, or exposed through the marketplace, so they do not participate in skill discovery unless someone explicitly visits and installs an upstream project.

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

## Meta-skills and persona experiments

| Skill                                                                             | Premise                                                                                                                 | Why it is interesting                                                                                                     | Why it stays docs-only                                                                                                                          | Status    |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| [`anti-distill`](https://github.com/leilei926524-tech/anti-distill)               | Rewrites a skill so it appears complete while withholding its most valuable tacit knowledge.                            | A sharp, satirical inversion of knowledge-distillation and corporate knowledge-transfer workflows.                        | Deliberately adversarial to ordinary documentation and knowledge-sharing goals; interesting as commentary, unsuitable for the default workflow. | `skipped` |
| [`distilly`](https://github.com/titanwings/distilly) (formerly `colleague-skill`) | Distills source material about a colleague, relationship, or public figure into a reusable person profile for an agent. | An unusually elaborate example of persona extraction, evidence collection, and continuously updated character simulation. | Highly personal, privacy-sensitive, and outside the repo's general engineering workflow.                                                        | `skipped` |
| [`create-ex`](https://github.com/therealXiaomanChu/ex-skill)                      | Builds an evolving simulated persona of an ex-partner from memories, chat history, photos, and social posts.            | A memorable experiment at the boundary between agent skills, digital memory, and emotional simulation.                    | Sensitive relationship data and a narrow personal-use scenario make it inappropriate for automatic discovery here.                              | `skipped` |

## Adding another curiosity

Add a row when a skill is worth revisiting for its idea, cultural signal, or unusual interaction design, but should not become part of normal agent behavior. Keep the note descriptive rather than endorsing the behavior.

Use `skipped` with a concise reason. If an entry later becomes genuinely useful for routine work, move it to [External skills](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/index.md) and follow the normal [catalog status workflow](https://daviddwlee84.github.io/agent-skills/workflows/adding-catalog-entries/index.md).

# External skill collections

Curated index of upstream skill collections, marketplaces, and adjacent projects we track. Most are *not* vendored into this repo — listing them here gives the manual-install path and a recorded vendoring decision.

This page replaces the historical [`Collections.md`](https://github.com/daviddwlee84/agent-skills/blob/main/Collections.md) at repo root (kept as a stub for backlink stability) and absorbs the "Resources" section that used to live in [`README.md`](https://github.com/daviddwlee84/agent-skills/blob/main/README.md).

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

## Skills managers

The CLIs / runtimes that install and discover agent skills. The install snippet at the top of this site uses the first one.

| Tool                       | Upstream                                                                                            | Status             | Notes                                                                                                                                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `npx skills`               | [`vercel-labs/skills`](https://github.com/vercel-labs/skills)                                       | `vendored`-as-tool | The CLI this repo standardizes on. See [npx skills metadata model](https://daviddwlee84.github.io/agent-skills/reference/npx-skills-metadata/index.md) for how `marketplace.json` drives the grouped picker. |
| The Agent Skills Directory | [`skills.sh`](https://skills.sh/)                                                                   | `evaluated`        | Hosted directory of `npx skills`-compatible skills. Useful for discovery.                                                                                                                                    |
| Skill.Fish                 | [`knoxgraeme/skillfish`](https://github.com/knoxgraeme/skillfish) ([site](https://www.skill.fish/)) | `evaluated`        | Alternative skill manager. Not used here; tracked for awareness.                                                                                                                                             |

## General-purpose collections

Multi-skill repos covering broad engineering / authoring topics. Several are partially vendored (specific skills cherry-picked into [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml)).

| Collection                         | Upstream                                                                                    | Status               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic's first-party skills     | [`anthropics/skills`](https://github.com/anthropics/skills)                                 | `vendored` (partial) | We vendor `skill-creator`, `frontend-design`, `webapp-testing`, `mcp-builder`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Vercel Labs agent skills           | [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)                   | `vendored` (partial) | We vendor `web-design-guidelines` into `fullstack-nextjs` series.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Vercel plugin skills               | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)                           | `vendored` (partial) | We vendor `nextjs`, `shadcn`, `react-best-practices`, `vercel-storage` into `fullstack-nextjs` series.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Supabase agent skills              | [`supabase/agent-skills`](https://github.com/supabase/agent-skills)                         | `vendored` (partial) | We vendor `supabase` and `supabase-postgres-best-practices` into `fullstack-nextjs` series.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| marimo team skills                 | [`marimo-team/skills`](https://github.com/marimo-team/skills)                               | `vendored` (partial) | We vendor `marimo-notebook`, `streamlit-to-marimo`, `anywidget`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Streamlit agent skills             | [`streamlit/agent-skills`](https://github.com/streamlit/agent-skills)                       | `wishlist`           | Not yet evaluated; mirrors the marimo-team pattern.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Matt Pocock's skills               | [`mattpocock/skills`](https://github.com/mattpocock/skills)                                 | `vendored` (partial) | We vendor the 15-skill end-to-end flow (grill → spec → tickets → implement → review) into the `engineering-fundamentals` series — see [`reference/mattpocock-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/mattpocock-skills/index.md) for the flow, the full list, and what we skip.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| GarryTan / OpenClaw skills         | [`garrytan/gstack`](https://github.com/garrytan/gstack)                                     | `vendored` (partial) | We vendor 4 skills into `product-planning` series.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| poteto's pstack                    | [`cursor/plugins/pstack`](https://github.com/cursor/plugins/tree/main/pstack)               | `evaluated`          | Lauren Tan's 56-skill Cursor plugin (`poteto-mode` router with 23 playbooks, 24 `principle-*` skills, 2 agents). Not vendored: skills read siblings and `../../docs/harness/` (which our per-skill sync doesn't copy), and upstream ships several commits a day. Claude Code has an official generated [harness tree](https://github.com/cursor/plugins/tree/main/harness/pstack/claude-code); install with `/plugin marketplace add cursor/plugins` then `/plugin install pstack@cursor-plugins`. No official Codex/OpenCode build. Use a community port: [`Go7hic/ystack`](https://github.com/Go7hic/ystack), [`TheOnlyFusionCube/potetos-for-everyone`](https://github.com/TheOnlyFusionCube/potetos-for-everyone), or [`kashyab12/uni-pstack`](https://github.com/kashyab12/uni-pstack). If we revisit, `unslop`, `benchmark-checklist`, and `blast-radius` are the only standalone skills. |
| Warp Oz skills                     | [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills)                           | `vendored` (partial) | 6 of 15 vendored — see [`reference/warp-oz-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md) for what was skipped and why.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 199-biotechnologies deep-research  | [`199-biotechnologies/deep-research`](https://github.com/199-biotechnologies/deep-research) | `vendored`           | Single-skill series. See [`reference/deep-research-landscape.md`](https://daviddwlee84.github.io/agent-skills/reference/deep-research-landscape/index.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Cloudflare security-audit          | [`cloudflare/security-audit-skill`](https://github.com/cloudflare/security-audit-skill)     | `vendored`           | Single-skill repo; flat `security-audit` in its own `security` picker group. See [`skills/security-audit.md`](https://daviddwlee84.github.io/agent-skills/skills/security-audit/index.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| thesysdev OpenUI skill             | [`thesysdev/skills`](https://github.com/thesysdev/skills)                                   | `vendored`           | Single-skill repo; flat `openui` in the `generative-ui` picker group. Gateway-first by default. See [`skills/openui.md`](https://daviddwlee84.github.io/agent-skills/skills/openui/index.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| The Minimalist Entrepreneur skills | [`slavingia/skills`](https://github.com/slavingia/skills)                                   | `evaluated`          | Skills based on Sahil Lavingia's [The Minimalist Entrepreneur](https://www.amazon.com/Minimalist-Entrepreneur-Great-Founders-More/dp/0593192397). Persona-style; useful as a model for opinionated single-author skill packs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `last30days` topic synthesizer     | [`mvanhorn/last30days-skill`](https://github.com/mvanhorn/last30days-skill)                 | `evaluated`          | Researches a topic across Reddit, X, YouTube, HN, Polymarket, web → grounded summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Domain-specific collections

Domain-focused skill packs and plugin marketplaces — see the corresponding [domain hub](https://daviddwlee84.github.io/agent-skills/catalog/domains/index.md) for cross-references.

| Collection                    | Upstream                                                                                            | Status     | Domain                                                                                                | Notes                                                                                                                            |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Claude for Financial Services | [`anthropics/financial-services`](https://github.com/anthropics/financial-services)                 | `wishlist` | [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md)               | Massive marketplace: 11 named agents, 7 vertical plugins, partner plugins (LSEG, S&P Global). 21.5k ⭐.                          |
| Awesome Finance Skills        | [`RKiding/Awesome-finance-skills`](https://github.com/RKiding/Awesome-finance-skills)               | `wishlist` | [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md)               | 8 plug-and-play finance skills (news, stock data, sentiment, forecasting, signal tracking, viz, reporting, web search).          |
| AI Research Skills library    | [`Orchestra-Research/AI-research-SKILLs`](https://github.com/Orchestra-Research/AI-research-SKILLs) | `wishlist` | [AI/ML Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/ai-ml-research/index.md) | 98 skills across 23 categories — full research lifecycle. Has its own npm wrapper: `npx @orchestra-research/ai-research-skills`. |
| Knowledge Work Plugins        | [`anthropics/knowledge-work-plugins`](https://github.com/anthropics/knowledge-work-plugins)         | `wishlist` | [Knowledge Work](https://daviddwlee84.github.io/agent-skills/catalog/domains/knowledge-work/index.md) | 11 job-function plugins (sales, legal, finance, data, bio-research, etc.). 12.1k ⭐.                                             |

## Articles & adjacent reading

| Title                                                                                                                             | Source                | Notes                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Building Agent Skills with skill-creator](https://medium.com/google-cloud/building-agent-skills-with-skill-creator-855f18e785cf) | Google Cloud / Medium | Walkthrough of the [`skill-creator`](https://daviddwlee84.github.io/agent-skills/skills/skill-creator/index.md) workflow (vendored).      |
| [Introducing: React Best Practices](https://vercel.com/blog/introducing-react-best-practices)                                     | Vercel blog           | Pairs with the vendored [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md) skill. |
| [Six skills for financial service professionals](https://claude.com/resources/tutorials/claude-for-financial-services-skills)     | Claude resources      | Cross-listed in [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md).                                  |

## Skill candidates (under evaluation)

Reference projects that *could* become a vendored skill or inform a local one — not formally evaluated yet.

| Candidate                       | Upstream                                                                                                                                       | Status      | Notes                                                                                                                                                                                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Wookstar Tampermonkey plugin    | [henkisdabro/wookstar-claude-plugins](https://github.com/henkisdabro/wookstar-claude-plugins/tree/main/plugins/tampermonkey)                   | `skipped`   | Prefer the owned [userscript-development](https://daviddwlee84.github.io/agent-skills/skills/userscript-development/index.md) workflow for cross-manager lifecycle, fixtures and actual extension comparison; reviewed API reference remains an alternative. |
| xixu-me userscript skill        | [skills.sh listing](https://skills.sh/xixu-me/skills/develop-userscripts)                                                                      | `evaluated` | Listing reviewed; canonical repo API returned 404 on 2026-09-09. Installation unverified.                                                                                                                                                                    |
| andradeatdev userscript creator | [skills.sh listing](https://skills.sh/andradeatdev/skills/userscript-creator)                                                                  | `wishlist`  | Content not reviewed; canonical repo API returned 404 on 2026-09-09.                                                                                                                                                                                         |
| 12-factor agents                | [`humanlayer/12-factor-agents`](https://github.com/humanlayer/12-factor-agents)                                                                | `skipped`   | Canonical methodology, not an installable skill. Not vendored; it is the attributed CC BY-SA source for the local [`12-factor-agent-design-review`](https://daviddwlee84.github.io/agent-skills/skills/12-factor-agent-design-review/index.md) skill.        |
| `agent-architecture-analysis`   | [`existential-birds/beagle`](https://github.com/existential-birds/beagle/tree/main/plugins/beagle-analysis/skills/agent-architecture-analysis) | `skipped`   | Useful evidence gates, but its rubric hard-codes Python/Pydantic/Jinja/REST implementation choices. The framework-neutral evidence pattern is cited as an extension in the local skill.                                                                      |
| 12-factor agent skill pack      | [`tika/12-factor-agent-skills`](https://github.com/tika/12-factor-agent-skills)                                                                | `skipped`   | Useful design/review/debug decomposition, but single-skill installs risk missing cross-skill references and the heuristic scanner can report its own source as evidence. Cited as an extension, not vendored.                                                |
| The Twelve-Factor App           | [12factor.net](https://12factor.net/)                                                                                                          | `evaluated` | Original 12-factor manifesto. Inspiration source, not a skill.                                                                                                                                                                                               |
| `agent-skill-creator`           | [`FrancyJGLisboa/agent-skill-creator`](https://github.com/FrancyJGLisboa/agent-skill-creator)                                                  | `wishlist`  | Alternative authoring tool; compare with our [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md) + vendored `skill-creator`.                                                                                          |
| `find-skills`                   | [`vercel-labs/skills/find-skills`](https://skills.sh/vercel-labs/skills/find-skills)                                                           | `evaluated` | Discovery skill from `vercel-labs/skills`. Useful pattern.                                                                                                                                                                                                   |

## Go CLI/TUI candidates

Reviewed **2026-09-20** using the skills.sh directory, `npx skills@1.7.0 find`, upstream skill contents, and GitHub repository metadata. Counts below are a dated discovery snapshot, not evidence that a skill produces correct code. We chose the standalone owned [go-cli-tui](https://daviddwlee84.github.io/agent-skills/skills/go-cli-tui/index.md) integration; its canonical source now lives in [awesome-lazy-tools](https://github.com/daviddwlee84/awesome-lazy-tools/tree/main/skills/go-cli-tui). These candidates are optional alternatives, not installed dependencies.

| Candidate                                                                                                                          | Status    | Snapshot and decision                                                                                                                                                                               | Manual install                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [samber/golang-cli](https://github.com/samber/cc-skills-golang/tree/19a0626ae8565d27a7b7bdf59d8d99d94d7e284c/skills/golang-cli)    | `skipped` | ~38K installs; repo 3,284 stars; MIT. Useful CLI foundation, but lacks the combined dashboard/wizard UX; first-party integration also checks terminal detection and Cobra hook ordering explicitly. | `npx skills@1.7.0 add samber/cc-skills-golang --skill golang-cli` |
| [hyperb1iss/tui-design](https://github.com/hyperb1iss/hyperskills/tree/5c2f96185a7ea1f9a3e9e397b1687f674c4c8c36/skills/tui-design) | `skipped` | ~1.2K installs; repo 33 stars; MIT. Closest UX overlap, but framework-neutral; choose first-party Go/wizard integration instead of a required second skill.                                         | `npx skills@1.7.0 add hyperb1iss/hyperskills --skill tui-design`  |
| [ggprompts/bubbletea](https://github.com/ggprompts/tfe/tree/b71818c5c92d8b45980eda352969817e6284cd91/.claude/skills/bubbletea)     | `skipped` | 464 installs; repo 21 stars; MIT. Layout ideas are useful, but older APIs and byte-slicing truncation do not meet the chosen version/Unicode contract.                                              | `npx skills@1.7.0 add ggprompts/tfe --skill bubbletea`            |

[Charm](https://charm.land/) and its [official repositories](https://github.com/charmbracelet) are `evaluated` library/tool sources, not installable agent skills. The owned skill includes a need-to-tool map and version checks; it does not vendor these libraries.

## Vendoring policy

We vendor a skill when:

1. The upstream has stable canonical authority (Vercel for Next.js, Supabase for Supabase, etc.).
1. The skill fills a gap not already covered by another vendored or local skill.
1. The license is compatible with the [agentskills.io specification](https://agentskills.io/specification).

We **do not** vendor when:

- The upstream is itself a marketplace / collection (we cherry-pick instead).
- Plugin-format collections (e.g., `anthropics/knowledge-work-plugins`) require `claude plugin install` rather than `npx skills add` — we record them here for manual install.
- The skill duplicates an already-vendored one from a more authoritative source.
- The skill is too narrow for general use (host-specific, BigQuery-specific, etc.).

For the full workflow — including how to move an entry from `wishlist` → `deferred` → `vendored` — see [Adding catalog entries](https://daviddwlee84.github.io/agent-skills/workflows/adding-catalog-entries/index.md).

# Domains

Per-domain hub pages. Each hub is a single-page entry point that pulls together the local skills, vendored skills, external (manual-install) skills, MCP servers, and backlog items relevant to a professional domain.

## Hubs

| Hub                                                                                                   | Coverage                                                                                   | Status          |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------- |
| [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md)               | Banking, capital markets, equity research, wealth management, fund admin.                  | Populated       |
| [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) | Quant trading, factor research, backtesting, live execution.                               | Populated       |
| [AI/ML Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/ai-ml-research/index.md) | Experiment tracking, model lifecycle, fine-tuning, agent frameworks.                       | Populated       |
| [Web & Fullstack](https://daviddwlee84.github.io/agent-skills/catalog/domains/web-fullstack/index.md) | Next.js / React / Tailwind / Supabase / Vercel / browser automation / web quality audits.  | Populated       |
| [Knowledge Work](https://daviddwlee84.github.io/agent-skills/catalog/domains/knowledge-work/index.md) | Sales / legal / customer support / product / marketing / data / etc.                       | Mostly template |
| [Agent Harness](https://daviddwlee84.github.io/agent-skills/catalog/domains/agent-harness/index.md)   | SDD frameworks + agent harnesses (the layer above skills), plus reusable control adapters. | Populated       |

"Mostly template" / "Template only" hubs are honest about being mostly empty — they exist so the structure is in place when content arrives.

## How to add a new domain hub

1. Copy [`docs/_snippets/domain-hub-template.md`](https://github.com/daviddwlee84/agent-skills/blob/main/docs/_snippets/domain-hub-template.md) to `docs/catalog/domains/<slug>.md`.
1. Fill in the elevator pitch + the 4 tables (Local / Vendored / External / MCP) — leave `_none yet_` for empty rows.
1. Add the new page to `mkdocs.yml` nav under `Catalog → Domains`.
1. Translate to `docs/catalog/domains/<slug>.zh-TW.md` (every catalog page is bilingual).
1. Cross-link from related hubs (`See also` section) and from any relevant reference landscape pages.
1. Run `make docs-build` (strict mode catches missing translations and broken links).

For the workflow on adding individual entries to an existing hub (skills, MCPs, status changes), see [Adding catalog entries](https://daviddwlee84.github.io/agent-skills/workflows/adding-catalog-entries/index.md).

# Agent Harness

Spec-driven development (SDD) frameworks and agent harnesses — the layer **above** agent skills that owns the requirements → spec → plan → tasks → execute → verify loop, manages context windows, or runs sub-agents.

This repo focuses on **skills** and intentionally does not ship a SDD framework or harness. It does ship a local skill for designing/reviewing the LLM application layer, plus Herdr's official control adapter: neither turns this collection into a harness runtime.

## Skills in this repo

### Local

| Skill                                                                                                                        | One-line                                                                                             | Notes                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`12-factor-agent-design-review`](https://daviddwlee84.github.io/agent-skills/skills/12-factor-agent-design-review/index.md) | Design or evidence-review production LLM applications using HumanLayer's 12-Factor Agents principles | Reviews the workflow/application layer below a harness: prompts, context, typed decisions, state, control flow, pause/resume, humans, retries, and replay. It does not provide a runtime. |

### Vendored

| Skill                                                                        | Upstream                                                                       | Series |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------ |
| [`herdr`](https://daviddwlee84.github.io/agent-skills/skills/herdr/index.md) | [`herdrdev/herdr`](https://github.com/herdrdev/herdr/tree/master/skills/herdr) | flat   |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

| Skill / Plugin                | Upstream                                                                                                                                       | Status      | Why this status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Install hint                                                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `spec-kit` (skills mode)      | [`github/spec-kit`](https://github.com/github/spec-kit)                                                                                        | `evaluated` | The de facto SDD framework (95.5k ⭐). 30+ supported agents. Has a `--skills` install mode that ships its slash commands as agent skills. Documented in [`reference/sdd-and-harnesses.md`](https://daviddwlee84.github.io/agent-skills/reference/sdd-and-harnesses/index.md). Not vendored — would compete with the per-skill philosophy of this repo.                                                                                                                                                                    | `uvx --from git+https://github.com/github/spec-kit specify init <project> --integration claude-code --integration-options="--skills"` |
| `get-shit-done` (gsd)         | [`gsd-build/get-shit-done`](https://github.com/gsd-build/get-shit-done)                                                                        | `evaluated` | Earlier, lighter SDD (61.4k ⭐). 6-command loop (`gsd-new-project → gsd-discuss-phase → gsd-plan-phase → gsd-execute-phase → gsd-verify-work → gsd-ship`).                                                                                                                                                                                                                                                                                                                                                                | (see upstream README)                                                                                                                 |
| `gsd-2`                       | [`gsd-build/gsd-2`](https://github.com/gsd-build/gsd-2)                                                                                        | `evaluated` | Standalone harness (not just a SDD framework).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | (see upstream README)                                                                                                                 |
| OpenClaw                      | [`openclaw/openclaw`](https://github.com/openclaw/openclaw)                                                                                    | `evaluated` | Standalone CLI/runtime that controls the agent session. Also produces `gstack-openclaw-*` skills (already vendored under `product-planning` series).                                                                                                                                                                                                                                                                                                                                                                      | (see upstream README)                                                                                                                 |
| Pi SDK                        | [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono)                                                                                      | `evaluated` | Agent harness alternative.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | (see upstream README)                                                                                                                 |
| `agent-architecture-analysis` | [`existential-birds/beagle`](https://github.com/existential-birds/beagle/tree/main/plugins/beagle-analysis/skills/agent-architecture-analysis) | `skipped`   | Evidence-first 12-Factor review is useful, but the rubric is Python- and implementation-specific; the local skill cites only the portable evidence-gate idea.                                                                                                                                                                                                                                                                                                                                                             | `npx skills add existential-birds/beagle --skill agent-architecture-analysis`                                                         |
| 12-factor agent skill pack    | [`tika/12-factor-agent-skills`](https://github.com/tika/12-factor-agent-skills)                                                                | `skipped`   | Broad five-skill pack, but cross-skill references and scanner self-matches make it unsuitable for vendoring as-is.                                                                                                                                                                                                                                                                                                                                                                                                        | `npx skills add tika/12-factor-agent-skills`                                                                                          |
| pstack (`poteto-mode`)        | [`cursor/plugins/pstack`](https://github.com/cursor/plugins/tree/main/pstack)                                                                  | `evaluated` | Opinionated Cursor workflow pack with a router, playbooks, principle skills, and subagent fan-out. Too coupled and fast-moving to vendor. Claude Code is supported upstream through a generated adapter. For Codex and others, use community ports ([`Go7hic/ystack`](https://github.com/Go7hic/ystack), [`TheOnlyFusionCube/potetos-for-everyone`](https://github.com/TheOnlyFusionCube/potetos-for-everyone)). See [skill collections](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/index.md). | `/plugin marketplace add cursor/plugins` then `/plugin install pstack@cursor-plugins`                                                 |

## MCP servers

| Name                                                                              | Upstream | Status | Auth | Records |
| --------------------------------------------------------------------------------- | -------- | ------ | ---- | ------- |
| *not applicable* — harnesses use whatever MCPs the underlying agent has access to |          |        |      |         |

## Backlog (TODO `P?` items)

- Harness runtimes remain out of scope; only their reusable skill adapters are eligible for vendoring.

## See also

- [`docs/reference/sdd-and-harnesses.md`](https://daviddwlee84.github.io/agent-skills/reference/sdd-and-harnesses/index.md) — full survey of SDD frameworks and agent harnesses, with the layering explanation (skill vs SDD framework vs harness).
- `product-planning` series in [`docs/skills/index.md`](https://daviddwlee84.github.io/agent-skills/skills/index.md) — vendored OpenClaw skills (`gstack-openclaw-*`) that *are* in this repo's scope.
- [`herdr`](https://daviddwlee84.github.io/agent-skills/skills/herdr/index.md) — official control skill, including why binary-emitted installs are preferred for exact version alignment.
- [`12-factor-agent-design-review`](https://daviddwlee84.github.io/agent-skills/skills/12-factor-agent-design-review/index.md) — when to design/review the LLM application layer rather than adopt a harness.

# AI/ML Research

Experiment tracking, model lifecycle, data versioning, notebooks, fine-tuning, agent frameworks, and the broader research-engineering tooling stack.

## Skills in this repo

### Local

| Skill                                                                                                    | One-line                                                                                                         | Notes |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----- |
| [`mlflow-tracking`](https://daviddwlee84.github.io/agent-skills/skills/mlflow-tracking/index.md)         | Generic MLflow — sqlite + `mlflow ui` solo, PostgreSQL + MinIO docker for teams; LLM tracing, registry, autolog. |       |
| [`dvc-ml-workflow`](https://daviddwlee84.github.io/agent-skills/skills/dvc-ml-workflow/index.md)         | DVC pipelines + queued experiments with metrics auto-bound to ephemeral commits.                                 |       |
| [`marimo-batch-mlflow`](https://daviddwlee84.github.io/agent-skills/skills/marimo-batch-mlflow/index.md) | marimo dual-mode (UI + batch CLI) notebooks with Tyro + MLflow.                                                  |       |

### Vendored

| Skill                                                                                                    | Upstream                                                                                           | Series                 |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------- |
| [`marimo-notebook`](https://daviddwlee84.github.io/agent-skills/skills/marimo-notebook/index.md)         | [`marimo-team/skills`](https://github.com/marimo-team/skills/tree/main/skills/marimo-notebook)     | flat                   |
| [`streamlit-to-marimo`](https://daviddwlee84.github.io/agent-skills/skills/streamlit-to-marimo/index.md) | [`marimo-team/skills`](https://github.com/marimo-team/skills/tree/main/skills/streamlit-to-marimo) | flat                   |
| [`anywidget`](https://daviddwlee84.github.io/agent-skills/skills/anywidget/index.md)                     | [`marimo-team/skills`](https://github.com/marimo-team/skills/tree/main/skills/anywidget)           | flat                   |
| [`deep-research`](https://github.com/199-biotechnologies/deep-research)                                  | `199-biotechnologies/deep-research`                                                                | `deep-research` series |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

| Skill / Plugin                      | Upstream                                                                                                                        | Status     | Why this status                                                                                                                                                                                                                          | Install hint                                                                                                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI-research-SKILLs` (full library) | [`Orchestra-Research/AI-research-SKILLs`](https://github.com/Orchestra-Research/AI-research-SKILLs)                             | `wishlist` | 98 skills across 23 categories — full lifecycle from architecture (LitGPT, Mamba, NanoGPT) through fine-tuning (Axolotl, LLaMA-Factory, PEFT) to inference (vLLM, TensorRT-LLM). Too broad to vendor wholesale; will likely cherry-pick. | `npx @orchestra-research/ai-research-skills` (their npm wrapper) or browse and `npx skills@latest add Orchestra-Research/AI-research-SKILLs/<category>/<skill>`. |
| `bio-research` plugin               | [`anthropics/knowledge-work-plugins/bio-research`](https://github.com/anthropics/knowledge-work-plugins/tree/main/bio-research) | `wishlist` | PubMed, BioRender, bioRxiv, ChEMBL, Benchling, Open Targets connectors. Not directly applicable but useful as a reference for life-sciences research workflows.                                                                          | `claude plugin install bio-research@knowledge-work-plugins`                                                                                                      |

## MCP servers

| Name                | Upstream | Status | Auth | Records |
| ------------------- | -------- | ------ | ---- | ------- |
| *none surveyed yet* |          |        |      |         |

## Backlog (TODO `P?` items)

See the [`P?` lane in `TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md):

- `[?/L]` **LangChain / LangSmith / LangServe / LangGraph / Langfuse** — group orchestration + observability stack into one coherent skill set.
- `[?/L]` **LLM fine-tuning skill** — practical workflow for supervised fine-tuning and adapter-based tuning.
- `[?/M]` **Build MCP skill** — minimum workflow for creating, testing, and documenting MCP servers (note: `mcp-builder` is already vendored — re-evaluate if this still needed).
- `[?/M]` **Hugging Face Spaces + Gradio skill** — demo app deployment, secrets, local-to-hosted handoff.
- `[?/M]` **Data visualization skill** — Matplotlib + Seaborn + Plotly for exploratory + report-ready output.

## See also

- [`docs/reference/deep-research-landscape.md`](https://daviddwlee84.github.io/agent-skills/reference/deep-research-landscape/index.md) — survey of deep-research tooling and personas.
- [`docs/reference/llm-wiki-pattern.md`](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — Karpathy's LLM Wiki pattern for personal research notes.
- [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) — overlap on experiment-tracking + notebook stack.

# Finance

Banking, capital markets, equity research, wealth management, fund admin, and accounting workflows. For trading-strategy / factor-research / backtesting work, see the [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) hub.

## Skills in this repo

### Local

| Skill         | One-line | Notes                                                                                                                                                                                                                                                                                        |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *none direct* |          | [`quantatitive-factor-researcher`](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md) is the closest fit but is quant-flavored — see the [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) hub. |

### Vendored

| Skill      | Upstream | Series |
| ---------- | -------- | ------ |
| *none yet* |          |        |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

| Skill / Plugin                                     | Upstream                                                                                                                                                                              | Status      | Why this status                                                                                                                                                                                                                                                                        | Install hint                                                                                                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `claude-for-financial-services` (full marketplace) | [`anthropics/financial-services`](https://github.com/anthropics/financial-services)                                                                                                   | `wishlist`  | Massive marketplace (11 named agents + 7 vertical plugins + partner plugins). Needs evaluation per-plugin — most assume Cowork / Managed Agents deployment, not solo Claude Code.                                                                                                      | `claude plugin marketplace add anthropics/financial-services` then pick a plugin (e.g. `financial-analysis`, `equity-research`, `investment-banking`). |
| `financial-analysis` plugin (subset)               | [`anthropics/financial-services/plugins/vertical-plugins/financial-analysis`](https://github.com/anthropics/financial-services/tree/main/plugins/vertical-plugins/financial-analysis) | `wishlist`  | Core skills (DCF, LBO, comps, 3-statement) + 11 MCP connectors. Highest-value entry point if vendoring any subset.                                                                                                                                                                     | `claude plugin install financial-analysis@claude-for-financial-services`                                                                               |
| `Awesome-finance-skills` curated list              | [`RKiding/Awesome-finance-skills`](https://github.com/RKiding/Awesome-finance-skills)                                                                                                 | `wishlist`  | Eight-skill bundle (news, stock data, sentiment, forecasting, signal tracking, viz, reporting, web search). Plug-and-play for finance-flavored agents. Independent author — verify license + maintenance.                                                                              | Inspect upstream `SKILL.md` layout, then `npx skills@latest add RKiding/Awesome-finance-skills`.                                                       |
| Six skills (Claude for Financial Services)         | [Claude tutorial](https://claude.com/resources/tutorials/claude-for-financial-services-skills)                                                                                        | `evaluated` | Toggleable in Settings → Capabilities → Skills (no manual install). Tutorial only — exclusive to Claude for Financial Services accounts. Documents 6 first-party skills: Comps Analysis, DCF, Initiating Coverage Research, Strip Profile, Due Diligence Data Pack, Earnings Analysis. | Not installable via `npx skills`; surfaced in the official Claude UI for FSI accounts.                                                                 |

## MCP servers

| Name                            | Upstream                                                                               | Status     | Auth                | Records                                                                                               |
| ------------------------------- | -------------------------------------------------------------------------------------- | ---------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| Financial Datasets MCP          | [`docs.financialdatasets.ai/mcp-server`](https://docs.financialdatasets.ai/mcp-server) | `wishlist` | OAuth 2.1 + API key | [Per-MCP page](https://daviddwlee84.github.io/agent-skills/catalog/mcp/financialdatasets-ai/index.md) |
| LSEG, S&P Global, FactSet, etc. | bundled in `anthropics/financial-services/financial-analysis/.mcp.json`                | `wishlist` | Provider-specific   | *no per-MCP record yet — add when evaluated*                                                          |

## Backlog (TODO `P?` items)

See the [`P?` lane in `TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md):

- `[?/L]` **Financial data sources skill set** — compare free vs paid market-data providers, regional coverage, organize-by-provider vs by-workflow. → [`backlog/financial-data-sources.md`](https://github.com/daviddwlee84/agent-skills/blob/main/backlog/financial-data-sources.md)

## See also

- [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) — trading strategies, backtesting, factor research.
- [MCP wiki: Financial Datasets](https://daviddwlee84.github.io/agent-skills/catalog/mcp/financialdatasets-ai/index.md) — first populated MCP record in the wiki.
- [`docs/reference/llm-wiki-pattern.md`](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — Karpathy's pattern for personal knowledge bases (relevant when curating provider-specific notes).

# Knowledge Work

Job-function plugins for sales / legal / customer support / product management / marketing / data / etc. Driven primarily by Anthropic's [Knowledge Work Plugins](https://github.com/anthropics/knowledge-work-plugins) program. This hub is mostly a registry today — we don't ship local skills in this space, but track external offerings for future use.

## Skills in this repo

### Local

| Skill      | One-line | Notes                                                                                                                                                   |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *none yet* |          | This repo focuses on engineering / ML / docs tooling. Knowledge-work plugins are job-function-shaped and overlap less with the maintainer's day-to-day. |

### Vendored

| Skill      | Upstream | Series |
| ---------- | -------- | ------ |
| *none yet* |          |        |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

The full Anthropic Knowledge Work Plugins marketplace (11 plugins, MIT licensed). Each is a Cowork / Claude Code plugin bundling skills + slash commands + MCP connectors specific to a job function.

| Plugin                     | Upstream                                                                                                                  | Status     | Why this status                                                                                                                                                             | Install hint                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `productivity`             | [knowledge-work-plugins/productivity](https://github.com/anthropics/knowledge-work-plugins/tree/main/productivity)        | `wishlist` | Generic task / calendar / workflow plugin. Slack + Notion + Asana + Linear + Jira + Monday + ClickUp + Microsoft 365 connectors.                                            | `claude plugin install productivity@knowledge-work-plugins`             |
| `sales`                    | [`.../sales`](https://github.com/anthropics/knowledge-work-plugins/tree/main/sales)                                       | `wishlist` | Prospect research, call prep, pipeline review.                                                                                                                              | `claude plugin install sales@knowledge-work-plugins`                    |
| `customer-support`         | [`.../customer-support`](https://github.com/anthropics/knowledge-work-plugins/tree/main/customer-support)                 | `wishlist` | Ticket triage, escalations, KB articles.                                                                                                                                    | `claude plugin install customer-support@knowledge-work-plugins`         |
| `product-management`       | [`.../product-management`](https://github.com/anthropics/knowledge-work-plugins/tree/main/product-management)             | `wishlist` | Specs, roadmaps, user research, competitive tracking.                                                                                                                       | `claude plugin install product-management@knowledge-work-plugins`       |
| `marketing`                | [`.../marketing`](https://github.com/anthropics/knowledge-work-plugins/tree/main/marketing)                               | `wishlist` | Content, campaigns, brand voice, performance reporting.                                                                                                                     | `claude plugin install marketing@knowledge-work-plugins`                |
| `legal`                    | [`.../legal`](https://github.com/anthropics/knowledge-work-plugins/tree/main/legal)                                       | `wishlist` | Contract review, NDAs, compliance, risk assessment.                                                                                                                         | `claude plugin install legal@knowledge-work-plugins`                    |
| `finance`                  | [`.../finance`](https://github.com/anthropics/knowledge-work-plugins/tree/main/finance)                                   | `wishlist` | Journal entries, reconciliation, financial statements, audits. Cross-listed in [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) hub. | `claude plugin install finance@knowledge-work-plugins`                  |
| `data`                     | [`.../data`](https://github.com/anthropics/knowledge-work-plugins/tree/main/data)                                         | `wishlist` | SQL queries, visualization, statistical analysis, dashboards. Snowflake + Databricks + BigQuery connectors.                                                                 | `claude plugin install data@knowledge-work-plugins`                     |
| `enterprise-search`        | [`.../enterprise-search`](https://github.com/anthropics/knowledge-work-plugins/tree/main/enterprise-search)               | `wishlist` | Cross-tool search across email / chat / docs / wikis.                                                                                                                       | `claude plugin install enterprise-search@knowledge-work-plugins`        |
| `bio-research`             | [`.../bio-research`](https://github.com/anthropics/knowledge-work-plugins/tree/main/bio-research)                         | `wishlist` | Cross-listed in [AI/ML Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/ai-ml-research/index.md) hub.                                                  | `claude plugin install bio-research@knowledge-work-plugins`             |
| `cowork-plugin-management` | [`.../cowork-plugin-management`](https://github.com/anthropics/knowledge-work-plugins/tree/main/cowork-plugin-management) | `wishlist` | Meta-plugin for organizations creating their own plugins.                                                                                                                   | `claude plugin install cowork-plugin-management@knowledge-work-plugins` |

Marketplace bootstrap (one-time, then install any of the above):

```
claude plugin marketplace add anthropics/knowledge-work-plugins
```

## MCP servers

| Name                                                                                            | Upstream | Status | Auth | Records |
| ----------------------------------------------------------------------------------------------- | -------- | ------ | ---- | ------- |
| *none surveyed yet* — most knowledge-work plugins bundle MCP connectors directly in `.mcp.json` |          |        |      |         |

## Backlog (TODO `P?` items)

- *none yet — open a TODO `P?` if you want to evaluate a specific plugin.*

## See also

- [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) — has overlap with `finance` and `data` plugins.
- [AI/ML Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/ai-ml-research/index.md) — cross-lists `bio-research`.
- Upstream README: [`anthropics/knowledge-work-plugins`](https://github.com/anthropics/knowledge-work-plugins) — full plugin matrix + connector list.

# Quant Research

Quantitative trading, factor research, backtesting, and live-execution workflows. Distinct from the [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) hub (which covers banking / capital markets / equity research / fund admin) — overlap is mostly on the data-source side.

## Skills in this repo

### Local

| Skill                                                                                                                          | One-line                                                                                                                       | Notes                        |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| [`quantatitive-factor-researcher`](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md) | Python quant-research persona for factor engineering, backtesting, cross-validation, and Sharpe / IR / Tracking Error metrics. | Anchor skill of this hub.    |
| [`vectorbt`](https://daviddwlee84.github.io/agent-skills/skills/vectorbt/index.md)                                             | OSS/PRO library development, release-aligned XDG docs, migration checks, and optional MCP.                                     | `quantitative-finance` group |
| [`nautilus-trader`](https://daviddwlee84.github.io/agent-skills/skills/nautilus-trader/index.md)                               | v1 Cython / v2 Rust-PyO3 generation detection, git-tag docs cache, event-driven backtests, sandbox/live-trading gates.         | `quantitative-finance` group |

### Vendored

| Skill      | Upstream | Series |
| ---------- | -------- | ------ |
| *none yet* |          |        |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

| Skill / Plugin              | Upstream                                                                                              | Status    | Why this status                                                                                                 | Install hint          |
| --------------------------- | ----------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | --------------------- |
| VectorBT Backtesting Skills | [marketcalls/vectorbt-backtesting-skills](https://github.com/marketcalls/vectorbt-backtesting-skills) | `skipped` | Evaluated OSS workflow; OpenAlgo indicator defaults do not match this library-focused skill.                    | Upstream instructions |
| NautilusTrader docs skill   | [aysuio/nt-skill](https://github.com/aysuio/nt-skill)                                                 | `skipped` | No license; assumes hosted `latest` docs track the installed release, which fails during the v1 → v2 RC period. | Upstream instructions |
| NautilusTrader skill        | [clay584/nautilus-trader-skill](https://github.com/clay584/nautilus-trader-skill)                     | `skipped` | No license; verified against 1.228.0 and teaches the v1 `TradingNode` API.                                      | Upstream instructions |

## MCP servers

| Name                   | Upstream                                                                               | Status     | Auth                | Records                                                                                               |
| ---------------------- | -------------------------------------------------------------------------------------- | ---------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| Financial Datasets MCP | [`docs.financialdatasets.ai/mcp-server`](https://docs.financialdatasets.ai/mcp-server) | `wishlist` | OAuth 2.1 + API key | [Per-MCP page](https://daviddwlee84.github.io/agent-skills/catalog/mcp/financialdatasets-ai/index.md) |

## Backlog (TODO `P?` items)

See the [`P?` lane in `TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md):

- `[?/L]` **Tardis SDK skill** — historical market data workflows, access assumptions, and example-driven guidance.
- `[?/L]` **Financial data sources skill set** — provider comparison (cross-listed in [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md)).

## See also

- [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) — banking, capital markets, equity research workflows.
- [AI/ML Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/ai-ml-research/index.md) — for the experiment tracking + notebook ecosystem (`mlflow-tracking`, `marimo-batch-mlflow`) that quant projects often layer on.
- [`docs/skills/quantatitive-factor-researcher.md`](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md), [`vectorbt.md`](https://daviddwlee84.github.io/agent-skills/skills/vectorbt/index.md), and [`nautilus-trader.md`](https://daviddwlee84.github.io/agent-skills/skills/nautilus-trader/index.md) — the local skill pages.

# Web & Fullstack

Web app development — Next.js / React / Tailwind / shadcn / Supabase / Vercel / Postgres / browser automation / GitHub workflow / web quality audits. This is the most-populated domain in this repo, anchored by the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/index.md) series.

## Skills in this repo

### Owned

| Skill                                                                                                        | Canonical project                                                            | Notes                                                                                   |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [userscript-development](https://daviddwlee84.github.io/agent-skills/skills/userscript-development/index.md) | [Tampermonkey-Scripts](https://github.com/daviddwlee84/Tampermonkey-Scripts) | SPA/GM lifecycle, Chromium/Firefox fixtures, real-manager and reference-extension tests |

### Local

| Skill                                                                                                          | One-line                                        | Notes                                                                     |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| [`openui-direct-provider`](https://daviddwlee84.github.io/agent-skills/skills/openui-direct-provider/index.md) | OpenUI generative UI on your own model provider | Provider-neutral companion to vendored `openui`; no Gateway unless asked. |

### Vendored

`fullstack-nextjs` series (9 skills, all from official orgs):

| Skill                                                                                                                              | Upstream                                                                  | Series                                         |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- |
| [`nextjs`](https://daviddwlee84.github.io/agent-skills/skills/nextjs/index.md)                                                     | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)         | `fullstack-nextjs`                             |
| [`shadcn`](https://daviddwlee84.github.io/agent-skills/skills/shadcn/index.md)                                                     | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)         | `fullstack-nextjs`                             |
| [`react-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/react-best-practices/index.md)                         | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)         | `fullstack-nextjs`                             |
| [`vercel-storage`](https://daviddwlee84.github.io/agent-skills/skills/vercel-storage/index.md)                                     | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)         | `fullstack-nextjs`                             |
| [`supabase`](https://daviddwlee84.github.io/agent-skills/skills/supabase/index.md)                                                 | [`supabase/agent-skills`](https://github.com/supabase/agent-skills)       | `fullstack-nextjs`                             |
| [`supabase-postgres-best-practices`](https://daviddwlee84.github.io/agent-skills/skills/supabase-postgres-best-practices/index.md) | [`supabase/agent-skills`](https://github.com/supabase/agent-skills)       | `fullstack-nextjs`                             |
| [`web-design-guidelines`](https://daviddwlee84.github.io/agent-skills/skills/web-design-guidelines/index.md)                       | [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills) | `fullstack-nextjs`                             |
| [`frontend-design`](https://daviddwlee84.github.io/agent-skills/skills/frontend-design/index.md)                                   | [`anthropics/skills`](https://github.com/anthropics/skills)               | `fullstack-nextjs`                             |
| [`webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md)                                     | [`anthropics/skills`](https://github.com/anthropics/skills)               | `fullstack-nextjs`                             |
| [`openui`](https://daviddwlee84.github.io/agent-skills/skills/openui/index.md)                                                     | [`thesysdev/skills`](https://github.com/thesysdev/skills)                 | — (flat, `generative-ui` group; Gateway-first) |

GitHub workflow + web quality (Warp Oz, see [`docs/reference/warp-oz-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md)):

| Skill                                                                              | Upstream                                                          | Notes                                                     |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
| `ci-fix`, `create-pull-request`, `github-bug-report-triage`, `github-issue-dedupe` | [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills) | All in `github-workflow` plugin grouping.                 |
| `web-accessibility-audit`, `web-performance-audit`                                 | [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills) | `web-performance-audit` requires the Chrome DevTools MCP. |

## External skills (manual install)

Status enum (single source of truth across the catalog)

Every external-skill or MCP entry below carries a `status:` value:

| Status      | Meaning                                                                                         | Where it links                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vendored`  | Already in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml). | Link to the `skills/vendor/<name>/` (or series) entry.                                          |
| `deferred`  | Open `TODO P?` item — under consideration.                                                      | Link to the [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) anchor. |
| `skipped`   | Looked at, chose not to vendor.                                                                 | Inline reason required (1 sentence).                                                            |
| `evaluated` | Read but no decision recorded. Effectively "tracked."                                           | Inline 1-line note describing what was learned.                                                 |
| `wishlist`  | Surfaced but not yet evaluated.                                                                 | No link required; default for fresh discoveries.                                                |

Status changes are explicit edits — see the **Adding catalog entries** workflow doc (under `Workflows` in the nav) for the `wishlist → deferred → vendored` recipe.

Manual install for non-vendored skills

When a skill is not in `vendor.yaml`, you can still install it directly from upstream via the [`npx skills`](https://skills.sh) CLI:

```
# Whole-repo install (if SKILL.md sits at repo root or skills/)
npx skills@latest add <owner>/<repo>

# Subpath install (when the skill is nested)
npx skills@latest add <owner>/<repo>/<path-to-skill-dir>

# Cherry-pick by name
npx skills@latest add <owner>/<repo> -s <skill-name>

# Force deep discovery (skill nested >1 level inside skills/)
npx skills@latest add <owner>/<repo> --full-depth -s <skill-name>
```

For Anthropic-style **plugin marketplaces** (e.g. `anthropics/financial-services`, `anthropics/knowledge-work-plugins`), use the Claude Code plugin commands instead:

```
claude plugin marketplace add <owner>/<repo>
claude plugin install <plugin-name>@<repo-name>
```

For MCP servers, see the per-entry "Auth & install" section in the MCP wiki — install commands vary by transport (HTTP / stdio / SSE) and host (Claude Code / Claude Desktop / Cursor / Managed Agents).

| Skill / Plugin                           | Upstream                                                                                                                     | Status      | Why this status                                                                                                                                                                                                                                    | Install hint                                                                     |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `tampermonkey`                           | [henkisdabro/wookstar-claude-plugins](https://github.com/henkisdabro/wookstar-claude-plugins/tree/main/plugins/tampermonkey) | `skipped`   | API-focused; the owned skill captures our lifecycle/native-testing workflow. [Review](https://daviddwlee84.github.io/agent-skills/skills/userscript-development/#existing-skills-considered).                                                      | `npx skills@1.5.25 add henkisdabro/wookstar-claude-plugins --skill tampermonkey` |
| `develop-userscripts`                    | [xixu-me directory listing](https://skills.sh/xixu-me/skills/develop-userscripts)                                            | `evaluated` | Listing reviewed; upstream API returned 404 on 2026-09-09.                                                                                                                                                                                         | Source/installability unverified                                                 |
| `userscript-creator`                     | [andradeatdev directory listing](https://skills.sh/andradeatdev/skills/userscript-creator)                                   | `wishlist`  | Search result only; upstream API returned 404 on 2026-09-09.                                                                                                                                                                                       | Source/installability unverified                                                 |
| Other `vercel/vercel-plugin` skills      | [`vercel/vercel-plugin`](https://github.com/vercel/vercel-plugin)                                                            | `evaluated` | We already vendored 4 of them into `fullstack-nextjs`. Remaining ones (e.g. `tailwind`, `vercel-ai-sdk`, etc.) are candidates if needed.                                                                                                           | `npx skills@latest add vercel/vercel-plugin -s <skill>`                          |
| Remaining `vercel-labs/agent-skills`     | [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)                                                    | `evaluated` | We vendored `web-design-guidelines`. Others are similar audit-style skills.                                                                                                                                                                        | `npx skills@latest add vercel-labs/agent-skills -s <skill>`                      |
| Other `warpdotdev/oz-skills` (9 skipped) | [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills)                                                            | `skipped`   | Skipped per [`docs/reference/warp-oz-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md): `mcp-builder` (duplicate), `webapp-testing` (duplicate), `scheduler` (too narrow), Slack-/BigQuery-specific ones. | (not vendored)                                                                   |

## MCP servers

| Name              | Upstream                                                                                            | Status      | Auth        | Records                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------- | ----------- | ----------- | ------------------------------------------------------------- |
| `chrome-devtools` | [`@modelcontextprotocol/server-chrome-devtools`](https://www.npmjs.com/package/chrome-devtools-mcp) | `evaluated` | Local stdio | *no per-MCP record yet — required by `web-performance-audit`* |

## Backlog (TODO `P?` items)

See the [`P?` lane in `TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md):

- `[?/M]` **Playwright skill** — web automation, testing, and website-cloning workflows realistic for agents to maintain.
- `[?/L]` **Sibling docs-stack skills (docusaurus / vitepress / hugo / sphinx)** — paired with the existing `mkdocs-site-bootstrap` skill.

## See also

- [`docs/reference/browser-automation-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/browser-automation-skills/index.md) — Playwright vs agent-browser vs browser-use vs stagehand vs Playwright MCP comparison.
- [`docs/reference/warp-oz-skills.md`](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md) — Warp Oz GitHub-workflow + web-quality skills.
- [`docs/skills/index.md`](https://daviddwlee84.github.io/agent-skills/skills/#fullstack-nextjs-series) — full Skills overview with the `fullstack-nextjs` series tables.

# MCP wiki

A personal-knowledge area for [Model Context Protocol](https://modelcontextprotocol.io/) servers we've evaluated, use, or want to track. Modeled after [Karpathy's LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — each entry is a curated record, not a vendored install target.

## Entries

| Name                                                                                                            | Domain                                                                                                                                                                                          | Status     | Auth                | Hosting                             |
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------- | ----------------------------------- |
| [Financial Datasets MCP](https://daviddwlee84.github.io/agent-skills/catalog/mcp/financialdatasets-ai/index.md) | [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) / [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) | `wishlist` | OAuth 2.1 + API key | Hosted (`mcp.financialdatasets.ai`) |

## Why a wiki, not a registry?

A registry needs an opinion on every MCP and a curation team. A wiki is just notes the maintainer wants to keep. The value is in *recording the decision* (use it, skip it, defer it, why) so future-you doesn't re-research the same MCP.

This wiki is intentionally aligned with the [LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — pages are written by hand for now (small N), with frontmatter that future automation can parse to regenerate the index table.

## Per-entry conventions

Every MCP entry is one markdown file under `docs/catalog/mcp/<slug>.md`, with required YAML frontmatter:

```
---
name: <human-readable name>
slug: <kebab-case slug, matches filename>
upstream_url: <docs URL>
transport: HTTP | stdio | SSE | mixed
auth: <one-line description>
hosting: Hosted (<host>) | Local | Self-hosted
domain: <one of the domain hub slugs>
status: vendored | deferred | skipped | evaluated | wishlist
license: <SPDX or "Proprietary">
last_verified: <YYYY-MM-DD>
---
```

The page body follows a consistent structure:

1. **TL;DR** (2 sentences)
1. **Tools / capabilities** (table, ~6-12 rows)
1. **Auth & install** (one snippet per host: Claude Code, Claude Desktop, Cursor, Managed Agents)
1. **When to use it / When NOT to use it** (paired bullets)
1. **Related skills in this repo** (cross-links to `docs/skills/*` or domain hubs)
1. **Upstream sources** (1-3 links — docs / GitHub / blog post)

The `status` field uses the same enum as [external skill entries](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/index.md) — see the snippet at the top of any catalog page for the full enum table.

## See also

- [LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — Karpathy's pattern this wiki is modeled after.
- [Domains](https://daviddwlee84.github.io/agent-skills/catalog/domains/index.md) — each domain hub lists relevant MCPs.
- Upstream MCP directory: [modelcontextprotocol.io/servers](https://github.com/modelcontextprotocol/servers).

# Financial Datasets MCP

## TL;DR

Hosted MCP server exposing real-time + historical equities data: pricing, financial statements, SEC filings, news, insider trades, and screening. 20+ tools accessible from Claude Code / Claude Desktop / Cursor / Managed Agents via OAuth 2.1 (interactive) or API key (programmatic).

## Tools / capabilities

| Category             | Examples                                                   |
| -------------------- | ---------------------------------------------------------- |
| Pricing              | Current + historical stock prices                          |
| Financial statements | Income, balance sheet, cash flow, segmented financials     |
| Metrics              | P/E, market cap, enterprise value, dividend yields         |
| Company info         | Sector, industry, employee counts                          |
| SEC filings          | 10-K, 10-Q, 8-K + extractable sections (e.g. Risk Factors) |
| Market intelligence  | News, insider trades, earnings data                        |
| Screening            | Filter stocks by valuation + financial criteria            |
| Specialized          | KPI guidance, non-GAAP metrics, central bank rates         |

## Auth & install

### Claude Code

```
claude mcp add --transport http financial-datasets https://mcp.financialdatasets.ai/
```

OAuth flow runs in the browser on first use.

### Claude Desktop

Settings → Connectors → Add custom connector → paste `https://mcp.financialdatasets.ai/`. OAuth flow runs in-app.

### Cursor

Edit `~/.cursor/mcp.json`:

```
{
  "mcpServers": {
    "financial-datasets": {
      "url": "https://mcp.financialdatasets.ai/",
      "transport": "http"
    }
  }
}
```

### Managed Agents (programmatic)

Use static bearer vault credentials with the `/api` endpoint (`X-API-KEY` header). See [upstream auth docs](https://docs.financialdatasets.ai/mcp-server) for the API key issuance flow.

## When to use it

- Quick equities lookups during research / writeup workflows.
- Cross-checking SEC filing claims against actual filings.
- Stock screening with valuation criteria.
- Pulling time series for ad-hoc charts.

## When NOT to use it

- Heavy time-series workloads — fetch raw data via the REST API and cache locally instead. MCP is per-call.
- Non-equity asset classes (futures, FX, crypto). Coverage is equity-first.
- Backtesting (latency + per-call cost). Use a [Tardis](https://tardis.dev/) / vendor SDK + local cache instead.
- Anything requiring deterministic snapshots (the MCP is live data).

## Related skills in this repo

- [`quantatitive-factor-researcher`](https://daviddwlee84.github.io/agent-skills/skills/quantatitive-factor-researcher/index.md) — local skill that could consume this MCP for factor data.
- [Finance](https://daviddwlee84.github.io/agent-skills/catalog/domains/finance/index.md) — domain hub.
- [Quant Research](https://daviddwlee84.github.io/agent-skills/catalog/domains/quant-research/index.md) — domain hub.

## Upstream sources

- [Financial Datasets MCP docs](https://docs.financialdatasets.ai/mcp-server) — install + tool reference.
- [Financial Datasets API docs](https://docs.financialdatasets.ai/) — underlying REST API the MCP wraps.
# Reference

# Agent skill compatibility

This page records the cross-agent `SKILL.md` constraints this repo targets. The goal is practical portability across coding agents, not the broadest set of optional product-specific extensions.

## Baseline we target

Use the [Agent Skills specification](https://agentskills.io/specification) as the portable baseline:

| Field                | Repo policy                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | Required, 1-64 chars, lowercase letters/digits with single hyphen separators, no leading/trailing hyphen, no `--`, should match the skill directory |
| `description`        | Required, 1-1024 chars, describes both what the skill does and when to use it                                                                       |
| `SKILL.md` body      | Keep under ~500 lines; move long detail into `references/`                                                                                          |
| Optional frontmatter | Allowed only when a target agent needs it; keep local skills portable by default                                                                    |

Description budget tiers used by `skill-author`:

| Tier   | Length         | Meaning                                                                  |
| ------ | -------------- | ------------------------------------------------------------------------ |
| Green  | 120-500 chars  | Preferred for local skills: enough trigger surface without context bloat |
| Yellow | 501-900 chars  | Valid, but context-heavy; move details to the body or references         |
| Orange | 901-1024 chars | Valid, but close to hard loader limits                                   |
| Red    | >1024 chars    | Invalid for Codex/Cursor/spec-aligned validators                         |

Also make the first 60 characters useful. The `npx skills` installer truncates picker hints to 60 characters, and Codex may shorten descriptions when the installed skill list is large.

## Agent notes

| Tool              | Preference / constraint                                                                                                                                                                                                                                                                | Link                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Agent Skills spec | Defines the portable directory layout, frontmatter fields, 64-char `name`, 1024-char `description`, optional `scripts/`, `references/`, and `assets/`.                                                                                                                                 | [Specification](https://agentskills.io/specification)                                                           |
| Codex             | Starts with each skill's name, description, and path, then loads full `SKILL.md` only when selected. The initial skills list has a context budget; descriptions should be concise and front-loaded. Codex can use optional `agents/openai.yaml` for UI metadata and invocation policy. | [Codex skills docs](https://developers.openai.com/codex/skills/create-skill)                                    |
| Claude Code       | Follows the open standard and adds fields such as `when_to_use`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `context`, and `hooks`. It truncates combined `description`/`when_to_use` listing text at 1,536 chars.                                                 | [Claude Code skills docs](https://code.claude.com/docs/en/skills)                                               |
| Cursor            | Uses `SKILL.md` skills with the same practical 64-char `name` and 1024-char `description` budget in its managed `create-skill` guidance. It also supports `disable-model-invocation` for explicit-only skills.                                                                         | [Cursor skills docs](https://cursor.com/docs/skills)                                                            |
| OpenCode          | Recognizes `.opencode/skills`, `.claude/skills`, and `.agents/skills`; only specific frontmatter fields are recognized, unknown fields are ignored. It enforces 1-64 char names and 1-1024 char descriptions.                                                                          | [OpenCode Agent Skills](https://opencode.ai/docs/skills/)                                                       |
| `npx skills`      | Installer/distributor. Reads `name` and `description` from `SKILL.md`, shows only a 60-char description hint in the picker, and uses `.claude-plugin/marketplace.json` for grouping.                                                                                                   | [npx skills metadata model](https://daviddwlee84.github.io/agent-skills/reference/npx-skills-metadata/index.md) |

## How this repo applies it

- Local skills should keep `description` in the green tier unless there is a concrete trigger-coverage reason to go longer.
- `skills/local/skill-author/scripts/lint-skill.sh` enforces the portable hard limits: hyphen-case names, 64-char names, and 1024-char descriptions. It also reports yellow/orange tier notes without failing strict mode.
- `skills/local/skill-author/assets/SKILL.md.template` tells new authors to target 120-500 chars and never exceed 1024.
- Detailed trigger examples belong in `SKILL.md` body or `references/`, not in an oversized frontmatter description.
- Product-specific metadata is acceptable when needed, but should be deliberate: prefer portable frontmatter for local skills, leave vendored upstream metadata intact, and document any target-agent-only field in the skill body.

## Incident that set the policy

`mkdocs-site-bootstrap` previously had a 1106-character frontmatter `description`. Codex 0.128.0 skipped it as invalid because the description exceeded 1024 characters. We shortened the description to 489 characters and updated `skill-author` so future local skills are caught before install-time loader failures.

# Browser automation skills & MCPs

This page compares the popular **browser automation tools shipped as agent skills or MCP servers**. Browser automation is one of the highest- value capabilities you can give a coding agent — but the design choices across these tools differ substantially. This page records the trade-offs so the choice is explicit, and explains why this repo currently does *not* vendor any of them.

## At a glance

Five well-known options, all roughly the same goal — let an agent open a real browser and interact with pages — but very different shapes:

| Tool                                                                        | ⭐                   | Form                                                                       | Auth/session                                                         | Cost model                                   | Token-efficient surface                                  |
| --------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------- |
| [`microsoft/playwright-cli`](https://github.com/microsoft/playwright-cli)   | 10k                  | CLI + 1 SKILL.md                                                           | Local Chromium / your profile                                        | Free, local                                  | a11y-tree snapshot + `eN` refs                           |
| [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser) | 33k                  | CLI + 1 SKILL.md                                                           | Local Chromium, profile, Vercel Sandbox, AWS Bedrock AgentCore cloud | Free CLI; Vercel/AWS pay-as-you-go for cloud | a11y-tree snapshot + compact `@eN` refs                  |
| [`browser-use/browser-use`](https://github.com/browser-use/browser-use)     | 93k                  | CLI + 4 SKILL.md (`browser-use`, `cloud`, `open-source`, `remote-browser`) | Local + Browser Use Cloud                                            | Open-source local; Cloud SaaS                | Persistent daemon (~50 ms/call); MCP also available      |
| [`browserbase/stagehand`](https://github.com/browserbase/stagehand)         | 23k                  | TypeScript SDK                                                             | Browserbase cloud (or local Playwright)                              | Browserbase metered                          | Code-first (`page.act("click sign in")`); not a SKILL.md |
| [Playwright MCP](https://playwright.dev/agent-cli/introduction)             | (part of Playwright) | MCP server                                                                 | Local Chromium                                                       | Free, local                                  | a11y tree, but full MCP schema overhead                  |

> Star counts are repo totals (the project, not just the skill). Don't use them to compare per-skill quality — `browser-use/browser-use` is a framework with very high stars; the SKILL.md inside it is one deliverable among many.

## The design axes that actually matter

Pick on these, not on stars:

### 1. CLI vs MCP vs SDK

- **CLI + SKILL.md** — `playwright-cli`, `agent-browser`, `browser-use` (CLI mode). The agent shells out to `playwright-cli click e15`. Each command is one short tool call; no MCP schema to load. **Best for token efficiency** when the agent has Bash access. The Microsoft README and the agent-browser README both argue this beats the MCP approach for high-throughput agent loops.
- **MCP server** — Playwright MCP, `browser-use` MCP. The agent calls `mcp_call("playwright.click", {...})`. Loads the full schema once; cleaner for agents without Bash but pays the MCP overhead. Token cost per call is higher than CLI for the same operation.
- **SDK** — Stagehand. You write TypeScript that calls `page.act("…")`. Powerful for *application code* you ship; not a skill the agent invokes ad-hoc.

### 2. Snapshot strategy — a11y tree vs DOM vs vision

- **Accessibility-tree snapshot + element refs** (`playwright-cli`, `agent-browser`, Playwright MCP). The agent sees a structured tree with stable `eN` / `@eN` refs and uses them directly. Token-cheap, reliable, no fragile selectors.
- **DOM + selectors** (older Playwright / Selenium patterns). Larger context, brittle.
- **Vision-first** (`magnitudedev/browser-agent`, 4k⭐). Agent reasons over screenshots. Robust against DOM changes; high token + latency cost; useful when the page is an opaque webapp.

### 3. Where the browser actually runs

- **Local Chromium** (default for all CLIs above) — fast, free, uses your machine.
- **Local Chrome with your real profile** (`agent-browser`, `browser-use`) — sees your real cookies and logged-in state. Powerful; also a security surface.
- **Cloud browser** — Vercel Sandbox / AWS Bedrock AgentCore (`agent-browser`); Browser Use Cloud (`browser-use`); Browserbase (`stagehand`). Pay-per-session; required for headless servers, scale, or compliance.

### 4. Persistent session vs cold-start per call

- **Persistent daemon** (`browser-use` CLI) — keeps Chromium alive between commands; ~50 ms per call. Best for long agent loops on the same site.
- **Per-call session** (`playwright-cli` defaults, Playwright MCP) — starts/stops cleanly; safer for one-shot tasks. Higher per-call latency.

## Recommendation matrix

| Need                                                      | Pick                                                      |
| --------------------------------------------------------- | --------------------------------------------------------- |
| Token-efficient browser CLI for any agent with Bash       | `agent-browser` or `playwright-cli`                       |
| Already on Playwright in CI                               | `playwright-cli` (same engine, same selectors)            |
| Long-running session, lowest per-call latency             | `browser-use` CLI                                         |
| Production agents, cloud parallel browsers                | `agent-browser` (Vercel/AWS) or `stagehand` (Browserbase) |
| Pages that defeat DOM scraping (heavy canvases, anti-bot) | Vision-first (`magnitudedev/browser-agent`)               |
| Want code-level control inside a TypeScript app           | `stagehand` SDK                                           |
| Agent doesn't have Bash, only MCP                         | Playwright MCP or `browser-use` MCP                       |

## What this repo vendors

**None of these.** Recorded so future agents don't relitigate it:

- **Heavy install surface** — Chromium download, persistent profiles, daemon processes, optional cloud accounts. Vendoring as a SKILL.md doesn't actually install the underlying CLI; users still need `npm i -g agent-browser`, `pip install browser-use`, etc.
- **Per-project rather than user-global** — browser automation skills often touch real auth/cookies and per-site quirks. Better installed per project where the operator can review the SKILL.md, hooks, and any MCP config first.
- **Security audit signal** — Skills.sh shows a failed Gen Agent Trust Hub audit on `browser-use/browser-use` at the time of writing. Good enough reason to defer until the situation clarifies.
- **Anthropic `webapp-testing` already covers the common case** — for agent-driven QA of a web app this repo already vendors [`anthropics/skills/webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md) under the [`fullstack-nextjs`](https://daviddwlee84.github.io/agent-skills/skills/index.md) series, which uses Playwright under the hood without committing to a specific browser CLI.

If you decide you need one, install per project:

```
# Token-efficient CLI route (recommended for OpenCode / Claude Code / Codex)
npx skills add vercel-labs/agent-browser

# Long-running daemon route
npx skills add browser-use/browser-use

# Same engine as your CI Playwright tests
npx skills add microsoft/playwright-cli
```

These compose with this repo's research and SDD skills — a deep-research session that needs a real browser can pair `vendor/deep-research` with any of the above without conflict.

## See also

- [Deep Research landscape](https://daviddwlee84.github.io/agent-skills/reference/deep-research-landscape/index.md) — browser automation is layer 4 in the deep-research stack
- [SDD frameworks & agent harnesses](https://daviddwlee84.github.io/agent-skills/reference/sdd-and-harnesses/index.md) — same CLI vs MCP vs framework distinction applied to spec-driven dev
- [`anthropics/webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md) — the Playwright-based testing skill already vendored in this repo
- [Agent skill compatibility](https://daviddwlee84.github.io/agent-skills/reference/agent-skill-compatibility/index.md) — portable `SKILL.md` constraints all the CLIs above respect

# Deep Research landscape

This page surveys the **commercial Deep Research products** from major AI vendors and the **open-source skills/frameworks** that try to reproduce similar capability locally. It also explains what this repo vendors (`deep-research/`) and which adjacent options are deliberately *not* vendored.

## Commercial Deep Research products (2024–2026)

The five major vendors converged on a similar shape — multi-agent planning, parallel retrieval, citation-grounded synthesis — but with different defaults around browser scope, model size, and pricing.

| Vendor        | Product                                                             | Launched           | Architecture                                        | Notable                                                                                                                           |
| ------------- | ------------------------------------------------------------------- | ------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI**    | ChatGPT Deep Research (`o3-deep-research`, `o4-mini-deep-research`) | 2025-02            | Plan → multi-step search → cited report             | Plus 25/mo, Pro 250/mo; 2026-02 added scoped sites + collaborative planning + live progress                                       |
| **Google**    | Gemini Deep Research (Interactions API)                             | 2024-12            | Lead agent + parallel sub-agents + synthesis agent  | Hooks into Gmail/Drive/Chat; 1M-token context; Canvas visualizations; 2026-04 added MCP tool connectors                           |
| **xAI**       | Grok DeepSearch / DeeperSearch / Grok 4 Heavy                       | 2024-Q2 → 2025-07  | Multi-agent parallel reasoning, live X + web search | 256k token context; no formal citations yet; emphasizes raw performance                                                           |
| **Anthropic** | Claude Research                                                     | 2025-06 (eng blog) | LeadResearcher + sub-agents + CitationAgent         | ~90% accuracy uplift over single-agent (Opus 4 lead + Sonnet 4 sub); strict enterprise privacy                                    |
| **Meta**      | (no first-party DR product)                                         | —                  | —                                                   | LLaMA 4 Scout/Maverick are multimodal foundation models; deep-research must be assembled from LangChain / LlamaIndex / vector DBs |

The shared pattern across all four shipping products:

1. **Plan** — decompose query into sub-questions
1. **Parallel retrieve** — spawn sub-agents that hit web search / docs / files
1. **Iterate** — re-plan based on what's found, follow citations
1. **Synthesize** — assemble a cited report (markdown / HTML / PDF)

Typical wall time is 2–20 minutes; cost is gated by subscription tier or per-call API metering.

## Reproducing Deep Research locally — the six layers

A real "deep research" stack for an agent CLI is **not a single skill**. Decompose it into six layers; pick a tool per layer:

| Layer                           | What it does                                                                     | Representative tools                                                                                                                                                 |
| ------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. **Planning / decomposition** | Turn the question into sub-questions, evidence requirements, and a research plan | `199-biotechnologies/claude-deep-research-skill` (vendored), `langchain-ai/deepagents` (Python framework, *not* a skill)                                             |
| 2. **Retrieval**                | Web / news / GitHub / PDF search                                                 | [`tavily-ai/skills/tavily-search`](https://github.com/tavily-ai/skills), [`firecrawl/cli/skills/firecrawl-search`](https://github.com/firecrawl/cli)                 |
| 3. **Extraction**               | Pull main content, tables, multi-page text out of fetched URLs                   | `firecrawl-scrape`, `firecrawl-crawl`, `firecrawl-parse`                                                                                                             |
| 4. **Browser interaction**      | Login walls, JS rendering, dynamic UIs, downloads                                | [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser) (32k⭐), [`browser-use/browser-use`](https://github.com/browser-use/browser-use) (93k⭐) |
| 5. **Evidence management**      | Source registry, claim ledger, citation verification                             | `199-biotechnologies/claude-deep-research-skill` (built-in)                                                                                                          |
| 6. **Synthesis**                | Final report (markdown / HTML / PDF) with inline citations                       | `199-biotechnologies/claude-deep-research-skill`, `tavily-ai/skills/tavily-research`                                                                                 |

The 2-skill minimum that gets you something usable: **(1) + (5) + (6)** from one disciplined research-flow skill, plus **(2)** from a search backend you trust.

## What this repo vendors

Just **one** skill, deliberately:

- **`vendor/deep-research/deep-research`** — from [`199-biotechnologies/claude-deep-research-skill`](https://github.com/199-biotechnologies/claude-deep-research-skill) (646⭐). A pure prompt-flow skill covering planning, evidence management, and synthesis. Four modes: `quick` (3 phases, 2–5 min), `standard` (6 phases, 5–10 min, default), `deep` (8 phases, 10–20 min), `ultradeep` (8+ phases, 20–45 min). Uses an evidence ledger + claim ledger so each finding traces back to its source.

**Why only one?** Deep-research stacks built from [`tavily-ai/skills`](https://github.com/tavily-ai/skills), [`firecrawl/cli`](https://github.com/firecrawl/cli), [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser), or [`browser-use/browser-use`](https://github.com/browser-use/browser-use) all introduce **paid API keys, hosted backends, or cloud browser sessions**. Keeping this repo cost-free by default means anyone can run the vendored research skill against whatever search/browser tools their agent already has (`WebSearch`, `WebFetch`, MCP, etc.) without signing up for a third-party service.

If you want a higher-fidelity pipeline, install those skills *alongside* this one — they compose cleanly.

## Adjacent options *not* vendored — and why

Recorded so future agents don't relitigate it:

| Option                                                                      | Stars | Why not vendored                                                                                                                                    |
| --------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`tavily-ai/skills`](https://github.com/tavily-ai/skills)                   | 285⭐ | Requires Tavily account / API key. Excellent if you're willing to pay; install separately when you are.                                             |
| [`firecrawl/cli`](https://github.com/firecrawl/cli)                         | 375⭐ | 9 skills (search/scrape/crawl/map/extract/agent…). Free tier exists but production use needs a key. Better as a per-project install.                |
| [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser) | 32k⭐ | Browser automation is a heavy dependency (Chromium, profiles). Out of scope for a research-only stack; install if you actually need it.             |
| [`browser-use/browser-use`](https://github.com/browser-use/browser-use)     | 93k⭐ | Skills.sh shows a failed Gen Agent Trust Hub security audit. Skip until that resolves.                                                              |
| [`langchain-ai/deepagents`](https://github.com/langchain-ai/deepagents)     | 22k⭐ | **Not a `SKILL.md` repo** — it's a Python package / framework. Cannot be vendored as an agent skill. ChatGPT-style summaries sometimes mislabel it. |
| [`24601/agent-deep-research`](https://github.com/24601/agent-deep-research) | 4⭐   | Genuine Gemini Interactions API wrapper, but too small / experimental to commit to. Worth re-evaluating later.                                      |

### Things that *look* like deep-research skills but aren't

- [`forrestchang/andrej-karpathy-skills`](https://github.com/forrestchang/andrej-karpathy-skills) (124k⭐) — name and star count are misleading. It's **a single `CLAUDE.md`** distilling four Karpathy observations on LLM coding pitfalls. Not a skill, not about research. See [Karpathy's LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) for the *separate* knowledge-base pattern Karpathy actually published in his [LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).

## See also

- [Karpathy's LLM Wiki pattern](https://daviddwlee84.github.io/agent-skills/reference/llm-wiki-pattern/index.md) — the persistent knowledge-base pattern that complements deep research (research produces reports; the wiki accumulates them)
- [SDD frameworks & agent harnesses](https://daviddwlee84.github.io/agent-skills/reference/sdd-and-harnesses/index.md) — same layering distinction (skill / framework / harness) applied to spec-driven development
- [Skill risk evaluations](https://daviddwlee84.github.io/agent-skills/reference/skills-risk-evaluations/index.md) — how to decide whether a workflow should become a skill at all

# Downstream docs stack recipe

> This page is now maintained as part of the `mkdocs-site-bootstrap` skill.
>
> The full recipe lives in the skill's reference file: [`skills/local/mkdocs-site-bootstrap/references/docs-stack-recipe.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/docs-stack-recipe.md)
>
> The skill also bundles ready-to-copy templates for `mkdocs.yml`, `pyproject.toml`, the GitHub Actions workflow, and a docs skeleton — see the skill's [`assets/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/mkdocs-site-bootstrap/assets) directory.

## Quick start

If your project doesn't yet use `mkdocs-site-bootstrap`, the easiest way to apply the same docs stack is to invoke the skill in your repo:

```
# From your project's repo root
bash <path-to-agent-skills>/skills/local/mkdocs-site-bootstrap/scripts/init-docs-site.sh \
  --site-name "My Project" \
  --repo-slug owner/repo \
  --site-url https://owner.github.io/repo/
```

Then enable GitHub Pages and trigger the first deploy:

```
bash <path-to-agent-skills>/skills/local/mkdocs-site-bootstrap/scripts/enable-pages.sh \
  --repo owner/repo
```

Build the deployable artifact with the scaffolded strict helper:

```
uv sync --extra docs
uv run python scripts/build-docs-site.py
```

For multilingual sites with llmstxt this keeps the root files default-language-only and builds locale HTML in a separate strict pass. Direct `mkdocs build --strict` remains an HTML-only preview.

For details on what the stack actually includes (Material theme + mkdocs-llmstxt + mkdocs-copy-to-llm + pymdownx.snippets), the linking rules that strict mode enforces, and how the GitHub Actions workflow is wired, read the canonical reference linked above.

Existing users should note that updating the installed skill does not migrate their project. If an older i18n site has empty or wrong-locale llms output, use the audit-first [`migration guide`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/i18n-llmstxt-migration.md).

## See also

- [Skill page: mkdocs-site-bootstrap](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md) — detailed walkthrough of the full skill workflow including consent gates, preferences, and existing-docs handling.
- [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/#documentation) — repo-specific rules that apply to *this* repo's `docs/` tree.

# Git workflow best practices

A concept-level explainer for the conventions the [`git-workflow`](https://daviddwlee84.github.io/agent-skills/skills/git-workflow/index.md) skill encodes. Read this for the *why* — it's usable on its own as a primer, independent of the skill's scripts. Everything here favors a **clean, linear, reviewable history** and habits that scale from solo work to a team.

## Table of contents

1. [Commit messages: Conventional Commits](#commit-messages-conventional-commits)
1. [Agentic commit provenance](#agentic-commit-provenance)
1. [Commit signing](#commit-signing)
1. [Semantic Versioning](#semantic-versioning)
1. [Choosing a workflow by project scale](#choosing-a-workflow-by-project-scale)
1. [Rebase, fast-forward, and squash](#rebase-fast-forward-and-squash)
1. [Branch naming](#branch-naming)
1. [Worktrees for parallel work](#worktrees-for-parallel-work)
1. [Forge CLIs: gh and glab](#forge-clis-gh-and-glab)
1. [Tag-driven versioning for packages](#tag-driven-versioning-for-packages)
1. [Sources](#sources)

______________________________________________________________________

## Commit messages: Conventional Commits

A commit message is documentation *and* an API for tooling. The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) convention gives each commit a machine-readable prefix:

```
<type>(<optional scope>): <subject>
```

Common types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. The subject is a short **imperative** phrase ("add retry", not "added retry"), lowercase, no trailing period, ideally ≤ 72 characters. A `!` (or a `BREAKING CHANGE:` footer) marks an incompatible change.

Why bother when working solo? Because the log becomes a changelog you can generate, a version bump you can compute, and a history you can `git log --grep 'feat'` months later. Write commits in **English** even when you think and prompt in another language — the object graph is read by tools and future collaborators.

## Agentic commit provenance

Agentic coding adds several signals that are easy to conflate. Keep them as separate layers:

| Layer                      | What it means                                                             |
| -------------------------- | ------------------------------------------------------------------------- |
| Git author / committer     | The human or service identity that created the commit object.             |
| `Co-Authored-By`           | Message attribution recognized by hosting UIs; not a signature.           |
| `AI-Assisted-By`           | This workflow's portable harness + model provenance.                      |
| Transcript / plan trailers | Repo-relative links to the detailed review trail committed with the diff. |
| SSH/GPG signature          | Proof that a key signed the exact commit object.                          |

The portable contract is:

```
feat(scope): add concise imperative summary

Explain why the change was needed, the resulting behavior, and meaningful
validation. Agent-produced non-trivial commits always include this body.

AI-Assisted-By: Codex CLI (gpt-5.6-sol)
Agent-Transcript: .specstory/history/session.md
Agent-Plan: .claude/plans/plan.md
```

Repeat the trailers for multiple agents or artifacts. Keep paths repo-relative and include only files in the same commit. Tool-native attribution is additive, but the canonical fields stay in the **final trailer block**, which is the structure [`git interpret-trailers --parse`](https://git-scm.com/docs/git-interpret-trailers) can query.

### Harness behavior observed on 2026-08-27

| Harness     | Native behavior                                                                                                                                                                                    | Portable-workflow consequence                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code | Commit/PR attribution is a configurable runtime feature; its default commit attribution includes a Generated-with line and model-specific `Co-Authored-By`.                                        | Preserve it and append canonical `AI-Assisted-By` + artifact paths. Commit-body quality is a separate agent behavior.                         |
| Cursor      | AI commit-message generation uses the staged diff and repository history. Cursor also has line-level AI tracking; Cloud Agent commits are cryptographically signed with an HSM-backed Ed25519 key. | Do not call line attribution, a message trailer, and a Verified commit the same thing. Preserve native signals and add the portable trailers. |
| Codex CLI   | **Inference:** the official configuration reference reviewed on this date documents no commit-attribution setting.                                                                                 | Use the skill/helper contract instead of inventing an OpenAI co-author email. Re-check upstream docs before claiming this is permanent.       |

Sources: [Claude Code settings](https://code.claude.com/docs/en/settings), [Cursor AI commit messages](https://docs.cursor.com/en/more/ai-commit-message), [Cursor analytics](https://cursor.com/docs/account/teams/analytics), [Cursor Cloud security](https://cursor.com/docs/cloud-agent/security), and the [Codex configuration reference](https://developers.openai.com/codex/config-reference/).

Squash merges create a new commit. Copy the canonical provenance into the squash message; neither the source commit hash nor its signature survives. Likewise, do not amend a vendor-signed cloud-agent commit solely to add metadata—the amended commit is a different object.

## Commit signing

Signing is optional and user-owned. This skill never silently changes global Git or agent settings. When the user explicitly asks for SSH signing, inspect their existing config and available public keys, confirm key + scope, then use:

```
git config gpg.format ssh
git config user.signingkey /path/to/public-key.pub
git config commit.gpgsign true
git config tag.gpgsign true       # optional, for signed release tags
```

With SSH signing, Git accepts a public-key path when the matching private key is available through `ssh-agent`; see [`user.signingKey`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-usersigningKey). The signature authenticates the configured key, while `AI-Assisted-By` records the coding harness/model. One does not replace the other.

## Semantic Versioning

[SemVer](https://semver.org/) numbers releases `MAJOR.MINOR.PATCH`:

- **MAJOR** — incompatible/breaking changes.
- **MINOR** — new, backward-compatible features.
- **PATCH** — backward-compatible bug fixes.

This maps cleanly onto Conventional Commits: `fix:` → PATCH, `feat:` → MINOR, anything breaking → MAJOR. Below `1.0.0`, anything may change; `1.0.0` is the promise of a stable public interface.

## Choosing a workflow by project scale

The biggest mistake is applying team ceremony to a solo repo (friction with no benefit) or applying solo habits to a shared repo (collisions, un-reviewable history). Match the workflow to real needs:

- **Tier 1 — solo / early.** One `main`. Commit directly, keep history linear with `git pull --rebase`, land the occasional short-lived branch with `git merge --ff-only`. No PRs. Tag when a state is worth returning to.
- **Tier 2 — prod/dev split.** `main` is the released/deployed line; `dev` is where features integrate. Promote `dev` → `main` at a release boundary. Adopt this when something (a deploy, a teammate) depends on a stable line while you keep working.
- **Tier 3 — team / grown vibe-coding.** `main` is always deployable; all work happens on short-lived branches merged via **pull request** after review and CI. This is [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow). Even a solo project benefits: the PR is a "ship a feature" boundary, a CI trigger, and a revert point.

You can skip tiers — a solo project with heavy CI may start at Tier 3.

## Rebase, fast-forward, and squash

Three operations shape history:

- **`git pull --rebase`** replays your local commits *on top of* the fetched upstream instead of making a merge commit, keeping history linear. Set it as the default: `git config pull.rebase true`.
- **Fast-forward merge** (`git merge --ff-only`) moves the branch pointer forward with no merge commit — possible only when there's nothing to reconcile. `git config merge.ff only` makes git *refuse* a merge that would create a merge commit, which surfaces divergence instead of hiding it.
- **Squash merge** collapses a branch's commits into a single commit on the target. Ideal for "vibe-coding" branches full of work-in-progress noise: the mainline gets one clean `feat: …` commit. The trade-off is that the branch's individual commits don't appear on `main` — so the branch shows as `gone` rather than `merged` afterward (see [branch hygiene](#branch-naming)).

Rule of thumb: linear locally with fast-forward; squash noisy PRs; rebase-merge PRs whose every commit already means something.

## Branch naming

A `<prefix>/<kebab-description>` convention makes branches sort by intent and lets you clean them up in bulk:

- `feat/…`, `fix/…`, `chore/…`, `docs/…`, `refactor/…`, `exp/…` for human-authored work (optionally with an issue number: `feat/123-oauth`).
- `agent/…` as a distinct namespace for agent / vibe-coding branches, so machine-generated work is visually separate and separately disposable.
- `worktree-*` is what Claude Code auto-creates for worktrees.

Keeping these namespaces apart is what makes cleanup (`git branch --list 'agent/*'`) safe rather than nerve-wracking. After a PR merges, prune with `git fetch --prune`; a branch whose upstream is `gone` (`git branch -vv`) is usually done — but confirm it has no unpushed commits before deleting, because work sometimes continues on a branch after its PR merged.

## Worktrees for parallel work

A [git worktree](https://git-scm.com/docs/git-worktree) is a second working directory attached to the same repository, on its own branch. Running each parallel agent or task in its own worktree means their file edits never collide. Claude Code integrates this directly ([docs](https://code.claude.com/docs/en/worktrees)):

- `claude --worktree <name>` creates `.claude/worktrees/worktree-<name>/` on a new branch, based on `origin/HEAD` by default.
- A worktree is a *fresh* checkout, so gitignored files (like `.env`) aren't present. A `.worktreeinclude` file at the repo root copies them in — using `.gitignore` syntax, and copying **only files that are themselves gitignored**. Already-tracked files (a committed `.vscode/settings.json`) are in the checkout already and should not be listed.
- Add `.claude/worktrees/` to `.gitignore` so worktree contents don't show as untracked in the main checkout.

## Forge CLIs: gh and glab

Drive pull/merge requests from the terminal with the platform CLI — [`gh`](https://cli.github.com/) for GitHub, [`glab`](https://gitlab.com/gitlab-org/cli) for GitLab:

```
gh pr create --fill                     # glab mr create --fill
gh pr checks                            # watch CI
gh pr merge --squash --delete-branch    # glab mr merge --squash --remove-source-branch
```

They keep you out of the browser for the common path and make PR state scriptable. Treat them as recommended conveniences, not hard dependencies — a good workflow still functions with plain `git` if a CLI is missing.

## Tag-driven versioning for packages

When a repository *is* a package, don't maintain the version string in three places (`__init__.py`, `pyproject.toml`, and a git tag) and let them drift. Make the **git tag the single source of truth**. For Python, the [Packaging guide](https://packaging.python.org/en/latest/discussions/single-source-version/) recommends deriving the version from the VCS:

- **setuptools** backend → [setuptools-scm](https://setuptools-scm.readthedocs.io/).
- **Hatch / hatchling** backend → [hatch-vcs](https://pypi.org/project/hatch-vcs/).

Tag as `vX.Y.Z` (PEP 440-compatible once the `v` is stripped), push the tag, and the build stamps the matching version. The release process becomes: land the release commit → `git tag -a vX.Y.Z` → push the tag.

## Sources

- [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
- [git-interpret-trailers](https://git-scm.com/docs/git-interpret-trailers)
- [git-config signing keys](https://git-scm.com/docs/git-config#Documentation/git-config.txt-usersigningKey)
- [Semantic Versioning 2.0.0](https://semver.org/)
- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
- [Claude Code worktrees](https://code.claude.com/docs/en/worktrees)
- [git-worktree docs](https://git-scm.com/docs/git-worktree)
- [Python Packaging — single-sourcing the version](https://packaging.python.org/en/latest/discussions/single-source-version/)
- [setuptools-scm](https://setuptools-scm.readthedocs.io/) · [hatch-vcs](https://pypi.org/project/hatch-vcs/)

# Karpathy's LLM Wiki pattern

A reference summary of the **personal knowledge base maintained by an LLM** pattern, as articulated by Andrej Karpathy in late 2025. This page is documentation, not a skill — it captures the idea so we can decide later whether to vendor an existing implementation (e.g. `obsidian-second-brain`) or author a local skill of our own.

## Sources

- [`gist.github.com/karpathy/442a6bf555914893e9891c11519de94f`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — the long-form "LLM Wiki" pattern document, written to be copy-pasted into your own LLM agent so it can co-design the specifics with you.
- [`x.com/karpathy/status/2039805659525644595`](https://x.com/karpathy/status/2039805659525644595) — the original announcement tweet ("LLM Knowledge Bases"), which is the ~1-page version of the gist and the seed of the broader pattern.

## TL;DR

The wiki is a **persistent, compounding artifact**. RAG re-derives knowledge from raw sources on every query; an LLM Wiki *compiles* that knowledge once into structured markdown and *keeps it current* as new sources arrive.

> Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase. — Karpathy, [LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

## The original tweet (verbatim)

> **LLM Knowledge Bases**
>
> Something I'm finding very useful recently: using LLMs to build personal knowledge bases for various topics of research interest. In this way, a large fraction of my recent token throughput is going less into manipulating code, and more into manipulating knowledge (stored as markdown and images). The latest LLMs are quite good at it. So:
>
> **Data ingest:** I index source documents (articles, papers, repos, datasets, images, etc.) into a `raw/` directory, then I use an LLM to incrementally "compile" a wiki, which is just a collection of `.md` files in a directory structure. The wiki includes summaries of all the data in `raw/`, backlinks, and then it categorizes data into concepts, writes articles for them, and links them all. To convert web articles into `.md` files I like to use the Obsidian Web Clipper extension, and then I also use a hotkey to download all the related images to local so that my LLM can easily reference them.
>
> **IDE:** I use Obsidian as the IDE "frontend" where I can view the raw data, the compiled wiki, and the derived visualizations. Important to note that the LLM writes and maintains all of the data of the wiki, I rarely touch it directly. I've played with a few Obsidian plugins to render and view data in other ways (e.g. Marp for slides).
>
> **Q&A:** Where things get interesting is that once your wiki is big enough (e.g. mine on some recent research is ~100 articles and ~400K words), you can ask your LLM agent all kinds of complex questions against the wiki, and it will go off, research the answers, etc. I thought I had to reach for fancy RAG, but the LLM has been pretty good about auto-maintaining index files and brief summaries of all the documents and it reads all the important related data fairly easily at this ~small scale.
>
> **Output:** Instead of getting answers in text/terminal, I like to have it render markdown files for me, or slide shows (Marp format), or matplotlib images, all of which I then view again in Obsidian. You can imagine many other visual output formats depending on the query. Often, I end up "filing" the outputs back into the wiki to enhance it for further queries. So my own explorations and queries always "add up" in the knowledge base.
>
> **Linting:** I've run some LLM "health checks" over the wiki to e.g. find inconsistent data, impute missing data (with web searchers), find interesting connections for new article candidates, etc., to incrementally clean up the wiki and enhance its overall data integrity. The LLMs are quite good at suggesting further questions to ask and look into.
>
> **Extra tools:** I find myself developing additional tools to process the data, e.g. I vibe coded a small and naive search engine over the wiki, which I both use directly (in a web ui), but more often I want to hand it off to an LLM via CLI as a tool for larger queries.
>
> **Further explorations:** As the repo grows, the natural desire is to also think about synthetic data generation + finetuning to have your LLM "know" the data in its weights instead of just context windows.
>
> **TL;DR:** raw data from a given number of sources is collected, then compiled by an LLM into a `.md` wiki, then operated on by various CLIs by the LLM to do Q&A and to incrementally enhance the wiki, and all of it viewable in Obsidian. You rarely ever write or edit the wiki manually, it's the domain of the LLM. I think there is room here for an incredible new product instead of a hacky collection of scripts.

## Architecture

Three layers, from the gist:

1. **Raw sources** — your curated source documents (articles, papers, images, datasets). **Immutable** — the LLM reads but never modifies them. This is your source of truth.
1. **The wiki** — a directory of LLM-generated markdown (summaries, entity pages, concept pages, comparisons, an overview, a synthesis). The LLM owns this layer entirely; you read it, the LLM writes it.
1. **The schema** — a `CLAUDE.md` / `AGENTS.md` that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow. You and the LLM co-evolve this over time.

## Operations

| Operation  | What it does                                                                                                                                                                                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ingest** | Drop a new source into `raw/`. The LLM reads it, summarizes, files it under the right entity/concept pages, updates the index, appends to the log. A single source might touch 10–15 pages.                                 |
| **Query**  | Ask a question. The LLM reads the index, drills into relevant pages, and answers — as markdown, a comparison table, a Marp deck, a matplotlib chart. **File the good answers back into the wiki** so explorations compound. |
| **Lint**   | Periodic health check. Find contradictions, stale claims, orphan pages, missing cross-references, data gaps. Suggests new questions to investigate and new sources to look for.                                             |

## Two special files

- **`index.md`** — content-oriented catalog. Every page listed with a link and one-line summary, organized by category. The LLM updates it on every ingest and reads it first when answering a query. At ~100 sources / a few hundred pages this works without embedding-based RAG.
- **`log.md`** — chronological, append-only. Use a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`) so the log becomes greppable: `grep "^## \[" log.md | tail -5`.

## Why this works

Maintenance — not reading or thinking — is what kills personal wikis. Updating cross-references, keeping summaries current, noting contradictions across dozens of pages: humans give up because the burden grows faster than the value. LLMs don't get bored, don't forget a back-link, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.

The pattern is, in spirit, Vannevar Bush's [Memex](https://en.wikipedia.org/wiki/Memex) (1945) — a private, curated knowledge store with associative trails. The part Bush couldn't solve was *who does the maintenance*. The LLM does.

## Ecosystem

Implementations and adjacent tools that have grown around this pattern:

- **[`eugeniughelbur/obsidian-second-brain`](https://github.com/eugeniughelbur/obsidian-second-brain)** — a Claude Code skill (not an Obsidian plugin) that pushes the pattern further: 31 slash commands + scheduled agents + Python scripts. Adds AI-first conventions (machine-readable preambles, bi-temporal facts, a "Two-Output Rule" where every answer also updates relevant pages), vault-first research that scans existing notes before going to the web, and `_CLAUDE.md` / `index.md` / `log.md` / `SOUL.md` / `CRITICAL_FACTS.md` (≈120 tokens always loaded) at the vault root. *"If Karpathy's wiki is a knowledge base you maintain with an LLM, this is a knowledge base that maintains itself."*
- **[`tobi/qmd`](https://github.com/tobi/qmd)** — local search engine for markdown (hybrid BM25 + vector + LLM re-ranking, on-device). Has both a CLI for the LLM to shell out to and an MCP server. Mentioned by the gist as the natural upgrade path once the index file alone stops scaling.
- **Obsidian Web Clipper**, **Marp** (markdown-to-slides), **Dataview** (frontmatter queries) — the supporting tools the gist recommends.

## Relation to this repo

This repo's [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) is **task memory** — `TODO.md` + `backlog/` + `pitfalls/`, oriented around shipped/deferred work and past traps. Karpathy's LLM Wiki is **knowledge memory** — a curated, synthesized view of an external research area. The two are orthogonal and could coexist on the same project.

Possible follow-ups (not committed):

- Vendor `obsidian-second-brain` into `skills/vendor/` (license permitting), alongside `project-knowledge-harness` as a "two flavors of memory" pair.
- Author a minimal local `llm-wiki-bootstrap` skill — just the gist's three-layer architecture + `index.md` / `log.md` + `ingest` / `query` / `lint` commands, no Obsidian dependency.

If you want to track either, add a `P3` entry via [`scripts/add-todo.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/index.md).

# Matt Pocock's "Skills for Real Engineers"

[Matt Pocock](https://github.com/mattpocock) — the TypeScript educator behind [Total TypeScript](https://www.totaltypescript.com/) — publishes [`mattpocock/skills`](https://github.com/mattpocock/skills), a collection he describes as *"agent skills that I use every day to do real engineering — not vibe coding."* They are **small, composable, model-agnostic** markdown skills "based on decades of engineering experience."

The pitch is not "here is a big skill that does everything." It is a **flow**: each skill is one disciplined step, and the steps chain into a repeatable loop from a rough idea to reviewed, tested, committed code. His walkthrough video, [*"mattpocock/skills: Learn the whole flow, end-to-end"*](https://youtu.be/M6mYodf0dJM), is the best introduction to how the pieces fit together.

This page documents the slice of that collection we vendor into the [`engineering-fundamentals`](https://daviddwlee84.github.io/agent-skills/skills/index.md) series, the end-to-end flow it supports, and what we deliberately leave upstream.

## The end-to-end flow

The skills are designed to hand off to one another. The backbone runs **align → specify → slice → implement → review**, with a few disciplines (`grilling`, `domain-modeling`, `codebase-design`) supplying the shared vocabulary the other skills reuse, and `diagnosing-bugs` on the "something broke" branch.

```
flowchart TD
    G["grill-with-docs / grill-me<br/>align intent · write GLOSSARY.md + ADRs"]
    S["to-spec<br/>synthesize a spec (PRD)"]
    T["to-tickets / wayfinder<br/>tracer-bullet tickets + blocking edges"]
    TR["triage<br/>agent-ready briefs · ready-for-agent"]
    I["implement<br/>build the tickets"]
    TDD["tdd<br/>red-green-refactor at seams"]
    CR["code-review<br/>Standards + Spec axes"]
    IA["improve-codebase-architecture<br/>find deepening opportunities"]
    DB["diagnosing-bugs<br/>reproduce → minimise → fix"]

    G --> S --> T --> TR --> I
    I --> TDD
    I --> CR
    CR --> IA
    IA -. re-grill .-> G
    I -. when broken .-> DB

    GR(["grilling"]):::eng -. interview engine .-> G
    DM(["domain-modeling"]):::eng -. ubiquitous language .-> G
    CD(["codebase-design"]):::eng -. deep-module vocab .-> IA
    CD -. deep-module vocab .-> I

    classDef eng fill:#eef,stroke:#88a,stroke-dasharray:3 3;
```

The engineering payoff Matt targets, step by step:

- **Alignment first.** `grill-me` / `grill-with-docs` interview you until every branch of a decision is resolved, and capture the shared language in a `GLOSSARY.md` (formerly `CONTEXT.md`) + ADRs. `grilling` is the reusable interview loop behind both; `domain-modeling` maintains the ubiquitous language. This is what stops an agent from confidently building the wrong thing.
- **A durable spec, then slices.** `to-spec` turns the aligned conversation into a spec (you may know it as a PRD) on the issue tracker. `to-tickets` breaks it into **tracer-bullet vertical slices** — each a narrow-but-complete path through every layer, sized for one context window — with explicit **blocking edges**. `wayfinder` is the same idea scaled past a single agent session: a map of investigation tickets resolved one at a time.
- **Tight feedback loops.** `implement` drives `/tdd` (red-green-refactor at pre-agreed seams) and finishes with `/code-review` before committing. `code-review` runs two parallel sub-agents — **Standards** (does it follow the repo's documented conventions?) and **Spec** (does it match what the issue asked for?).
- **Design care over time.** `codebase-design` supplies the deep-module vocabulary (module, interface, depth, seam, adapter); `improve-codebase-architecture` scans for deepening opportunities and grills through the one you pick. `diagnosing-bugs` is the disciplined loop for when something is broken or slow.

## Why `mattpocock/skills` is installable here

The repo is **MIT-licensed** and the skills are plain [agentskills.io](https://agentskills.io/specification)-spec markdown, so they run in any compliant agent — Claude Code, Codex, OpenCode, Cursor, Gemini CLI. Matt's own `.claude` layout is just one host; vendoring the markdown into this repo is safe and portable.

## Skills we vendor (15, series `engineering-fundamentals`)

We vendor the whole core flow so it is **self-consistent** — every `/skill` cross-reference resolves within the series (the two exceptions are documented below). `disable-model-invocation: true` skills are **user-invoked** (you call them explicitly); the rest are **model-invoked** disciplines an agent reaches for when appropriate.

### Orchestrators (user-invoked)

| Skill                           | Upstream bucket         | What it does                                                                                                                                      |
| ------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grill-with-docs`               | `engineering/`          | Relentless interview that also writes ADRs + a glossary as you go.                                                                                |
| `to-spec`                       | `engineering/`          | Synthesize the current conversation into a spec/PRD and publish it — no interview.                                                                |
| `to-tickets`                    | `engineering/`          | Break a plan/spec into tracer-bullet tickets, each declaring its blocking edges.                                                                  |
| `wayfinder`                     | `engineering/`          | Plan work bigger than one agent session as a shared map of decision tickets, resolved one at a time.                                              |
| `implement`                     | `engineering/`          | Build the work from a spec or tickets, driving `/tdd` and finishing with `/code-review`.                                                          |
| `improve-codebase-architecture` | `engineering/`          | Scan for deepening opportunities, present a visual HTML report, then grill the one you pick.                                                      |
| `zoom-out`                      | `engineering/` (frozen) | Step back for broader, higher-level context on unfamiliar code. **Frozen** — deleted upstream in the 2026-07 reorg; we keep the last-synced copy. |

### Disciplines (model-invoked)

| Skill             | Upstream bucket | What it does                                                                                                                       |
| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `grilling`        | `productivity/` | The reusable interview loop that grills until every branch of a decision is resolved (engine behind `grill-with-docs`/`grill-me`). |
| `domain-modeling` | `engineering/`  | Build and sharpen the project's ubiquitous language; maintain the domain model + ADRs.                                             |
| `codebase-design` | `engineering/`  | Shared vocabulary for designing deep modules — module, interface, depth, seam, adapter.                                            |
| `tdd`             | `engineering/`  | Test-driven red-green-refactor loop at pre-agreed seams.                                                                           |
| `code-review`     | `engineering/`  | Two-axis review (Standards + Spec) run as parallel sub-agents against a fixed base point.                                          |
| `diagnosing-bugs` | `engineering/`  | Diagnosis loop for hard bugs and performance regressions (reproduce → minimise → hypothesise → fix → regression-test).             |
| `triage`          | `engineering/`  | Move issues and external PRs through a triage state machine, writing agent-ready briefs.                                           |
| `prototype`       | `engineering/`  | Build a throwaway prototype to answer a design question.                                                                           |

## Prerequisite: `/setup-matt-pocock-skills`

Several flow skills (`to-spec`, `to-tickets`, `triage`, `code-review`, `wayfinder`) expect an **issue tracker + triage-label vocabulary + docs location** to have been configured. Upstream that is done once per repo by the `setup-matt-pocock-skills` skill, which we do **not** vendor — it is an opinionated repo bootstrap (it writes `docs/agents/issue-tracker.md`, label mappings, etc.). The dependency is **soft**: each skill says *"run `/setup-matt-pocock-skills` if not provided"* and otherwise **defaults to a local-markdown tracker**, so the flow still works without it. To adopt the full tracker-backed workflow, install and run `setup-matt-pocock-skills` from upstream (see [Install](#install)). It is the top candidate in the [remaining-skills TODO](#upstream-skills-we-dont-vendor-yet).

## Upstream skills we don't vendor (yet)

`mattpocock/skills` is far larger than the core flow. We cherry-pick per the repo's [vendoring policy](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/#vendoring-policy) and leave the rest for manual install. Two vendored skills still reference an un-vendored skill, by design:

- **`wayfinder` → `/research`** — `wayfinder` fires `/research` sub-agents to resolve investigation tickets. We ship the [`deep-research`](https://daviddwlee84.github.io/agent-skills/skills/index.md) skill (a different upstream) which can play that role, and `research` itself is a [TODO](#upstream-skills-we-dont-vendor-yet) candidate.
- **flow → `/setup-matt-pocock-skills`** — soft, see [above](#prerequisite-setup-matt-pocock-skills).

Deliberately left upstream (tracked in [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md)):

| Upstream skill                                | Bucket          | Why not vendored                                                                                                        |
| --------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `setup-matt-pocock-skills`                    | `engineering/`  | Opinionated per-repo bootstrap; soft prereq documented above.                                                           |
| `ask-matt`                                    | `engineering/`  | Router over Matt's own skill set — redundant once you know the flow.                                                    |
| `research`                                    | `engineering/`  | Overlaps the vendored `deep-research`; evaluate before adding.                                                          |
| `resolving-merge-conflicts`                   | `engineering/`  | Candidate; overlaps the local `git-workflow` scope.                                                                     |
| `grill-me`                                    | `productivity/` | User-facing wrapper of `grilling` (which we vendor).                                                                    |
| `handoff`, `teach`                            | `productivity/` | Niche productivity workflows, not part of the build loop.                                                               |
| `writing-great-skills`                        | `productivity/` | Duplicates the local [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md).        |
| `misc/*`                                      | `misc/`         | `git-guardrails-claude-code`, `setup-pre-commit`, `migrate-to-shoehorn`, `scaffold-exercises` — narrow / host-specific. |
| `deprecated/*`, `in-progress/*`, `personal/*` | —               | Upstream marks these unstable or personal; skipped wholesale.                                                           |

## The 2026-07 reorg

Our first sync (2026-07-05) tracked a flat `skills/engineering/` layout. Matt has since restructured into `engineering/`, `productivity/`, `misc/`, `deprecated/`, `in-progress/`, and `personal/` buckets, which changed two of our entries and removed one. Our `vendor.yaml` bookkeeping records the lineage:

- `to-prd` → **`to-spec`** (`renamed_from: to-prd`) — PRD framing became "spec".
- `to-issues` → **`to-tickets`** (`renamed_from: to-issues`) — now tracer-bullet tickets.
- `zoom-out` — **deleted upstream**, kept locally via a `frozen:` block.
- `diagnose` → **`diagnosing-bugs`** (`renamed_from: diagnose`) — from the earlier reorg.

Renaming changes the **downstream install id** (`npx skills` has no lockfile), so `renamed_from:` is how we keep the history greppable. See [Adding vendor skills → renamed/removed upstream](https://daviddwlee84.github.io/agent-skills/workflows/adding-vendor-skills/index.md) and `CLAUDE.md`.

`code-review` name overlap

We vendor a skill named `code-review`. It is Matt's two-axis (Standards + Spec) review discipline — distinct from Claude Code's built-in `/code-review` command. Both can coexist; invoke the vendored one by its skill name.

## Install

```
# The 15-skill flow, via this repo (grouped as "engineering-fundamentals")
npx skills@latest add daviddwlee84/agent-skills

# The full upstream collection (all buckets), straight from Matt
npx skills@latest add mattpocock/skills
# …then run /setup-matt-pocock-skills once to wire up your issue tracker.

# Or as a Claude Code plugin (managed, read-only, auto-updating)
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock
```

The `npx skills` install copies editable markdown into your project (hack away); the plugin install is a managed bundle that updates when Matt ships new versions.

## See also

- [External skill collections](https://daviddwlee84.github.io/agent-skills/catalog/skill-collections/#general-purpose-collections) — the catalog row for `mattpocock/skills` links back here.
- [Agent Harness domain hub](https://daviddwlee84.github.io/agent-skills/catalog/domains/agent-harness/index.md) — where spec-driven flows and harnesses are surveyed.
- [Warp Oz skills](https://daviddwlee84.github.io/agent-skills/reference/warp-oz-skills/index.md) — its GitHub-specific `triage`/PR skills complement Matt's more general-purpose `triage`.
- [Deep Research landscape](https://daviddwlee84.github.io/agent-skills/reference/deep-research-landscape/index.md) — the `deep-research` skill that can stand in for `wayfinder`'s `/research` sub-agents.

# MkDocs 2.0, Zensical, and the `mkdocs<2` cap

> This page is now maintained as part of the `mkdocs-site-bootstrap` skill.
>
> The full rationale and re-evaluation criteria live in the skill's reference file: [`skills/local/mkdocs-site-bootstrap/references/mkdocs-2-and-zensical.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/mkdocs-2-and-zensical.md)

## Why this exists

This repo's [`pyproject.toml`](https://github.com/daviddwlee84/agent-skills/blob/main/pyproject.toml) caps `mkdocs<2` and `mkdocs-material<10`. So does the `pyproject.toml.template` that `mkdocs-site-bootstrap` writes into downstream projects. That cap is deliberate, not bit-rot.

In one paragraph: MkDocs 2.0 removes the entire plugin system, so every plugin in this docs stack (`mkdocs-llmstxt`, `mkdocs-static-i18n`, `mkdocs-copy-to-llm`) stops working under 2.x. The Material for MkDocs team has refused to follow MkDocs 2.0 and is shipping a separate replacement called Zensical, positioned as a drop-in for **1.x**, not 2.0. Until Zensical reaches stable release with i18n + LLM-friendly output, the realistic answer is "stay on MkDocs 1.x." The canonical reference linked above documents the exact re-evaluation criteria.

## See also

- [Downstream docs stack recipe](https://daviddwlee84.github.io/agent-skills/reference/docs-stack-recipe/index.md) — full stack description (what the cap is protecting).
- [Skill page: mkdocs-site-bootstrap](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md) — the skill that owns the templates and references.

# How `npx skills` reads catalog metadata

This page captures the verified mechanism behind the grouped install UI of `npx skills@latest add ...`. Everything below was confirmed by reading the actual source of the npm package (`vercel-labs/skills`, [`src/plugin-manifest.ts`](https://github.com/vercel-labs/skills/blob/main/src/plugin-manifest.ts) and [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts)) and the official [Claude Code plugin-marketplaces docs](https://code.claude.com/docs/en/plugin-marketplaces).

## TL;DR for this repo

- The grouped picker UI you see when running `npx skills@latest add daviddwlee84/agent-skills/skills` is driven by `skills/.claude-plugin/marketplace.json` — **inside** the `skills/` directory, not at the repo root.
- Every group header is `kebabToTitle(plugins[].name)`. Skills not listed under any plugin fall through to the **Other** group.
- Edit the manifest by hand; run `make marketplace` (= `bash scripts/validate-marketplace.sh`) to catch broken paths, duplicates, or on-disk skills that would silently fall under "Other".
- We do **not** ship per-plugin `.claude-plugin/plugin.json` files: each marketplace entry is already a complete inline `strict: false` skill bundle.

## How the CLI resolves the manifest path

The user's argument to `npx skills add` is parsed into `repo` + optional `subpath`. For this repo:

```
npx skills@latest add daviddwlee84/agent-skills/skills
                       └────────── repo ──────────┘ └sub┘
```

Inside the CLI ([`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts)):

```
const searchPath = subpath ? join(basePath, subpath) : basePath;
// ...
const pluginGroupings = await getPluginGroupings(searchPath);
```

So when the install command **includes** a subpath, the CLI reads the catalog from `<repo>/<subpath>/.claude-plugin/marketplace.json`.

| Invocation                                        | Where the CLI looks for the manifest              |
| ------------------------------------------------- | ------------------------------------------------- |
| `npx skills add anthropics/skills`                | `<repo>/.claude-plugin/marketplace.json`          |
| `npx skills add daviddwlee84/agent-skills/skills` | `<repo>/skills/.claude-plugin/marketplace.json`   |
| `npx skills add foo/bar/some/dir`                 | `<repo>/some/dir/.claude-plugin/marketplace.json` |

This repo uses the second form because the `skills/local/` and `skills/vendor/` trees live under `skills/`, not at the repo root.

Common pitfall

Putting `.claude-plugin/marketplace.json` at the repo root and then invoking the CLI with a subpath silently disables grouping — the file at the root is never read, and every skill ends up in **Other**. Match the manifest's location to the install command's subpath.

## Reusing the nested manifest with Claude Code and Codex

The same file is consumed by three installers, but each chooses its marketplace root independently:

| Consumer                                          | Marketplace root                     |
| ------------------------------------------------- | ------------------------------------ |
| `npx skills add daviddwlee84/agent-skills/skills` | the requested `skills/` subpath      |
| `claude plugin marketplace add owner/repo`        | the cloned repository root           |
| `claude plugin marketplace add ./local/path`      | the local path passed to the command |
| `codex plugin marketplace add ./local/path`       | the local path passed to the command |

A local checkout therefore provides zero-duplication native routes for both plugin CLIs:

```
git clone https://github.com/daviddwlee84/agent-skills.git

claude plugin marketplace add ./agent-skills/skills
claude plugin install version-control@daviddwlee84-skills

codex plugin marketplace add ./agent-skills/skills
codex plugin add version-control@daviddwlee84-skills
```

Verified with Claude Code 2.1.235 and Codex 0.147.0. Codex reads the inline Claude-format marketplace entry and generates a `.codex-plugin/plugin.json` adapter in its install cache with only that category's explicit `skills[]`. There is no second source manifest to maintain.

The bare repository root does not contain a supported marketplace manifest, so pass its `skills/` directory. The Claude GitHub shorthand `claude plugin marketplace add daviddwlee84/agent-skills` consequently fails. A direct URL to the nested JSON is not an equivalent Claude workaround: URL marketplaces fetch the catalog file without the adjacent repository tree, so relative `source: "./"` and skill paths have no installable source beside them.

Both native routes install a category plugin, while `npx skills` can install one selected skill across agents. `make native-marketplace-smoke` exercises both local native paths in temporary configuration state and verifies that the runtime adapter preserves category boundaries.

## Manifest shape

Reference: official [marketplace manifest schema](https://code.claude.com/docs/en/plugin-marketplaces).

```
{
  "name": "<unique-marketplace-id>",
  "owner": { "name": "...", "email": "..." },
  "metadata": {
    "description": "...",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "<group-name-kebab-case>",
      "description": "Short description of the plugin / category",
      "category": "<for Claude Code /plugin UI>",
      "tags": ["...", "..."],
      "source": "./",
      "strict": false,
      "skills": [
        "./relative/path/to/skill-dir",
        "./another/skill-dir"
      ]
    }
  ]
}
```

What the `npx skills` picker actually consumes:

| Field                                                                | Used by `npx skills`?                                                        | Used by Claude Code `/plugin` UI? |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------- |
| `metadata.pluginRoot`                                                | yes (resolves `source`)                                                      | yes                               |
| `plugins[].name`                                                     | **yes — drives the group header label**                                      | yes                               |
| `plugins[].source`                                                   | yes (must be a string starting with `./`; object/remote sources are skipped) | yes                               |
| `plugins[].skills[]`                                                 | yes (must start with `./`)                                                   | yes                               |
| `plugins[].description` / `category` / `tags` / `version` / `strict` | **no — pass through**                                                        | yes                               |

So `category` and `tags` are essentially free metadata for now: they cost nothing to include in the manifest, and any future native consumer (Claude Code's `/plugin` browser, downstream catalog tooling) can use them without us migrating the file.

### What the picker actually shows for a skill row

Per [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) (the `groupMultiselect` call), each skill row is constructed as:

```
{
  value: s,
  label: getSkillDisplayName(s),        // = s.name (SKILL.md frontmatter)
  hint:  s.description.slice(0, 57)+'…' // = SKILL.md description, truncated to 60 chars
}
```

So the **only** thing the user sees per skill is `name` + truncated `description` from that skill's SKILL.md. **Nothing in `marketplace.json` is shown per-skill** — not `plugins[].description`, not `category`, not `tags`, not anything. The plugin's `name` only ever appears as the group header above the skill rows.

This means: if you want to annotate / re-label / "tag as deprecated" / override the description for a single skill in the picker, the SKILL.md itself is the only knob. There is no "external annotation" mechanism in the catalog manifest.

## Group header rendering — `kebabToTitle`

The picker turns each plugin `name` into a header label by splitting on hyphens and titlecasing each token. So:

| `plugins[].name`   | UI header        |
| ------------------ | ---------------- |
| `document-skills`  | Document Skills  |
| `claude-api`       | Claude Api       |
| `ml-workflow`      | Ml Workflow      |
| `fullstack-nextjs` | Fullstack Nextjs |
| `notebooks`        | Notebooks        |

Pick names that titlecase legibly. `claude-api` → "Claude Api" is the official upstream choice and ships in the user-facing UI of `anthropics/skills`, so awkward casing is a known quirk; do not work around it with weird name fields.

## Ordering in the picker (alphabetical-only)

The picker sorts **purely alphabetically** — the order of the `plugins[]` array in `marketplace.json`, and of each group's `skills[]` array, is **ignored**. Confirmed in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) (the interactive `groupMultiselect` path, ~L1298):

```
const sortedSkills = [...skills].sort((a, b) => {
  if (a.pluginName && b.pluginName && a.pluginName !== b.pluginName)
    return a.pluginName.localeCompare(b.pluginName);          // ① group name, A→Z
  return getSkillDisplayName(a).localeCompare(getSkillDisplayName(b)); // ② skill name, A→Z
});
```

The non-interactive list / summary / results paths sort the same way via `Object.keys(grouped).sort()`. So there are two sort keys, both alphabetical and neither array-driven:

1. **Group order** — `plugins[].name` (kebab), A→Z.
1. **Within a group** — each skill's `SKILL.md` `name`, A→Z.

### The only lever: rename the group so it sorts earlier

Because the sort key is the group `name` string itself, the sole way to move a group up is to make its name sort earlier. `localeCompare` orders digits before letters, so a two-digit `NN-` prefix pins a group to the top in an explicit order (the prefix shows in the header via `kebabToTitle` — the accepted trade-off):

| `plugins[].name`     | picker header        | position                    |
| -------------------- | -------------------- | --------------------------- |
| `01-project-memory`  | `01 Project Memory`  | 1st                         |
| `02-skill-authoring` | `02 Skill Authoring` | 2nd                         |
| `03-infra-and-docs`  | `03 Infra And Docs`  | 3rd                         |
| `04-ml-workflow`     | `04 Ml Workflow`     | 4th                         |
| `05-notebooks`       | `05 Notebooks`       | 5th                         |
| *(everything else)*  | *(kebabToTitle)*     | A→Z, after all `NN-` groups |

The `NN-` prefixes are intentional, not typos

Stripping a prefix drops that group back to its A→Z position. This repo pins its frequently-used groups this way; the rest stay alphabetical. Re-run `make marketplace` after any rename.

**Within-group order is not controllable** without renaming the skills themselves — and the `SKILL.md` `name` is load-bearing (it's the install id), so don't. Example: under `02 Skill Authoring` the rows render `mcp-builder → skill-author → skill-creator` regardless of the `skills[]` array order.

## "Other" — the auto-fallback group

Any SKILL.md the CLI discovers under the search root that is **not** listed in any `plugins[].skills[]` entry shows up under the **Other** group header. This is how `anthropics/skills`'s `template-skill` ends up under "Other" — it's not listed in their manifest's `plugins[]`.

Use this to your advantage: a skill that doesn't fit any category yet can simply be omitted from `marketplace.json` and it will still install, just under "Other". Our `make marketplace` validator emits a warning (not an error) for unlisted on-disk skills so they're easy to notice.

## Path resolution rules (gotchas)

- `source: "./..."` and `skills[]: "./..."` are **relative to the marketplace root** (the directory containing `.claude-plugin/`), not relative to the JSON file itself or the `.claude-plugin/` dir.
- The CLI rejects any path that does not start with `./` — `../` and absolute paths are not allowed (path-traversal protection in [`isContainedIn`](https://github.com/vercel-labs/skills/blob/main/src/plugin-manifest.ts)).
- `metadata.pluginRoot` (optional) is prepended to every plugin's `source`. We don't use it; we set `source: "./"` per plugin so each plugin path resolves directly under the manifest root (`skills/`).

## Reserved marketplace `name`s

These cannot be used as the `name` field, per official docs:

- `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`
- `anthropic-marketplace`, `anthropic-plugins`
- `agent-skills`
- `knowledge-work-plugins`, `life-sciences`
- Any name that impersonates an official marketplace (e.g. `official-claude-plugins`, `anthropic-tools-v2`)

This repo's manifest uses **`daviddwlee84-skills`** — the GitHub repo folder is still allowed to be `agent-skills`; only the `name` field inside the manifest is restricted. The validator script enforces this.

## Versioning

Top-level `metadata.version` describes the marketplace catalog; it does not pin these inline plugins. Claude Code 2.1.235 resolves plugin version identity from `plugin.json`, then an individual `plugins[].version`, then the git source SHA. These entries define neither of the first two, so an isolated update test advanced the installed SHA and content after a new commit even while `metadata.version` stayed at `"1.0.0"`; omitting the field behaved the same.

This repository therefore keeps `metadata.version: "1.0.0"` as catalog metadata, not as a release gate. A git-backed install still needs its normal refresh sequence: fetch the new source (for the documented local checkout, `git pull`), run `claude plugin marketplace update daviddwlee84-skills`, then `claude plugin update <plugin>@daviddwlee84-skills`. The `npx skills` grouping path ignores this field.

## `marketplace.json` vs `plugin.json`

| File                                  | Purpose                                     | When to use                                                           |
| ------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
| `.claude-plugin/marketplace.json`     | Catalog of one or more plugins / categories | A repository that users register as a marketplace                     |
| `<plugin>/.claude-plugin/plugin.json` | Manifest for one plugin                     | Conventional strict marketplace plugins that own their component tree |

The two files are not redundant, but a marketplace entry may define a manifest-less bundle inline. This repository does exactly that: every entry sets `strict: false`, points `source` at the shared `skills/` root, and explicitly lists its skill directories. Adding a set of near-empty `plugin.json` files would not make discovery more correct; it would only create another identity/version surface to keep synchronized.

## Cross-agent portability

`npx skills` is a one-way installer: it reads the manifest, then copies SKILL.md files into each target agent's native skills directory (supported targets enumerated in [`src/types.ts`](https://github.com/vercel-labs/skills/blob/main/src/types.ts)). Most other agents (OpenCode, Cursor, Aider, …) do **not** read `.claude-plugin/marketplace.json` natively; they have their own conventions (`.opencode/`, `AGENTS.md`, `.cursor/rules/`, etc.). Codex 0.147.0 is a verified exception: its plugin marketplace CLI accepts this manifest directly.

The resulting distribution paths are:

- One `marketplace.json` is enough for cross-agent **install** via `npx skills add`.
- The same file provides category-plugin installation through both Claude Code and Codex when `skills/` is passed as the local marketplace root.
- Standalone Codex skills installed under `.agents/skills/` continue to use its canonical shared discovery path; they do not require plugin packaging.

On `codex plugin add`, Codex copies the shared source and generates a cache-local `.codex-plugin/plugin.json` whose `skills[]` contains only the selected category. Do not commit a second manifest merely to reproduce that adapter. A source `.codex-plugin/plugin.json` remains relevant only if this repository later chooses to publish a standalone Codex-specific package with its richer interface metadata. Codex's public CLI does not install arbitrary `.plugin` or ZIP archives, so a packaging script would still need a named release/upload consumer.

## Hiding / deprecating a skill without deleting it

The CLI has a built-in hide mechanism via SKILL.md frontmatter — set `metadata.internal: true` and the skill becomes invisible in the picker while staying in the repo.

Per [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts):

```
const isInternal = data.metadata?.internal === true;
if (isInternal && !shouldInstallInternalSkills() && !options?.includeInternal) {
  return null;
}
```

```
---
name: my-deprecated-skill
description: ...
metadata:
  internal: true   # <- hides this skill from `npx skills add` picker UI
---
```

What this does:

- ✅ Skill stays in the repo, files unchanged.
- ✅ Hidden from the interactive picker by default.
- ✅ Still installable on direct request: `npx skills add <repo> my-deprecated-skill` passes `includeInternal: true` so the by-name lookup finds it.
- ✅ Power-user override: `INSTALL_INTERNAL_SKILLS=1 npx skills add ...` shows internal skills in the picker as well.
- ✅ Compatible with discovery elsewhere (Claude Code's auto-discovery, this repo's docs site) — `metadata.internal` is a `npx skills` convention only.

When marking a skill as internal, also **remove its path from `plugins[].skills[]`** in `marketplace.json` — otherwise you have a dead catalog entry pointing at a hidden skill. The two settings should not coexist for the same skill.

### Why not just delete it?

Reasons to use `metadata.internal` over deletion:

- Keep the docs page reachable (the skill still renders on the docs site).
- Preserve `vendor.yaml` history and `last_sync` dates for vendored skills.
- Allow opt-in installs by name during a deprecation grace period.
- Keep `git log` / `git blame` continuity for future debugging.

If you want it gone for good, delete the directory and remove the entry from `marketplace.json` and (for vendored skills) `vendor.yaml`.

### Validator coverage (today)

`scripts/validate-marketplace.sh` does **not** currently parse SKILL.md frontmatter, so it won't flag the "internal skill listed in `marketplace.json`" mistake. If we hit this in practice, the validator can be extended to:

1. Parse each SKILL.md's frontmatter (e.g. via `yq` or python-frontmatter).
1. Error if any path listed in `plugins[].skills[]` resolves to a skill with `metadata.internal: true`.
1. Skip the "falls under Other" warning for internal skills (they wouldn't show up in the picker at all, so the warning is misleading).

This is a deferred enhancement — see TODO if/when it becomes worth it.

## Working with the manifest in this repo

```
# Validate the manifest (parses, name not reserved, all paths exist,
# no duplicates, on-disk skills covered).
make marketplace

# Or run the script directly with verbose output.
bash scripts/validate-marketplace.sh

# Exercise native Claude + Codex add/list/install in temporary config state.
make native-marketplace-smoke
```

After adding a new local or vendored skill:

1. Place the SKILL.md as usual under `skills/local/<name>/` or `skills/vendor/<name>/`.
1. Open `skills/.claude-plugin/marketplace.json` and add the new path (relative to `skills/`) to the appropriate plugin's `skills[]` array, **or** intentionally leave it out so it falls under "Other".
1. Run `make marketplace`. It will warn for unlisted skills and error for broken paths.

## Source references

- `npx skills` package source: [vercel-labs/skills](https://github.com/vercel-labs/skills) on GitHub, npm package [`skills`](https://www.npmjs.com/package/skills).
- Manifest read logic: [`src/plugin-manifest.ts`](https://github.com/vercel-labs/skills/blob/main/src/plugin-manifest.ts).
- Subpath + searchPath logic: [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts).
- Picker UI grouping: [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) (search for `groupMultiselect` and `kebabToTitle`).
- Official Claude Code docs: [plugin-marketplaces](https://code.claude.com/docs/en/plugin-marketplaces), [plugins-reference](https://code.claude.com/docs/en/plugins-reference).
- Reference manifest in this repo: [`skills/.claude-plugin/marketplace.json`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/.claude-plugin/marketplace.json).

# Pitfalls format

A `pitfalls/` directory captures non-obvious traps you've already debugged once, so the next agent (or future you) can grep the symptom and skip straight to the fix.

This page documents the format used by [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md). Same shape ships in any project that has run the skill's `init.sh`.

## File layout

```
pitfalls/
├── README.md                              # index + cross-reference table
├── <symptom-slug-1>.md                    # one trap per file
├── <symptom-slug-2>.md
└── …
```

The slug is the **symptom**, not the root cause. You search by what you see in the error, not by the explanation you eventually learned.

## Single pitfall doc — required sections

Each `pitfalls/<slug>.md` should answer four questions in this order:

1. **Symptom** — the verbatim error text or behavior. Copy-paste, don't paraphrase. Paraphrasing kills `grep`.
1. **Root cause** — the underlying mechanism, in one or two paragraphs.
1. **Workaround** — exact steps to recover. Code blocks where applicable.
1. **Prevention** — the invariant that, if applied, would have prevented the trap. If the prevention is severe enough (silent corruption, cross-machine recurrence), graduate it to a Hard invariant in `AGENTS.md` / `CLAUDE.md` and link both ways.

The full template lives at [`skills/local/project-knowledge-harness/assets/pitfall-doc.md.template`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/assets/pitfall-doc.md.template).

## Title / slug guidance

Write the title the way the search query would look:

| ✅ Symptom-first                        | ❌ Root-cause-first                    |
| --------------------------------------- | -------------------------------------- |
| `gh-api-404-on-tree-endpoint.md`        | `vendor-yaml-branch-handling.md`       |
| `npx-skills-empty-after-install.md`     | `skills-discovery-depth-fallback.md`   |
| `mkdocs-strict-fails-on-relative-md.md` | `mkdocs-link-validation-rules.md`      |
| `mkdocs-i18n-llms-files-are-empty.md`   | `mkdocs-plugin-lifecycle-collision.md` |

The agent reading the pitfall is asking *"is this what just happened to me?"* — the title needs to match the question, not the answer.

A current repository example is [`mkdocs-i18n-llms-files-are-empty.md`](https://github.com/daviddwlee84/agent-skills/blob/main/pitfalls/mkdocs-i18n-llms-files-are-empty.md): the visible symptom is nearly empty or wrong-locale llms output; the underlying plugin lifecycle collision belongs inside the document, not in its slug.

## When NOT to use `pitfalls/`

- **Project-specific bugs that are already fixed.** Use `git log` / CHANGELOG instead. Pitfalls are for traps that can recur.
- **Onboarding gaps.** That's documentation; put it in `docs/` or the README.
- **Generic "things to watch out for" lists.** Without a specific symptom, there's nothing to grep, so the pitfall doesn't earn its keep.

## Cross-referencing

`pitfalls/README.md` should keep a small table of pitfalls that live *outside* the directory — for example, a known trap explained inside a specific design doc. The table lets future agents grep the symptom keyword from one place even when the explanation lives elsewhere.

# Bundled scripts

Every script in this repo's [`scripts/`](https://github.com/daviddwlee84/agent-skills/tree/main/scripts) directory is also bundled inside the skill that owns it (so the package shipped via `npx skills` stays self-contained). The pair must stay byte-identical — see [Conventions](https://daviddwlee84.github.io/agent-skills/conventions/index.md).

Shell scripts are written in **Bash 3.2** so they run on stock macOS without homebrew bash. The MkDocs build helper is Python and runs inside the project's uv-managed docs environment.

## Vendor system

### `add-vendor.sh`

```
./scripts/add-vendor.sh owner/repo/path/to/skill
./scripts/add-vendor.sh https://github.com/owner/repo/tree/branch/path/to/skill
./scripts/add-vendor.sh --name custom --branch dev owner/repo/skills/some-skill
./scripts/add-vendor.sh --no-sync owner/repo/path/to/skill
```

Verifies the upstream path exists via `gh api`, deduplicates against existing entries in [`vendor.yaml`](https://github.com/daviddwlee84/agent-skills/blob/main/vendor.yaml), appends the new entry, and triggers `sync-vendor.sh` (skip with `--no-sync`).

**Dependencies:** `gh` (authenticated) and `yq`.

### `sync-vendor.sh`

```
./scripts/sync-vendor.sh           # download all vendored skills
./scripts/sync-vendor.sh --check   # dry-run: report which entries have new upstream commits
```

Iterates `vendor.yaml`, downloads each skill via the GitHub trees API, and updates `last_sync.{date,commit}` on success. `--check` prints what would change without writing.

## Project memory

These ship with [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md); the canonical copies live at [`skills/local/project-knowledge-harness/scripts/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/project-knowledge-harness/scripts).

### `todo-kanban.sh`

```
./scripts/todo-kanban.sh                    # default: TODO.md, Markdown board
./scripts/todo-kanban.sh path/to/TODO.md    # explicit file
./scripts/todo-kanban.sh --validate-only    # exit code only, no rendering
./scripts/todo-kanban.sh --json             # machine-readable lane summary
```

Validates the [TODO format](https://daviddwlee84.github.io/agent-skills/reference/todo-format/index.md) and renders a kanban-style board to stdout. Anything that's not a top-level `- [ ]` / `- ✅` item is ignored, so you can sprinkle prose under section headings.

Exit codes: `0` valid; `1` validation failure (line number printed to stderr); `2` usage error.

### `add-todo.sh`

```
./scripts/add-todo.sh \
  --priority P3 \
  --effort M \
  --title "Add docs versioning" \
  --description "Use mike for versioned docs"

./scripts/add-todo.sh \
  --priority "P?" \
  --effort "?" \
  --title "Try Rspress for docs" \
  --description "Evaluate AI-native docs framework alternative"

./scripts/add-todo.sh \
  --priority P2 --effort L \
  --title "Migrate kanban to Python" \
  --description "Bash 3.2 compat is getting expensive" \
  --backlog
```

Inserts a canonically-formatted entry into the matching `## P*` lane. With `--backlog`, also scaffolds `backlog/<slug>.md` from the skill's template and appends `→ [research](backlog/<slug>.md)` to the new line.

After writing, re-runs the validator. If validation fails, the original `TODO.md` is restored.

Flags:

- `--priority {P1|P2|P3|P?}` — required.
- `--effort {S|M|L|XL|?}` — required. `?` is only valid with `P?`.
- `--title TEXT` — required. Must not contain `*`.
- `--description TEXT` — required. Free-form after the em-dash.
- `--backlog` — also create the backlog research doc.
- `--file PATH` — TODO file (default `TODO.md`).
- `--dry-run` — print the rewritten file to stdout instead of mutating.

### `promote-todo.sh`

```
./scripts/promote-todo.sh \
  --title "<substring of the item's title>" \
  --summary "<one-line shipped summary>"
```

Atomically moves an active item from its lane into `## Done` with the dated `Done` syntax, then re-validates. Refuses to run if the substring matches zero or more than one active item — refine the substring.

Flags:

- `--title SUBSTRING` — required. Case-sensitive substring of the title.
- `--summary TEXT` — required.
- `--file PATH` — TODO file (default `TODO.md`).
- `--date YYYY-MM-DD` — override completion date (default: today, UTC).
- `--dry-run` — print to stdout, don't modify.
- `--validator PATH` — override validator path (default: sibling `todo-kanban.sh`).

### `sweep-inbox.sh`

```
./scripts/sweep-inbox.sh                # interactive triage of backlog/inbox.md
./scripts/sweep-inbox.sh --dry-run      # preview without modifying inbox or TODO
./scripts/sweep-inbox.sh --batch        # non-interactive: skip lines that need a prompt
```

Reads [`backlog/inbox.md`](https://github.com/daviddwlee84/agent-skills/tree/main/backlog) line by line. For each non-empty, non-comment line it prompts for the priority / effort / formal title / description (defaulting where possible), calls `add-todo.sh`, and removes the line from the inbox once the entry is committed.

`--batch` is intended for agent workflows: lines whose `priority:` / `effort:` / `title:` / `description:` are inferable get formalized automatically; ambiguous ones are left in the inbox for the next interactive sweep.

Inbox-line conventions (all optional; loose lines are also accepted):

```
# Comments and blank lines are ignored.
- maybe add docs versioning with mike
- priority=P3 effort=M title="Add docs versioning" desc="Use mike for versioned docs"
- the find-skills bootstrap UX is rough
```

The first form requires interactive prompting. The second form is fully parseable and works in `--batch` mode.

### `init.sh`

Lives only inside the skill (not mirrored to top-level `scripts/`): [`skills/local/project-knowledge-harness/scripts/init.sh`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/scripts/init.sh).

```
skills/local/project-knowledge-harness/scripts/init.sh \
  --target /path/to/project \
  --project-name "My Project" \
  --deployment chezmoi   # or npm | pip | docker | none
```

One-shot setup of `TODO.md` + `backlog/` + `pitfalls/` + agent guidance snippet + README snippet for any target repo. Idempotent. See [`project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) for the full flag list.

## Documentation sites

These ship with [`mkdocs-site-bootstrap`](https://daviddwlee84.github.io/agent-skills/skills/mkdocs-site-bootstrap/index.md). They are not mirrored into the repo-wide `scripts/` directory: the build helper is copied into each scaffolded project, while migration runs from the installed skill.

### `build-docs-site.py`

```
uv run python scripts/build-docs-site.py
uv run python scripts/build-docs-site.py --dry-run
uv run python scripts/build-docs-site.py --site-dir public --keep-temp
```

Canonical strict production build for scaffolded docs sites. Monolingual sites use one pass. Multilingual sites with llmstxt build default-language output separately from the full locale HTML site, validate and merge the artifacts, then replace the target site directory only after both passes succeed. Root `llms.txt`, `llms-full.txt`, and raw `.md` sidecars are default-language-only.

Flags: `--target-dir DIR`, `--config-file FILE`, `--site-dir DIR`, `--dry-run`, `--keep-temp`. Stdout is JSON; MkDocs logs and diagnostics go to stderr. Exits: `0` success, `2` invalid/missing input, `3` MkDocs failed, `4` output validation failed. There is no non-strict mode. Direct `mkdocs build --strict` remains an HTML-only preview because llmstxt is disabled by default in the scaffolded config.

### `migrate-i18n-llmstxt.sh`

```
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --json
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --apply --dry-run --json
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --apply --verify --json
```

Audits by default and only writes with `--apply`. It patches recognizable older scaffold shapes, installs/refreshes only a marker-owned build helper, and leaves custom config/CI/Makefile shapes in `manual_actions[]`. Candidate files are staged and validated before replacement, and the migration is idempotent. Updating the skill merely downloads this tool; it never runs automatically.

Flags: `--target-dir DIR`, `--apply`, `--dry-run`, `--verify`, `--json`. Important exits: `0` safe/migrated, `10` affected legacy config found during audit/dry-run, `11` manual work remains, `12` strict verification failed. See the canonical [`migration guide`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/i18n-llmstxt-migration.md).

## Skill authoring

These ship with [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md); the canonical copies live at [`skills/local/skill-author/scripts/`](https://github.com/daviddwlee84/agent-skills/tree/main/skills/local/skill-author/scripts). Not mirrored to top-level `scripts/` because they're agent-author tooling, not repo-wide make targets.

### `new-skill.sh`

```
bash skills/local/skill-author/scripts/new-skill.sh <skill-name>
bash skills/local/skill-author/scripts/new-skill.sh --project my-skill
bash skills/local/skill-author/scripts/new-skill.sh --global my-skill
bash skills/local/skill-author/scripts/new-skill.sh --local --vendor cherry-picked
bash skills/local/skill-author/scripts/new-skill.sh --dry-run my-skill
```

Scaffolds the canonical skill directory (`SKILL.md` + `references/` + `scripts/` + `assets/` from templates) and adds *relative* discovery symlinks for non-universal agents. Auto-detects placement scope by walking up from CWD; explicit flags override.

Placement scopes (see [creating local skills](https://daviddwlee84.github.io/agent-skills/workflows/creating-local-skills/index.md) for the full table):

- **LOCAL** — publishing-repo anchor (`vendor.yaml` / `skills/local/` / `skills/.claude-plugin/`) found. Canonical at `<repo>/skills/local/<name>/` (or `skills/vendor/` with `--vendor`); symlinks for `.agents/skills/` and `.claude/skills/`.
- **PROJECT** — `.git` found. Canonical at `<repo>/.agents/skills/<name>/`; symlink for `.claude/skills/<name>` (+ any already-present non-universal agent dir at the repo root).
- **GLOBAL** — neither anchor, or `--global`. Canonical at `~/.agents/skills/<name>/`; symlinks for `~/.claude/skills/<name>` and any other already-present non-universal agent dir under `$HOME`.

The symlink fan-out matches `npx skills add`'s discipline: "claude-code always, others only if their config root dir already exists at the base dir" — never creates `.windsurf/` or similar for agents the user doesn't actually use. Each created symlink is post-write verified with `test -e <link>/SKILL.md`; a dangling link aborts with exit 4.

Flags:

- `--local` / `--project` / `--global` — force scope (mutually exclusive).
- `--vendor` — LOCAL only; use `skills/vendor/<name>/`.
- `--root DIR` — override walk-up start dir.
- `--no-symlinks` — skip the agent-dir fan-out.
- `--dry-run` — print every action without writing.
- `--force` — overwrite the canonical dir and replace any existing symlinks.

Output: single JSON object on stdout (`{skill, mode, canonical, symlinks[], next_steps[]}`); prose on stderr.

Exit codes: `0` ok; `1` invalid args; `2` canonical dir already exists (use `--force`); `3` scope precondition failed (e.g. `--project` outside a git repo); `4` post-write symlink verification failed (the [symlink-target-relative footgun](https://daviddwlee84.github.io/agent-skills/reference/pitfalls/index.md)).

### `lint-skill.sh`

```
bash skills/local/skill-author/scripts/lint-skill.sh skills/local/<name>
bash skills/local/skill-author/scripts/lint-skill.sh --strict skills/local/<name>
bash skills/local/skill-author/scripts/lint-skill.sh --json   skills/local/<name>
```

Lints a skill directory for frontmatter + length, script hygiene (shebang / +x / `--help` handler), and reference reachability. See [`skill-author`](https://daviddwlee84.github.io/agent-skills/skills/skill-author/index.md) for the full checklist.

### `lint-frontmatter.sh`

```
make lint-frontmatter                                  # sweep skills/
./scripts/lint-frontmatter.sh skills/local/<name>/SKILL.md
./scripts/lint-frontmatter.sh --parser node skills     # exact npx-skills parity
```

YAML-parses the frontmatter of every `SKILL.md` under the given paths and checks that the root is a mapping with string `name` + `description`. `lint-skill.sh` delegates to it for the single-skill case.

This exists because harnesses **silently skip** a skill whose frontmatter does not parse — `npx skills add` prints `⚠ Skipped … YAML parse error` and still exits `0`. The usual cause is an unquoted `description:` containing `": "`; a `#` in an unquoted value is worse, since it parses but truncates the description at the comment marker (warning, not error). See [pitfalls](https://daviddwlee84.github.io/agent-skills/reference/pitfalls/index.md).

Parser is auto-detected: `yq` → PyYAML → the js `yaml` package (what `npx skills` itself uses; force it with `--parser node`). With none installed the script degrades to a pattern heuristic and says so.

Exit codes: `0` clean; `1` at least one file failed; `2` bad args, missing path, or forced parser unavailable.

### `git-hooks/pre-push`

```
make install-hooks     # symlink it into .git/hooks/pre-push
git push --no-verify   # bypass once
rm .git/hooks/pre-push # uninstall
```

Runs `make validate` (frontmatter + `marketplace.json` + `TODO.md` format) and aborts the push on failure, printing the tail of the output. Mirrors [`.github/workflows/validate.yml`](https://github.com/daviddwlee84/agent-skills/blob/main/.github/workflows/validate.yml), which runs the same three gates on push and PR — the hook just moves the signal earlier, since a broken `SKILL.md` is invisible at install time.

# Spec-Driven Development frameworks & agent harnesses

This page surveys the popular **spec-driven development (SDD)** frameworks and **agent harnesses** that sit *one layer above* agent skills, and records where this repo intentionally does not compete with them.

## The layering

Three things often get conflated. They are not the same:

| Layer             | What it is                                                                                                                                                                                        | Examples                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skill**         | A small `SKILL.md` (+ optional `references/`, `scripts/`) the agent loads on demand. Stateless prompt fragment. Governed by the [Agent Skills spec](https://agentskills.io/specification).        | This repo's skills, `mattpocock/skills`, `anthropics/skills`, `gstack` skills                                                                            |
| **SDD framework** | A workflow that owns the loop *requirements → spec → plan → tasks → execute → verify*, usually via slash commands and structured artifacts. Stateful (writes spec/plan/task files into the repo). | [`github/spec-kit`](https://github.com/github/spec-kit), [`gsd-build/get-shit-done`](https://github.com/gsd-build/get-shit-done)                         |
| **Agent harness** | A standalone CLI/runtime that *controls* the agent session — context windows, fresh subagents, git worktrees, crash recovery, cost tracking. Replaces or wraps the agent.                         | [`gsd-build/gsd-2`](https://github.com/gsd-build/gsd-2), [OpenClaw](https://github.com/openclaw/openclaw), [Pi SDK](https://github.com/badlogic/pi-mono) |

Skills are *consumed* by harnesses and SDD frameworks. They are not a substitute for either. This repo focuses on **skills**, and explicitly does not ship a SDD framework or harness.

## Surveyed projects

### `github/spec-kit` (95.5k ⭐) — the SDD reference implementation

The de facto SDD framework, maintained by GitHub. Installs a Python CLI (`specify`) plus a set of slash commands that write spec/plan/task artifacts into your repo:

| Command                                                      | What it produces                                   |
| ------------------------------------------------------------ | -------------------------------------------------- |
| `/speckit.constitution`                                      | `.specify/memory/` — project governing principles  |
| `/speckit.specify`                                           | Feature spec (the *what* and *why*, not the stack) |
| `/speckit.plan`                                              | Technical implementation plan (the *how*)          |
| `/speckit.tasks`                                             | Actionable task list                               |
| `/speckit.implement`                                         | Execute tasks                                      |
| `/speckit.clarify`, `/speckit.analyze`, `/speckit.checklist` | Optional quality gates                             |

Key properties:

- **Open ecosystem** — 80+ community extensions in [the catalog](https://github.com/github/spec-kit/blob/main/extensions/catalog.community.json) (Jira/Linear sync, security review, V-Model, brownfield bootstrap, retro, etc.) plus presets that override templates without touching tooling.
- **30+ supported agents** — Claude Code, Codex, Cursor, Copilot, Windsurf, Gemini CLI, Kilo, etc.
- **Skills mode** — `--integration <agent> --integration-options="--skills"` installs the slash commands as agent skills (`speckit-constitution`, `speckit-plan`, …) instead of slash-command files.
- **Stateless** — spec-kit itself doesn't manage agent sessions; it just writes prompt files and lets your agent execute.

### `gsd-build/get-shit-done` (61.4k ⭐) — opinionated SDD for solo builders

Earlier, lighter take on the same idea, by TÂCHES. Six-command loop:

```
/gsd-new-project → /gsd-discuss-phase → /gsd-plan-phase
  → /gsd-execute-phase → /gsd-verify-work → /gsd-ship
```

Differentiators vs spec-kit:

- **Fewer ceremonies** — explicitly built for solo devs, not 50-person eng orgs. No story points, no sprint syncs.
- **Subagent orchestration baked in** — execute runs plans in *parallel waves*, each in its own fresh 200k-token context.
- **Persistent artifacts** — `PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` / `STATE.md` / `CONTEXT.md` survive session boundaries so every fresh agent loads the same memory.
- Still a **prompt framework** — relies on the LLM following the prompts, no direct control over context or session lifecycle.

### `gsd-build/gsd-2` (7.3k ⭐) — GSD as a real harness

The successor that admits the prompt-framework approach has hard limits (no context control, no crash recovery, no real automation) and rebuilds GSD as a **standalone TypeScript CLI** on top of the [Pi SDK](https://github.com/badlogic/pi-mono). Now an actual *agent harness*:

| v1 (prompt framework)                 | v2 (agent harness)                                       |
| ------------------------------------- | -------------------------------------------------------- |
| Slash commands inside Claude Code     | Standalone CLI                                           |
| Hope the LLM doesn't fill its context | Fresh session per task, programmatic                     |
| LLM self-loop "auto mode"             | State-machine over SQLite database                       |
| No crash recovery                     | Lock files + session forensics + DB-backed runtime state |
| LLM writes git commands               | Worktree isolation, sequential commits, squash merge     |
| No cost/token tracking                | Per-unit ledger + dashboard + budget ceilings            |
| No stuck detection                    | Sliding-window dispatch detector + bounded retries       |

Hierarchy: **Milestone → Slice → Task** with an iron rule that *a task must fit in one context window*. `/gsd auto` runs the loop unattended until the milestone is done.

This is the same architectural class as OpenClaw and the gstack browser stack — code that *runs around* the agent rather than *inside* it.

### `Chen-Dixi/nano-bruce/specs` — minimal SDD pattern in the wild

A small working example showing how lightweight SDD can be:

```
specs/
├── mission.md
├── roadmap.md
├── tech-stack.md
├── 2026-04-24-configuration-system/
├── 2026-04-24-session-management/
└── 2026-05-03-terminal-ui/
```

Just three repo-level docs (mission / roadmap / tech-stack) plus date-stamped feature spec directories. No CLI, no slash commands, no harness — just a *convention* the agent reads. Useful as a reference for what "SDD" looks like stripped of tooling.

### `obra/superpowers` (186k ⭐) — methodology as a SKILL bundle

A 14-skill bundle that turns the SDD loop into discrete agent skills rather than slash commands. Skills include `brainstorming`, `writing-plans`, `executing-plans`, `test-driven-development`, `subagent-driven-development`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `verification-before-completion`, `using-git-worktrees`, `finishing-a-development-branch`, `dispatching-parallel-agents`, `using-superpowers`, `writing-skills`.

Differentiators:

- **Pure SKILL.md** — works in any agent that loads `SKILL.md` (Claude Code, Codex, OpenCode, Cursor, Gemini CLI), no CLI required
- **HARD-GATE pattern** — each skill has a refuse-to-proceed rule (e.g. brainstorming refuses to write code until a design is approved)
- **Ships agent files for multiple platforms** — `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `.opencode/`, `.gemini-extension`
- **Methodology as plugin** — `/plugin install superpowers` enables the whole flow at once

### `addyosmani/agent-skills` (39k ⭐) — Google-style SDLC scaffold

22 SKILL.md files covering the full SDLC: `spec-driven-development`, `planning-and-task-breakdown`, `incremental-implementation`, `test-driven-development`, `code-review-and-quality`, `debugging-and-error-recovery`, `documentation-and-adrs`, `api-and-interface-design`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `ci-cd-and-automation`, `deprecation-and-migration`, `git-workflow-and-versioning`, `performance-optimization`, `security-and-hardening`, `shipping-and-launch`, `context-engineering`, `doubt-driven-development`, `idea-refine`, `code-simplification`, `source-driven-development`, `using-agent-skills`.

Differentiators:

- **Heavier SDLC ceremony** — explicit ADR, security gate, deprecation guidance; suited to larger repos with engineering process requirements
- **Skill-per-phase** — finer granularity than spec-kit's slash commands
- **Standalone skills** — each can be invoked independently, no enforced overall flow

## SDD options at a glance

### Form, ownership, artifacts

| Project                         | ⭐   | Form                     | Loop ownership                 | Stateful artifacts                       | Best fit                                             |
| ------------------------------- | ---- | ------------------------ | ------------------------------ | ---------------------------------------- | ---------------------------------------------------- |
| `github/spec-kit`               | 96k  | CLI + slash commands     | Full loop, broad ecosystem     | `.specify/`                              | Default; want plugin community + 30+ agent support   |
| `gsd-build/get-shit-done`       | 61k  | Slash commands           | Full loop, less ceremony       | `PROJECT.md` / `STATE.md` / `CONTEXT.md` | Solo builder, fewer ceremonies                       |
| `gsd-build/gsd-2`               | 7k   | Standalone CLI (harness) | Full loop + session control    | SQLite `.gsd/`                           | Want context/session/cost control + crash recovery   |
| `obra/superpowers`              | 186k | SKILL.md bundle          | Capabilities, not a fixed loop | Per-skill artifacts                      | Want methodology in *any* agent without a CLI        |
| `addyosmani/agent-skills`       | 39k  | SKILL.md bundle          | Capabilities, not a fixed loop | ADRs, specs                              | Larger repos / strict process / ADR + security gates |
| `Chen-Dixi/nano-bruce` `specs/` | —    | Markdown convention      | None — agent reads convention  | `mission.md` / `roadmap.md` / dated dirs | Want zero tooling, just a layout                     |

### Sequential workflows (have a designed order)

These four projects ship a defined command sequence. The diagrams show the order their READMEs prescribe.

#### `github/spec-kit` — 5-step main loop + 3 optional gates

```
flowchart LR
    C[/speckit.constitution/] --> S[/speckit.specify/]
    S --> P[/speckit.plan/]
    P --> T[/speckit.tasks/]
    T --> I[/speckit.implement/]
    S -.gate.-> CL[/speckit.clarify/]
    P -.gate.-> A[/speckit.analyze/]
    T -.gate.-> CK[/speckit.checklist/]
```

The clarify / analyze / checklist commands are **orthogonal quality gates**, not "step 6". Run them when the spec or plan needs scrutiny.

#### `gsd-build/get-shit-done` (v1) — 6-step linear loop, repeats per phase

```
flowchart LR
    N[/gsd-new-project/] --> D[/gsd-discuss-phase/]
    D --> P[/gsd-plan-phase/]
    P --> E[/gsd-execute-phase/]
    E --> V[/gsd-verify-work/]
    V --> S[/gsd-ship/]
    S -. next phase .-> D
```

#### `gsd-build/gsd-2` — state machine driven by `/gsd auto`

```
stateDiagram-v2
    [*] --> NewProject : /gsd new-project
    NewProject --> AutoLoop : /gsd auto
    state AutoLoop {
        [*] --> Plan
        Plan --> Execute : per task (fresh session)
        Execute --> Verify : lint + test
        Verify --> Complete : pass
        Verify --> Execute : fail (auto-fix)
        Complete --> Reassess
        Reassess --> Plan : next slice
        Reassess --> ValidateMilestone : milestone done
    }
    AutoLoop --> Ship : squash-merge
    Ship --> [*]
```

Mostly automatic — the human triggers `/gsd auto`, the harness drives everything from a SQLite state machine and only stops on errors or budget ceilings.

#### `gstack` — 7-phase sprint with specialist roles

```
flowchart LR
    OH[/office-hours/] --> PR[plan-ceo-review<br/>plan-eng-review<br/>plan-design-review]
    PR --> AP[/autoplan/]
    AP --> Build[implementation]
    Build --> R[/review/ + /qa/ + /cso/]
    R --> CX[/codex<br/>cross-model<br/>second opinion/]
    CX --> SH[/ship/ + /land-and-deploy/ + /canary/]
    SH --> RT[/retro/]
```

Think → Plan → Build → Review → Test → Ship → Reflect, with a different specialist skill per role.

### Capability bundles (no fixed order)

These two install **a bag of skills** that fire on demand. There's an entry hard-gate, but the rest are categories you compose freely.

#### `obra/superpowers` — entry gate + 14 capabilities

```
flowchart TB
    Start([any task]) --> BS[brainstorming<br/><b>HARD-GATE</b>:<br/>no code until<br/>design approved]
    BS --> Pool

    subgraph Pool["14 capabilities — fire on demand"]
        direction LR
        Plan[writing-plans<br/>executing-plans]
        Code[test-driven-development<br/>subagent-driven-development<br/>dispatching-parallel-agents<br/>systematic-debugging]
        Review[requesting-code-review<br/>receiving-code-review<br/>verification-before-completion]
        Ship[using-git-worktrees<br/>finishing-a-development-branch]
        Meta[using-superpowers<br/>writing-skills]
    end
```

The only enforced order is: `brainstorming` first. Everything else is called when the agent decides it applies.

#### `addyosmani/agent-skills` — 22 SDLC capabilities

```
flowchart TB
    Start([any task]) --> Refine[idea-refine<br/>spec-driven-development<br/><i>typical entry points</i>]
    Refine --> Pool

    subgraph Pool["22 capabilities — fire on demand"]
        direction LR
        Plan[planning-and-task-breakdown<br/>context-engineering<br/>doubt-driven-development]
        Build[incremental-implementation<br/>test-driven-development<br/>code-simplification<br/>source-driven-development]
        Quality[code-review-and-quality<br/>debugging-and-error-recovery<br/>security-and-hardening<br/>performance-optimization]
        Domain[api-and-interface-design<br/>frontend-ui-engineering<br/>browser-testing-with-devtools]
        Ship[git-workflow-and-versioning<br/>ci-cd-and-automation<br/>shipping-and-launch<br/>deprecation-and-migration]
        Docs[documentation-and-adrs<br/>using-agent-skills]
    end
```

No enforced order at all. The 22 skills are SDLC capabilities the agent loads when their description matches the task. Closest to a "library" model.

### Convention only (no commands, no skills)

#### `Chen-Dixi/nano-bruce` `specs/` layout

```
flowchart LR
    M[mission.md] --> RM[roadmap.md]
    RM --> Spec[YYYY-MM-DD-feature/<br/>spec.md]
    Spec --> Agent([agent reads<br/>convention])
    Agent --> Impl[implement]
    Impl --> Commit[manual commit]
```

Pure markdown convention; no slash commands, no skills, no harness.

### Picking one — and only one

**Key warning:** loading two methodology bundles globally makes the agent re-litigate process at every step.

- The four sequential workflows (spec-kit, GSD v1, GSD v2, gstack) are **mutually exclusive at the project level** — each one expects to own the slash-command surface and the artifact directory.
- The two capability bundles (superpowers, addyosmani) **can technically coexist** with a sequential workflow, but in practice their entry hard-gates fire on every task and start fighting over who plans first.

Pick *one* primary methodology. Use individual skills from this repo (grilling, TDD, diagnose, retro, deep-research, etc.) as targeted augmentation, not as a competing methodology.

## How this repo relates

## How this repo relates

The cherry-picked vendor skills cover **selected pieces** of the SDD loop without committing to a specific framework or harness:

| SDD loop step             | spec-kit primitive              | gstack primitive                              | Skill in this repo                                                                                                         |
| ------------------------- | ------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Forcing-question intake   | `/speckit.clarify`              | `gstack-openclaw-office-hours`                | `product-planning/gstack-openclaw-office-hours`, `engineering-fundamentals/grill-with-docs`                                |
| Strategic scope challenge | (community ext)                 | `gstack-openclaw-ceo-review`                  | `product-planning/gstack-openclaw-ceo-review`                                                                              |
| Technical plan / PRD      | `/speckit.plan`                 | `/plan-eng-review`                            | `engineering-fundamentals/to-prd`                                                                                          |
| Issue/task breakdown      | `/speckit.tasks`                | (gstack auto)                                 | `engineering-fundamentals/to-issues`, `engineering-fundamentals/triage`                                                    |
| Implementation discipline | `/speckit.implement`            | `/ship`                                       | `engineering-fundamentals/tdd`                                                                                             |
| Debugging                 | (community ext)                 | `gstack-openclaw-investigate`, `/investigate` | `product-planning/gstack-openclaw-investigate`, `engineering-fundamentals/diagnose`                                        |
| Architecture care         | (community ext)                 | (n/a)                                         | `engineering-fundamentals/improve-codebase-architecture`, `engineering-fundamentals/zoom-out`                              |
| Retrospective             | (community ext)                 | `gstack-openclaw-retro`, `/retro`             | `product-planning/gstack-openclaw-retro`                                                                                   |
| Project memory            | `.specify/memory/` constitution | `STATE.md` / `CONTEXT.md`                     | [`local/project-knowledge-harness`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md) |

So a typical user workflow is:

- Pick a SDD framework if you want one (spec-kit is the safe default, GSD if you prefer fewer ceremonies, GSD-2 if you want a real harness).
- Install this repo's skills *alongside* it for the specific reasoning loops you care about (grilling, TDD, diagnosis, project memory).

These compose. The skills are stateless prompt fragments — they do not fight spec-kit's `.specify/` artifacts or GSD's `.planning/` / `.gsd/` databases.

## When to reach for which

| You want…                                                                                               | Reach for                                                         |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| A spec/plan/task workflow with broad agent support and a community ecosystem                            | **spec-kit**                                                      |
| The same loop, less ceremony, designed for solo builders                                                | **GSD v1**                                                        |
| An actual harness that controls context, sessions, git worktrees, cost, and survives crashes            | **GSD v2** or **OpenClaw**                                        |
| A *minimal* SDD pattern with no tooling, just markdown conventions                                      | **nano-bruce-style `specs/`** layout                              |
| Sharp, composable reasoning skills (grill, TDD, diagnose, retro, CEO-review) usable in any of the above | **This repo** (`engineering-fundamentals/` + `product-planning/`) |

## What this repo will *not* try to be

Recorded here so future agents don't relitigate it:

- **Not a SDD framework.** Spec-kit, GSD, BMAD, OpenSpec, Taskmaster all occupy that space. Building a 9th one is not interesting.
- **Not a harness.** GSD-2, OpenClaw, Pi SDK, claude-code-router occupy that space. Building agent runtime infrastructure is out of scope.
- **Not opinionated about *which* SDD framework to use.** This repo's skills should compose with spec-kit, GSD v1/v2, or no framework at all.

## See also

- [Agent skill compatibility](https://daviddwlee84.github.io/agent-skills/reference/agent-skill-compatibility/index.md) — the portable `SKILL.md` baseline this repo targets across agents
- [`npx skills` metadata model](https://daviddwlee84.github.io/agent-skills/reference/npx-skills-metadata/index.md) — how skills are discovered and grouped during install
- [Skill risk evaluations](https://daviddwlee84.github.io/agent-skills/reference/skills-risk-evaluations/index.md) — when a workflow should *not* become a skill

# Skill risk evaluations on skills.sh

[skills.sh](https://skills.sh/daviddwlee84/agent-skills) runs three independent audits against every skill in this repo and surfaces the verdicts on the catalog page:

| Auditor                   | What it checks                                                                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gen** (Agent Trust Hub) | High-level "is this skill safe to install?" verdict produced by Gen's own model.                                                                         |
| **Socket**                | Static scan of skill files for credential-shape strings, suspicious install scripts, network calls, obfuscation, etc.                                    |
| **Snyk**                  | A combination of standard CVE/SCA on declared dependencies plus a set of AI-skill-specific rules (W0xx) targeting prompt-injection / agent-facing risks. |

This page records the **current findings** and the reasoning for each, so a reader (or future me) does not have to re-derive whether a flag is a real problem or expected noise.

## Current findings

As of the most recent audit run shown on [skills.sh/daviddwlee84/agent-skills](https://skills.sh/daviddwlee84/agent-skills):

| Skill                       | Gen  | Socket      | Snyk         |
| --------------------------- | ---- | ----------- | ------------ |
| `mkdocs-site-bootstrap`     | Safe | 0 alerts    | **Med Risk** |
| `project-knowledge-harness` | Safe | 0 alerts    | Low Risk     |
| `agent-history-hygiene`     | Safe | **1 alert** | Low Risk     |

Both flagged items are **expected** and stem from the skills' core functionality, not from a real vulnerability. The reasoning follows.

## `agent-history-hygiene` — Socket 1 alert (expected)

- **File flagged:** `tests/fixtures/real_anthropic.md`
- **Pattern:** Anthropic API key shape (`sk-ant-api03-aaaa…AA`)
- **Severity:** medium / confidence high

The skill's whole job is to detect and redact secrets in agent transcripts and plan files. Verifying that `gitleaks` rules + the `redact_secrets.py` substitution logic actually fire requires a corpus of intentionally-realistic secret-shape strings. `tests/fixtures/` therefore deliberately contains:

- `real_anthropic.md` — `sk-ant-api03-` followed by 93 filler chars and `AA`, which is the exact shape the strict Anthropic rule expects
- `real_openai.md` — `sk-proj-` + 100 chars matching the OpenAI project-key rule
- `private_key.md` — fake `-----BEGIN RSA PRIVATE KEY-----` block

Socket's secret-pattern scanner can't distinguish "all-`a`s placeholder filler that exists to be matched" from "leaked credential," so it fires on the fixture. Removing the corpus would silently break the test suite, which defeats the purpose of having the skill in the first place. The alert stays.

If the alert is annoying on a downstream dashboard, mark it as a false positive in skills.sh / Socket with the rationale "intentional secret-shape test corpus for a secret-redaction skill."

### Keeping the fixtures out of scan scope

The fixtures are shaped to trip scanners on purpose, so the standing goal is "fake test vectors are out of scan scope **by default**, and only fire when a test re-plants them." How that is enforced across the surfaces that scan this repo (and downstream installs):

- **gitleaks (this repo, downstream, `npx skills add` copies).** Each firing line in the fixtures carries an inline `<!-- gitleaks:allow -->` marker (a `# gitleaks:allow` comment for the two PEM headers in `test_redact_secrets.py`). The marker travels with the file, so it also suppresses in a downstream user's freshly-bootstrapped gitleaks hook. The corpus + shell tests strip the marker before staging into their throwaway repo, so the rules still fire there. See the skill's [`tests/README.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/agent-history-hygiene/tests/README.md) "Test-vector hygiene" section for the byte-identical-strip invariant.
- **GitHub-native secret scanning / push protection.** Honors neither the marker nor gitleaks config, so the fixtures dir is excluded by path in [`.github/secret_scanning.yml`](https://github.com/daviddwlee84/agent-skills/blob/main/.github/secret_scanning.yml).
- **What was removed.** A former repo-root `.gitleaksignore` pinned each finding by `file:rule:line`; those fingerprints drift on any line edit (one entry was already stale) and never ship downstream. The co-located marker replaces it.

**Socket is a separate scanner that honors none of the above** — it re-derives the credential shape from file content — so the "mark as false positive" guidance above still stands for the Socket dashboard specifically.

## `mkdocs-site-bootstrap` — Snyk Med Risk (expected)

This one is **not** a transitive-dependency CVE — pinning, bumping, or removing a package will not change the score.

- **Rule:** `W011` — Third-party content exposure / indirect prompt injection
- **Risk score:** 0.90
- **Snyk's rationale (verbatim):**
  > The agent will read untrusted, user-generated third-party docs that could contain instructions and thus enable indirect prompt injection.

The skill ships templates that install `mkdocs-llmstxt` and `mkdocs-copy-to-llm` by default, which produce:

- `/llms.txt` and `/llms-full.txt` — full-content dumps intended for LLM ingestion
- Per-page "copy as markdown for LLM" buttons

On multilingual sites, the managed `scripts/build-docs-site.py` isolates `mkdocs-llmstxt` from `mkdocs-static-i18n`: root llms files and raw `.md` sidecars contain the default language only, while translated HTML is built in a separate strict pass. Direct `mkdocs build --strict` is an HTML-only preview. This fixes empty/wrong-locale output; it is **not** a trust boundary and does not sanitize the default-language docs.

Any LLM-driven agent that consumes those endpoints is reading whatever ended up in `docs/`. If `docs/` accepts external contributions (e.g. open-source PRs), an attacker can plant prompt-injection payloads in a doc page and have them flow into a downstream agent's context. Snyk's W0xx ruleset flags that agent-facing surface.

### Why we accept the score

The whole point of dogfooding `mkdocs-llmstxt` + copy-to-llm is to make these docs LLM-friendly; degrading that defeats the skill. A real fix is **trust modeling**, not a dependency change:

- Treat `docs/` as an LLM input boundary (CODEOWNERS on `docs/**`, require review for external PRs).
- Document the threat in the skill so downstream users opt in knowingly.

A future opt-out flag on `init-docs-site.sh` (e.g. `--no-llmstxt`) for repos that don't want the LLM-facing surface is tracked in `TODO.md` rather than landed pre-emptively.

### See also

- [`reference/mkdocs-2-and-zensical.md`](https://daviddwlee84.github.io/agent-skills/reference/mkdocs-2-and-zensical/index.md) — why we pin `mkdocs<2` (different rationale, same skill).
- [`reference/docs-stack-recipe.md`](https://daviddwlee84.github.io/agent-skills/reference/docs-stack-recipe/index.md) — what the bootstrap actually installs.
- [i18n + llmstxt migration guide](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/mkdocs-site-bootstrap/references/i18n-llmstxt-migration.md) — why existing downstream sites need an explicit audit/migration after updating the skill.

## Why we don't ship README badges yet

skills.sh **does not currently expose first-party badge endpoints**. We probed the obvious paths and all returned 404:

```
https://skills.sh/<owner>/<repo>/badge.svg          → 404
https://skills.sh/badge/<owner>/<repo>.svg          → 404
https://skills.sh/api/badge/<owner>/<repo>          → 404
```

That leaves three options if we ever want a row of audit badges in `README.md`, in increasing order of effort:

1. **Static `shields.io` badges + manual hyperlinks.** Hand-write each badge's value (`Safe`, `1 alert`, `Med (W011)`) and link the image to the skills.sh detail page. Zero infrastructure, but drifts the moment an audit re-runs.
1. **`shields.io` `endpoint` schema + a self-hosted JSON file.** A scheduled GitHub Action scrapes skills.sh, writes `badges/{gen,socket,snyk}.json` to `gh-pages`, and shields.io's [endpoint badge](https://shields.io/badges/endpoint-badge) renders against that JSON. Auto-updating, ~half a day to set up.
1. **Vendor-native badges from Snyk / Socket directly.** Snyk and Socket each publish their own badges, but they target whole-repo or npm-package scopes rather than per-skill verdicts, so they don't represent the same thing skills.sh shows.

We've parked all three. Re-evaluate when skills.sh ships a first-party badge endpoint, or when the audit signal becomes load-bearing for trust decisions (e.g. external contributors using verdicts to decide whether to install).

## When to revisit this page

- A new skill lands and gets its first non-trivial audit verdict.
- An existing finding flips (e.g. Socket alert disappears after a Socket rule update, or a new W0xx fires).
- skills.sh changes the auditor lineup, or starts publishing badge URLs.

# Tag schema (priority × effort)

This is the human-readable mirror of [`skills/local/project-knowledge-harness/references/tag-schema.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/tag-schema.md), which is what the agent loads on demand. Same content, available here so maintainers don't have to dig into the skill directory.

Two orthogonal axes prevent the "important but unimplementable" trap.

## Priority

- `P1` — likely next batch (you'd reach for this if you sat down today)
- `P2` — worth doing, no rush
- `P3` — someday / nice-to-have
- `P?` — needs evaluation first; spike before committing to a priority

## Effort

- `S` — under an hour
- `M` — half day
- `L` — multi-day
- `XL` — architectural; design doc required before code

## Useful combinations

- `P?` + `[?/L]` — explicit "unknown of size L"; the most honest tag
- `P3` + `[S]` — "small enough to slip into any free moment"
- `P1` + `[XL]` — warns "you said this is urgent but it's actually huge — re-scope"

## Heading and item syntax (validator-checked)

[`scripts/todo-kanban.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#todo-kanbansh) enforces this exact form. The full grammar lives in [TODO format](https://daviddwlee84.github.io/agent-skills/reference/todo-format/index.md). The short version:

- Section headings, in order: `## P1`, `## P2`, `## P3`, `## P?`, `## Done`
- Active items in `P1` / `P2` / `P3`: `- [ ] **[Effort] Title** — description`
- Active items in `P?`: `- [ ] **[?/Effort] Title** — description`
- Shipped items in `Done`: `- ✅ [YYYY-MM-DD] [P#/Effort] Title — one-line shipped summary`
- Optional trailing on active items: `→ [research](backlog/<slug>.md)`

Anything that is **not** a top-level `- [ ]` / `- ✅` item — prose paragraphs, blockquotes, HTML comments, `---` rules, indented sub-bullets — is ignored by the validator. Use this room for explanatory text without breaking machine-readability of the lanes.

# TODO format

This page documents the exact grammar that [`scripts/todo-kanban.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#todo-kanbansh) validates. It applies to this repo's own [`TODO.md`](https://github.com/daviddwlee84/agent-skills/blob/main/TODO.md) and to any project that has run [`project-knowledge-harness`'s `init.sh`](https://daviddwlee84.github.io/agent-skills/skills/project-knowledge-harness/index.md).

## File-level structure

1. The first non-empty heading **must** be `# TODO`.
1. Sections **must** appear in this order: `## P1`, `## P2`, `## P3`, `## P?`, `## Done`.
1. After `## Done`, additional `## ...` headings are allowed (e.g. a `## Notes` section, a prune log). The validator stops checking item format at that point.
1. Anything that is **not** a top-level `- [ ]` / `- ✅` item — prose paragraphs, blockquotes, HTML comments, `---` rules, indented sub-bullets — is ignored. You can write inline guidance under each section heading without breaking validation.

## Item-level grammar

| Lane               | Format                                          |
| ------------------ | ----------------------------------------------- |
| `P1` / `P2` / `P3` | `- [ ] **[Effort] Title** — description`        |
| `P?`               | `- [ ] **[?/Effort] Title** — description`      |
| `Done`             | `- ✅ [YYYY-MM-DD] [P#/Effort] Title — summary` |

Where:

- **Effort** is one of `S`, `M`, `L`, `XL`. For `P?` items where effort is also unknown, use `[?/?]`.
- **Title** must not contain `*` (the validator uses the closing `**` as a delimiter).
- **Description / summary** can be free text after the em-dash (`—`, U+2014). Plain hyphens (`-`) are not accepted.
- Active items may end with `→ [research](backlog/<slug>.md)` to link the index entry to a `backlog/` doc.
- `Done` items use a date in `YYYY-MM-DD` format. UTC by convention; the promote script uses `date -u +%Y-%m-%d`.

## Examples

```
## P1

- [ ] **[S] Wire up GitHub Pages** — first deploy of the docs site

## P2

- [ ] **[L] Migrate kanban to Python** — Bash 3.2 compat is getting expensive → [research](backlog/kanban-python.md)

## P?

- [ ] **[?/M] Try Rspress for docs** — evaluate AI-native docs framework alternative
- [ ] **[?/?] Skill-set lint** — vague idea, needs scoping

## Done

- ✅ [2026-04-23] [P1/M] Restructure project-knowledge-harness — looser validator, init/promote scripts, references/ progressive disclosure
```

## Tools that depend on this format

- [`scripts/todo-kanban.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#todo-kanbansh) — validator and Markdown / JSON board renderer.
- [`scripts/promote-todo.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#promote-todosh) — atomic move from active lane to `## Done`.
- [`scripts/add-todo.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#add-todosh) — structured insert into the right lane.
- [`scripts/sweep-inbox.sh`](https://daviddwlee84.github.io/agent-skills/reference/scripts/#sweep-inboxsh) — formalize loose captures from `backlog/inbox.md` via repeated `add-todo.sh` calls.

If you find yourself wanting a syntax that isn't here, it's worth asking whether the new shape is genuinely useful or whether it's another `IDEAS.md` file in disguise — see [`references/anti-patterns.md`](https://github.com/daviddwlee84/agent-skills/blob/main/skills/local/project-knowledge-harness/references/anti-patterns.md).

# Warp Oz skills

[Warp](https://github.com/warpdotdev/warp) (57k⭐) is a terminal that evolved into an "agentic development environment." In May 2026 Warp open-sourced its main codebase under **AGPL-3.0**. Alongside the main repo, the team publishes [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills) (764⭐) — a growing collection of skills for their **Oz** cloud-agent platform.

## Why oz-skills is installable here

oz-skills is **MIT-licensed** and follows the [agentskills.io specification](https://agentskills.io/specification), so the skills work in any compliant agent: Claude Code, Codex, OpenCode, Cursor, Gemini CLI. The Warp agent is just another host — the skills themselves are portable markdown.

The Warp main repo is AGPL-3.0 (viral copyleft); that license does **not** propagate to oz-skills, which is separately MIT. Vendoring oz-skills into this repo is safe.

## Skills we vendor (6 of 15)

We pick skills that fill genuine gaps in this repo's existing lineup. Skipped skills: `mcp-builder` (duplicate of `anthropics/mcp-builder`), `webapp-testing` (duplicate of `anthropics/webapp-testing` in the `fullstack-nextjs` series), `scheduler` (too narrow — local-only reminders), `slack-qa-investigate` (Slack dependency), `dbt-model-index` / `analysis-artifacts` (BigQuery-shaped for Warp's internal stack), `terraform-style-check` (too narrow), `seo-aeo-audit` (too opinionated), `docs-update` (overlaps `doc-coauthoring` / the doc-update pattern already in CLAUDE.md).

### `github-workflow` plugin — 4 skills

| Skill                      | Description                                                                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ci-fix`                   | Diagnose GitHub Actions failures: inspect logs via `gh`, identify root cause, implement a minimal fix, push to a dedicated fix branch. Prerequisite: `gh auth status`.      |
| `create-pull-request`      | Create a well-structured PR following project conventions — commit analysis, branch management, PR body via `gh pr create`.                                                 |
| `github-bug-report-triage` | Evaluate a GitHub bug issue for actionability. Locates the project's bug-report template, checks required fields, and drafts a constructive comment for incomplete reports. |
| `github-issue-dedupe`      | Detect duplicate issues using multi-strategy semantic + keyword search. Can run manually or be wired into a GitHub Actions workflow.                                        |

These complement `engineering-fundamentals/triage` (mattpocock) which is more general-purpose. The Oz skills are GitHub-specific and use the `gh` CLI for automation.

### `web-quality` plugin — 2 skills

| Skill                     | Description                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `web-accessibility-audit` | WCAG 2.0/2.1/2.2 compliance audit — identifies violations by POUR principle category, provides remediation steps. Works without an MCP dependency.                                         |
| `web-performance-audit`   | Core Web Vitals + Lighthouse audit using the `chrome-devtools` MCP. Requires `chrome-devtools-mcp@latest` configured in `.mcp.json`. If not configured, the skill tells you how to add it. |

`web-accessibility-audit` is MCP-free and works anywhere. `web-performance-audit` requires the Chrome DevTools MCP — the skill gracefully degrades if it is not present.

## Install

```
# All 6 via this repo
npx skills@latest add daviddwlee84/agent-skills

# Or directly from upstream
npx skills@latest add warpdotdev/oz-skills/.agents/skills/ci-fix
npx skills@latest add warpdotdev/oz-skills/.agents/skills/web-accessibility-audit
# ...
```

## Warp's AGPL-3.0 note

The Warp terminal itself is AGPL-3.0. If you embed Warp into a product you ship to users, AGPL requires you to open-source your modifications. Using Warp as a local development tool does not trigger AGPL. Using oz-skills (MIT) separately from Warp has no AGPL implications.

## See also

- [Browser automation skills](https://daviddwlee84.github.io/agent-skills/reference/browser-automation-skills/index.md) — testing web apps in a real browser; complements the web-quality skills above
- [`fullstack-nextjs/webapp-testing`](https://daviddwlee84.github.io/agent-skills/skills/webapp-testing/index.md) — the Playwright-based Anthropic skill already vendored for frontend QA
- [Agent skill compatibility](https://daviddwlee84.github.io/agent-skills/reference/agent-skill-compatibility/index.md) — portable `SKILL.md` spec all these skills follow
# Changelog

# Changelog

This page summarizes notable changes. Day-to-day commit history lives in [git log](https://github.com/daviddwlee84/agent-skills/commits/main); this file curates the milestones.

## Unreleased

- Added canonical `agent-history-hygiene` post-session protocol v2 with strict unchanged v1 recovery: durable private sanitation beforeimages, exact finding/ occurrence transformation receipts, whole frozen-index scanner coverage, and source-bound per-finding review for noncredential fixtures versus credential rotation or unresolved evidence. Review never restores raw bytes, adds blanket allows, skips hooks, or retries uncertain commits; partial publication remains explicitly unproven.
- New v2 wrappers default to native no-cloud flags, pin explicit resume UUIDs and typed queued-request acknowledgements, and prove the selected alias against a bounded read-only native exact export plus unchanged native source generation. Stale aliases/unsupported export block without retargeting. Side-effect-free capabilities/inspection and revision-guarded prepare/reconcile APIs support a thin native adapter while the canonical helper retains all commit authority. macOS helper subprocesses use stock Bash 3.2, avoiding unstable PATH-shell substitution behavior without weakening exact selector checks.
- Released `agent-history-hygiene` hook v2.0.1: scoped the upstream `sourcegraph-access-token` bare-40-hex false positive to agent artifacts while preserving real `sgp_...` detection, and advanced fresh bootstrap to gitleaks v8.30.1 so global `[[allowlists]]` / `targetRules` are actually applied.
- Bootstrapped a [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) documentation site with `mkdocs-llmstxt` and `mkdocs-copy-to-llm`, deployable to GitHub Pages.
- Fixed `mkdocs-static-i18n` + `mkdocs-llmstxt` builds that could silently overwrite root llms files with an empty or wrong-locale final pass. New scaffolds use a strict two-pass `scripts/build-docs-site.py`; existing sites get an audit-first, idempotent migration tool. Updating the skill alone does not modify downstream projects.
- Added `scripts/add-todo.sh` for structured TODO inserts and `scripts/sweep-inbox.sh` for triaging loose captures from `backlog/inbox.md`. See [Project memory workflow](https://daviddwlee84.github.io/agent-skills/workflows/project-memory/index.md).
- Added [Downstream docs stack recipe](https://daviddwlee84.github.io/agent-skills/reference/docs-stack-recipe/index.md) so projects consuming our skills can mirror the same docs setup.

## 2026-04 — `project-knowledge-harness` restructure

- Loosened `scripts/todo-kanban.sh` validator to ignore prose, blockquotes, HTML comments, `---` rules, and indented sub-bullets. Added `--validate-only` and `--json` flags. Allowed extra `## ...` headings after `## Done`.
- Added `scripts/init.sh` for one-shot setup of `TODO.md` + `backlog/` + `pitfalls/` + agent-guidance + README snippet in any target repo.
- Added `scripts/promote-todo.sh` for atomic active-→-Done moves with re-validation and dry-run support.
- Slimmed `SKILL.md` (~350 → ~170 lines) and pushed detail into `references/{tag-schema,when-to-add-docs,anti-patterns,deployment-exclusion}.md` for [progressive disclosure](https://agentskills.io/specification#progressive-disclosure).

## 2026-03 and earlier

- Initial vendor system (`vendor.yaml`, `scripts/add-vendor.sh`, `scripts/sync-vendor.sh`, `make sync` / `make sync-check`).
- Initial `project-knowledge-harness` skill (formerly `backlog-harness`).
- `quantatitive-factor-researcher` persona skill.