feat: skills + agent instructions for repo + better practices

.gitignore

@@ -16,3 +16,16 @@ node_modules/
 
 # OS
 .DS_Store
+
+# issue-triage clarifying Q&A / resume artifacts (subject-repo local state)
+.issue-triage/
+
+# pr-feedback-qa session JSON (subject-repo local state; also ensured by session_log.py)
+.scratch/
+
+# skill-creator eval run workspaces (sibling to skill dirs or repo root)
+*-workspace/
+skills/*-workspace/
+
+# Local scratch (not canonical)
+.lavish/

AGENTS.md

@@ -0,0 +1,43 @@
+# Skills Catalog — Agent Guide
+
+> Scope: Root project (applies to all subdirectories unless overridden)
+
+Agent skills catalog for the [skills CLI](https://github.com/vercel-labs/skills) and a Cursor [Agent Plugin](https://agent-plugins.org) (`plugin.json` + `skills/`). Each skill is `skills/<name>/SKILL.md` (+ optional helpers).
+
+## Quick Facts
+
+- **Primary language:** Markdown skills; Python 3.12+ for contracts and catalog scripts
+- **Package manager:** [uv](https://docs.astral.sh/uv/) (`pyproject.toml`, `package = false`)
+- **Entrypoints:** `task` via `Taskfile.yml`
+- **CI:** `.github/workflows/ci.yml` → `task ci`; PR title lint; scheduled upstream sync
+
+## Canonical docs
+
+| Doc | Contents |
+| --- | --- |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Repo shape, authored vs vendored, discovery contract, quality pipeline |
+| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Bootstrap, `task` operations, local patterns (skills, tests, vendor sync) |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Human contributor workflow, upstream PAT, commit/PR conventions |
+| [README.md](README.md) | Install UX and public skill inventory |
+
+## Orientation (one screen)
+
+- **Authored** skills: edit `skills/<name>/`; dir name = frontmatter `name`.
+- **Vendored** skills: edit `upstream-skills.toml` only → `task sync-upstream-skills`; never hand-edit vendored trees.
+- Day-to-day gate: `task ci` (`validate` + `lint`). Details: [DEVELOPMENT.md](docs/DEVELOPMENT.md).
+- How the catalog fits together: [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+- `.lavish/` is local scratch, not canon.
+
+## Documentation Duties
+
+- Update `README.md` when the skill list or install story changes
+- Update `docs/DEVELOPMENT.md` / `docs/ARCHITECTURE.md` when ops or structure change
+- Update `CONTRIBUTING.md` when validation/sync/PR rules change
+- Keep skill `description` frontmatter accurate (discovery + install UX)
+
+## Finish the Task Checklist
+
+- [ ] `task ci` clean (or `task validate` + relevant lint)
+- [ ] Relevant docs updated (`README.md` / `docs/*` / `CONTRIBUTING.md` as needed)
+- [ ] Summarize changes in conventional commit form (e.g. `feat: …`, `fix: …`, `docs: …`)
+- [ ] No hand-edits to vendored `skills/<name>/` without catalog + re-sync

CONTRIBUTING.md

@@ -11,9 +11,15 @@ skills/
   my-skill/
     SKILL.md        # required: frontmatter with `name` and `description`
     scripts/        # optional helper scripts (keep them executable)
-    evals/          # optional evaluation cases
+    evals/          # optional evaluation cases (skill-creator evals.json + fixtures)
 ```
 
+Prefer deterministic helpers under `scripts/` for anything an agent would otherwise
+guess (CLIs, schemas). Cover them with pytest under `tests/`. Skill-creator
+evals should use realistic prompts + local fixtures (issue snapshots, validators)
+and avoid live external I/O; reserve mocks for script unit tests only (e.g.
+`issue-triage`’s `mock_gh.py` for `issue_ops` pytest, not for `evals/evals.json`).
+
 ## Adding or updating a skill
 
 1. Create `skills/<name>/SKILL.md` with at least:

README.md

@@ -13,12 +13,17 @@ Each skill is a directory under `skills/<name>/` containing a `SKILL.md` (plus a
 | Skill | Description |
 | --- | --- |
 | `agentsmd-generator` | Generate project-level `AGENTS.md` onboarding guides covering structure, tooling, testing, task flow, and conventions. |
+| `issue-triage` | Turn a rough GitHub Issue into an agent-executable sealed body with `ready` + size labels (explicit invocation). Clarifying Q&A persists under `.issue-triage/` (gitignored) for resume. Ships `issue_ops` + validators, offline `evals/`, and `mock_gh` for script unit tests. |
 | `bro` | Slash-command only (`/bro`): restate the last message plainly and concisely, without jargon. |
 | `jj-case-insensitive-clone-fix` | Diagnose and fix the `jj git clone` "Failed to update refs" error on case-insensitive filesystems (e.g. macOS APFS). |
+| `lavish-safe` | Local-only Lavish HTML review via `lavish-axi`, with share and telemetry forbidden. |
+| `pr-feedback-qa` | Disposition PR or file-based review feedback one item at a time (Address / Skip / GitHub Issue), with resumable JSON sessions under `.scratch/pr-feedback-qa/` and a final decision table. |
 | `research_codebase` | Map how a codebase works today and save a dated, citation-backed report under `thoughts/`, using parallel sub-agents by default. |
 | `sdd-linear` | Run the Spec-Driven Development (SDD) workflow with Linear issues, sub-issues, attachments, and comments as the system of record instead of `docs/specs`. |
+| `sdd-qa` | Ask SDD `docs/specs` clarification questions ONE-by-ONE and write decisions back to the questions file (explicit slash invocation). |
 | `sync-upstream` | Sync a fork's default branch with its upstream remote using merge or rebase, resolving conflicts as needed. |
 | `taskfile-automation` | Scaffold consistent, portable repo automation with a `Taskfile` as the single entry point (run the same locally and in CI), adding Docker/Compose only when external runtime deps demand it. |
+| `visual-explain` | Interactive local HTML explanation of a diff/branch/PR (Background, Intuition, Code walkthrough, Quiz). Adapted from sighup/claude-workflow `cw-explain`. |
 | `work-breakdown` | Decompose large/ambiguous scope into smaller units of work with dependencies and parallelization. |
 
 ### Vendored from upstream
@@ -34,6 +39,13 @@ Provenance (source commit and license) is recorded in `upstream-skills.lock.json
 | Skill | Upstream | License | Description |
 | --- | --- | --- | --- |
 | `agent-browser` | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | Apache-2.0 | Browser automation CLI for AI agents (navigate, fill forms, screenshot, scrape, test web/Electron apps). |
+| `grill-me` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Relentless interview to sharpen a plan or design (explicit invocation). |
+| `grill-with-docs` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Same grilling loop, also producing ADRs and glossary docs as you go. |
+| `grilling` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Stress-test a plan/decision/idea with a decision-tree interview. |
+| `improve-codebase-architecture` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Scan for deepening opportunities, present an HTML report, then grill one. |
+| `teach` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Teach a skill or concept inside the current workspace. |
+| `test-driven-development` | [obra/superpowers](https://github.com/obra/superpowers) | MIT | TDD workflow before writing implementation code. |
+| `wayfinder` | [mattpocock/skills](https://github.com/mattpocock/skills) | MIT | Map large work as decision tickets on an issue tracker and resolve them one by one. |
 
 Some upstream skills set `hidden: true`, so they will not appear in
 `npx skills add SystemFiles/skills --list`. Install them by explicit name, for
@@ -77,6 +89,22 @@ Install every skill in this repo:
 npx skills add SystemFiles/skills --skill '*'
 ```
 
+### Cursor plugin (IDE / team / Cloud Agents)
+
+This repo is also an [Agent Plugin](https://agent-plugins.org): root [`plugin.json`](plugin.json) plus `skills/*/SKILL.md`. Prefer this path when you want Cursor (not other agents) to load the whole catalog without the skills CLI.
+
+Local dry-run:
+
+```bash
+ln -s "$(pwd)" ~/.cursor/plugins/local/systemfiles-skills
+```
+
+Reload Cursor, then confirm skills under Customize.
+
+Team Marketplace (Teams / Enterprise): Dashboard → Plugins → import this GitHub repo → set Required or Default On. Enable auto-refresh if the Cursor GitHub App is on the repo.
+
+Cloud Agents do not see `npx skills add --global` home installs. After marketplace install, verify a Cloud Agent can invoke a skill from this catalog. If it cannot, commit the needed skills under `.agents/skills/` or `.cursor/skills/` in the target repo (project-scoped discovery).
+
 ## Updating and removing
 
 ```bash

cspell.config.yaml

@@ -7,10 +7,15 @@ words:
   - Codex
   - evals
   - frontmatter
+  - sighup
+  - wayfinder
+  - obra
+  - mattpocock
   - pytest
   - repo
   - sdd
   - skillsrc
+  - systemfiles
   - taskfile
   - venv
   - vercel

docs/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Architecture
+
+This repo is a **skills.sh source catalog** and an [Agent Plugin](https://agent-plugins.org) package. Consumers install skills with the [skills CLI](https://github.com/vercel-labs/skills) (`npx skills add SystemFiles/skills …`) or load the whole catalog as a Cursor plugin via root `plugin.json`. Agents load installed `SKILL.md` files; this repo’s Python tooling only validates the catalog and vendors upstream copies.
+
+## Layout
+
+```text
+.
+├── plugin.json             # Agent Plugins manifest (Cursor / portable clients)
+├── skills/<name>/          # installable units (authored + vendored)
+│   └── SKILL.md            # required; YAML frontmatter name + description
+├── scripts/                # catalog maintenance (sync / capture)
+├── tests/                  # pytest contracts + script unit tests
+├── upstream-skills.toml    # declaration of vendored skills
+├── upstream-skills.lock.json
+├── Taskfile.yml            # single automation entry point
+├── docs/                   # agent/dev architecture + local development
+└── .github/workflows/      # ci, pr-title-lint, sync-upstream-skills
+```
+
+Optional under a skill: `scripts/`, `evals/`, `references/`, `examples/`, attribution files (`LICENSE`, `NOTICE`).
+
+## Two skill populations
+
+```text
+  authored                          vendored
+  ────────                          ────────
+  Edit skills/<name>/ directly      Edit upstream-skills.toml only
+       │                                 │
+       │                                 ▼
+       │                    task sync-upstream-skills
+       │                    (scripts/sync_upstream_skills.py)
+       │                                 │
+       │                                 ▼
+       │                    skills/<name>/ + lockfile
+       ▼                                 │
+  tests/test_skill_contract.py ◄─────────┘
+  (every */SKILL.md: name, description, dir==name, unique)
+```
+
+| Kind | Source of truth | Rule |
+| --- | --- | --- |
+| **Authored** | `skills/<name>/` in this repo | Edit freely; keep dir name = frontmatter `name` |
+| **Vendored** | `upstream-skills.toml` + upstream git | Do not hand-edit `skills/<name>/`; change catalog → re-sync → commit tree + lockfile |
+
+Sync clones each `[[skill]]`, copies the skill folder (and LICENSE/NOTICE), refuses copyleft licenses, writes provenance to `upstream-skills.lock.json`. Scheduled workflow [sync-upstream-skills](../.github/workflows/sync-upstream-skills.yml) refreshes vendored copies; pushes use `SYNC_UPSTREAM_PAT` so other workflows still fire.
+
+`task capture-project PROJECT=…` scans another project’s installed skills and proposes catalog entries. Local-only skills with no shareable git source stay out of the catalog (promotion target: authored skills here).
+
+## Discovery contract
+
+The skills CLI finds skills by **frontmatter `name`**, not directory name alone. Contract tests enforce:
+
+- Non-empty `name` and `description`
+- Directory name equals frontmatter `name`
+- Names unique across `skills/`
+- A pinned `EXPECTED_SKILLS` set stays present (authored baseline; update when adding/removing authored skills)
+
+Install surface for humans: root `README.md` skill tables.
+
+## Cursor / Agent Plugin install
+
+Root [`plugin.json`](../plugin.json) follows the [Agent Plugins](https://agent-plugins.org) standard. Cursor discovers every immediate child of `skills/` that has a `SKILL.md`. Catalog dirs (`scripts/`, `tests/`, `docs/`) stay in-repo; plugin clients ignore them.
+
+| Surface | Mechanism | Cloud Agents |
+| --- | --- | --- |
+| skills CLI | `npx skills add …` into agent skill dirs | No — cloud VMs lack user home installs |
+| Cursor plugin | Team Marketplace import of this repo, or `~/.cursor/plugins/local` symlink | Verify after install; if missing, commit skills under `.agents/skills/` / `.cursor/skills/` in the target repo |
+
+Team distribution: Dashboard → Plugins → import this GitHub repo → **Required** or **Default On**. Local dry-run: symlink the repo to `~/.cursor/plugins/local/systemfiles-skills` and reload Cursor.
+
+## Quality pipeline
+
+```text
+local / CI
+    task ci
+      ├─ task validate  →  uv run pytest -q
+      └─ task lint      →  uv run pre-commit run --all-files
+                            (markdownlint, cspell, gitleaks, …)
+
+local (opt-in; needs Cursor agent CLI)
+    task evals:validate          →  scripts/validate_evals.py
+    task evals [SKILL=<name>]    →  agent -p (Sonnet 5): one process per eval in parallel, then aggregate
+
+PR title  →  Conventional Commits (pr-title-lint workflow)
+```
+
+No runtime services or Docker: catalog + scripts only. `pyproject.toml` sets `package = false`; uv only manages the dev dependency group.
+
+## Skill-internal patterns (authored)
+
+Prefer **deterministic helpers** under `skills/<name>/scripts/` for anything an agent would otherwise invent (CLIs, schemas, allowlists). Cover them from repo-root `tests/`.
+
+Skills that talk to external systems (GitHub, etc.) should keep **evals offline** via local snapshots (no live I/O). Reserve mocks for script unit tests — e.g. `issue-triage` uses issue fixtures in `evals/` and `mock_gh.py` only under `tests/`.
+
+## Non-canon paths
+
+- `.lavish/` — local review artifacts; not architecture or process canon
+- `.issue-triage/` — issue-triage clarifying Q&A / resume logs; gitignored
+- `.agents/`, `skills-lock.json` — install-side artifacts; gitignored (this repo is a source, not a consumer)
+- `skills/*-workspace/` — skill-creator eval run workspaces; gitignored
+
+## Related docs
+
+- [DEVELOPMENT.md](DEVELOPMENT.md) — setup, tasks, day-to-day patterns
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — contributor / PR conventions
+- [README.md](../README.md) — install UX and skill inventory

docs/DEVELOPMENT.md

@@ -0,0 +1,105 @@
+# Local Development
+
+Setup, day-to-day commands, and patterns for working in this catalog. Architecture and skill populations: [ARCHITECTURE.md](ARCHITECTURE.md). Contributor/PR rules: [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Prerequisites
+
+| Tool | Role |
+| --- | --- |
+| [uv](https://docs.astral.sh/uv/) | Python 3.12+ toolchain + deps (`uv sync`) |
+| [Task](https://taskfile.dev) | Single automation entry point (`Taskfile.yml`) |
+| Node / `npx` | Only for `task verify-discovery` (skills CLI) |
+| Cursor `agent` CLI | Only for `task evals` (skill-creator agent runs) |
+
+No Docker, no local services, no app `.env` for ordinary work.
+
+## Bootstrap
+
+```bash
+uv sync
+task install-hooks   # pre-commit + commit-msg (commitlint)
+task --list
+```
+
+Ad-hoc Python always via uv:
+
+```bash
+uv run pytest -q
+uv run pytest tests/test_skill_contract.py -q
+uv run python scripts/sync_upstream_skills.py
+```
+
+## Common operations
+
+| Goal | Command |
+| --- | --- |
+| Full gate (same as CI) | `task ci` |
+| Contract + unit tests | `task validate` (alias: `task test`) |
+| Lint / format / secrets | `task lint` |
+| Validate skill-creator `evals/evals.json` | `task evals:validate` (optional `SKILL=name`) |
+| Run skill-creator evals via Cursor agent | `task evals` (all skills with `evals/`); `task evals SKILL=name` (one). Uses Sonnet 5 (`claude-sonnet-5-high`); override with `MODEL=…`. One agent per eval in parallel, then aggregate. |
+| Confirm skills CLI sees this path | `task verify-discovery` |
+| Dry-run as Cursor Agent Plugin | `ln -s "$(pwd)" ~/.cursor/plugins/local/systemfiles-skills` then reload Cursor |
+| Refresh vendored skills | `task sync-upstream-skills` |
+| Propose catalog from another project | `task capture-project PROJECT=/path/to/project` |
+| Install git hooks | `task install-hooks` |
+
+Prefer `task …` over inventing raw pipelines. CI runs `uv sync` then `task ci` ([ci.yml](../.github/workflows/ci.yml)).
+
+## Patterns
+
+### Adding or changing an authored skill
+
+1. Create or edit `skills/<name>/SKILL.md` with frontmatter `name` + `description`.
+2. Directory name **must** equal frontmatter `name`.
+3. `chmod +x` any new scripts under `skills/<name>/scripts/`.
+4. If the skill is part of the authored baseline, add its name to `EXPECTED_SKILLS` in `tests/test_skill_contract.py`.
+5. Put guessable agent behavior in deterministic scripts; cover from `tests/`.
+6. External I/O in evals: local fixtures/snapshots only; mocks belong in script unit tests (see `skills/issue-triage/`).
+7. `task ci`, then update `README.md` skill table if the public inventory changed.
+
+### Vendoring an upstream skill
+
+1. Add `[[skill]]` to `upstream-skills.toml` (`name`, `repo`, optional `path` / `ref`).
+2. `task sync-upstream-skills`.
+3. Commit **together**: catalog, `skills/<name>/`, `upstream-skills.lock.json`.
+4. Never hand-edit vendored trees; re-sync after catalog changes.
+
+Or generate candidates: `task capture-project PROJECT=…` (local-only installs are flagged for authored promotion, not the catalog).
+
+### Scripts and tests
+
+- Repo-level tooling: `scripts/` (sync, capture).
+- Skill-scoped helpers: `skills/<name>/scripts/`.
+- Tests live under `tests/` at the repo root (import/path against skill scripts as needed).
+- Pre-commit already runs `uv run pytest -q` as `skill-contract-tests`; still run `task ci` before review.
+
+### Docs and spelling
+
+- User-facing inventory/install: `README.md`.
+- Process/PR: `CONTRIBUTING.md`.
+- Agent map: root `AGENTS.md` → these docs.
+- cspell currently scopes to a small set of authored markdown files (see `.pre-commit-config.yaml`); don’t assume new docs are spell-checked automatically.
+
+### Secrets
+
+- Don’t commit credentials; gitleaks is in the lint gate.
+- Local development needs no secrets.
+- Scheduled upstream sync in CI needs `SYNC_UPSTREAM_PAT` (see `CONTRIBUTING.md`).
+
+### Branches and commits
+
+- Branches: `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, `chore/<topic>`.
+- Messages **and** PR titles: [Conventional Commits](https://www.conventionalcommits.org/) (`feat`, `fix`, `docs`, `chore`, …).
+- Pass pre-commit before requesting review.
+
+## Scratch vs canon
+
+| Path | Treat as |
+| --- | --- |
+| `docs/`, `README.md`, `CONTRIBUTING.md`, `AGENTS.md` | Canon |
+| `.lavish/` | Local review scratch — do not treat as process source of truth |
+| `.issue-triage/` | issue-triage clarifying Q&A / resume logs — gitignored |
+| `.scratch/pr-feedback-qa/` | pr-feedback-qa session JSON — subject-repo local state (ensure `.scratch/` gitignored) |
+| `.agents/`, `skills-lock.json` | Install artifacts — gitignored |
+| `skills/*-workspace/` | skill-creator eval run outputs — gitignored |

plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "systemfiles-skills",
+  "description": "SystemFiles agent skills catalog (authored and vendored).",
+  "version": "1.0.0",
+  "author": {
+    "name": "SystemFiles"
+  }
+}