P1: remove agents/, promote data-pipelines into skills - #7
Merged
Conversation
The 6 "agents" were never Claude Code subagents. Evidence:
- 4 of 6 (expert-coder, ml-engineer, code-review, test-engineer) had NO YAML
frontmatter, so they installed with their H1 as the entire description
("Expert Coder Agent") and were effectively untriggerable.
- All 6 installed into .claude/skills/, not .claude/agents/. discover_agents()
returned Skill objects; there was no Agent model anywhere in src/.
- agent.toml was never parsed — only a doctor check and a test asserted it
existed. The advisory/blocking field was read once, by a test.
- Both "blocking" action.yml files ran `pixi run` against a repo with no
pixi.toml (whet itself uses uv) and were referenced by no workflow.
Roughly 77% of their 3,047 lines duplicated existing skills — and because they
were written independently they diverged: test-engineer timed GPU inference
without cuda.synchronize() while skills/testing does it correctly; expert-coder
recommended logging.getLogger against the repo's own Loguru mandate.
GSD already owns agency (33 correctly-formatted subagents). whet owns domain
knowledge, and knowledge is a skill.
Promoted:
- skills/data-pipelines (481 lines) from data-engineer — storage-format matrix,
group-aware leakage-preventing splitting, schema evolution, Great Expectations.
DVC section dropped in favor of the existing dvc skill.
- skills/cv-model-selection (340 lines) from ml-engineer, rewritten for the
actual stack: RF-DETR vs YOLOX as set- vs dense-prediction, NMS-free export,
small-object regimes, tracking/re-ID, detector+crop for jersey numbers.
Salvaged before deletion:
- devops-infra decision trees -> docker-cv, kubernetes, github-actions
- test-engineer coverage thresholds + naming convention -> testing
Removed: agents/, docs/agents/, discover_agents(), --agents-only/--skills-only,
agents_dir config, doctor agent checks (renumbered 1-8), tests/test_agents.py.
34 skills, 0 agents. 202 tests pass; ruff, format, mypy --strict, and
mkdocs build --strict all clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ortizeg
changed the title
Both removed at the user's request — DVC is not part of their workflow, and cv-model-selection was not wanted. - Delete skills/dvc + docs/skills/dvc.md and skills/cv-model-selection + docs/skills/cv-model-selection.md, plus their mkdocs nav entries and docs/skills/index.md table rows. - Drop "dvc" from archetype skill lists (model-zoo, data-processing-pipeline) and from skill.toml recommends (aws-sagemaker, data-pipelines, model-evaluation) so no metadata references a missing skill. - Rewrite prose that pointed at the dvc skill. Where DVC appeared as a generic data-versioning concept, the guidance is now tool-neutral (object storage plus a versioned/content-hashed manifest) rather than naming a tool the user does not use — e.g. data-pipelines' Versioning section, model-evaluation's frozen test-set rule, onnx artifact storage, and the data-processing-pipeline and research-notebook archetypes. 32 skills. 192 tests pass; ruff, mypy --strict, and mkdocs build --strict clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ortizeg
force-pushed
the
p1-agents-to-skills
branch
from
July 23, 2026 21:08
ba5eb6f to
d758358
Compare
ortizeg
added a commit
that referenced
this pull request
Jul 24, 2026
) **Stacked on [#7](#7 — base is `p1-agents-to-skills`, so review #7 first. ## 1. Progressive disclosure Split the 21 skills over 450 lines into a thin `SKILL.md` index plus topic-organized `references/` loaded on demand. A SKILL.md loads fully into context when triggered and **stays there for the session**, so every line is a recurring token cost. Anthropic's guidance is that SKILL.md should read like a table of contents. **Always-resident lines: 14,930 → 7,122** across 32 skills, with ~10k lines relocated into **115 reference files**. Content was *relocated, not trimmed*. | Skill | Index before → after | |---|---| | onnx | 503 → 120 | | opencv | 502 → 131 | | kubernetes | 496 → 125 | | pytorch-lightning | 485 → 125 | | testing | 479 → 103 | | wandb | 477 → 121 | | gcp | 477 → 116 | | aws-sagemaker | 455 → 132 | | …13 more | all → 95–143 | Each index keeps the 80%-case patterns, conventions, and anti-patterns inline, then ends with a `## Deep dives` list giving every reference a *"read this when…"* trigger. Rules enforced: **one level deep** (no reference links to another reference), TOC on any reference over 100 lines, descriptive filenames, frontmatter byte-for-byte unchanged. ## 2. Installer support (required — otherwise the links 404) Without this, the deep-dive links would break exactly the way the external `interface-design` skill's currently do: - `Skill.references_dir` / `reference_files()` / `read_flattened()` - **Claude + Antigravity** adapters copy `references/` on install - **Cursor + Copilot** store one flat file, so references are **inlined** rather than lost ## 3. Install tiers New `tier` field in `skill.toml`. `tier = "extra"` marks a skill as opt-in, skipped unless `whet install --include-extras`. Marked extra: **aws-sagemaker, kubernetes, gradio, huggingface, mlflow** — real skills, but no evidence they're in the flagship workflow, so they no longer dilute the default trigger surface. ## 4. Documentation CLAUDE.md now documents the description formula (trigger-first, pushy, with disambiguation), the progressive-disclosure layout and its rules, and the tier system. `docs/skills/index.md` gains an Install Tiers section and marks extras. Also documents the **`interface-design` companion**: whet ships no general product-UI ruleset (`gradio` is ML demos only), so that external skill is the recommended pairing — with a note that its `references/` must be present or its deep-dive links won't resolve. ## Verification - `uv run pytest tests/` → **192 passed** - `uv run ruff check .` / `ruff format --check .` → clean - `uv run mypy src/whet/ tests/ --strict` → clean - `uv run mkdocs build --strict` → clean 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
ortizeg
added a commit
that referenced
this pull request
Jul 24, 2026
Third pillar of the library review. Skills (#6, #8) and agents (#7) were audited and fixed; the 6 archetypes had never been reviewed. An audit that actually **rendered** each one and ran the toolchain against the output found they were in worse shape than either. ## Why it went unnoticed **Nothing ever rendered an archetype in CI.** The tests checked README length and file existence — which is exactly how `cv-inference-service` shipped for months without the `fastapi` skill. Every bug below was invisible to a green build. ## What was broken **4 of 6 archetypes generated nothing.** `whet init` fell through to a 4-file stub; `model-zoo` and `research-notebook` produced *byte-identical* output apart from one description string. `research-notebook` shipped no `notebooks/` directory — the one thing its name promises. **The 2 with templates produced projects that did not run:** | Archetype | Failure | |---|---| | `pytorch-training-project` | **Zero runtime dependencies declared** — couldn't import its own entry point. Crashed on the first training step (`batch["image"]` against `FakeData`, which yields tuples). **Hydra was a required skill but entirely absent**, so documented CLI overrides silently did nothing — worse than crashing. Failed its own `ruff` gate. | | `cv-inference-service` | Named for ONNX, requires the `onnx` skill, shipped **no `onnxruntime`, no inference engine, no `/predict`** — its request/response schemas were dead code. `Dockerfile` COPY'd a `uv.lock` that doesn't exist, so `docker build` failed. | And the docs described a different product than the code: every README said `pixi`, every template said `uv`; all six listed a `pixi.toml` no template shipped. ## What this PR does **Templates: 19 files → 125.** All six now render into a project that passes its own gates. - **pytorch-training-project** — deps declared; tuple unpacking; a real `@hydra.main` driving Pydantic configs; `transforms.py` and `configs/trainer/debug.yaml` added; 13 tests including a genuine `fast_dev_run`. A *second* latent crash surfaced during verification and was fixed: the `LazyLinear` head left `configure_optimizers` iterating uninitialized params. - **cv-inference-service** — real ONNX Runtime engine, wired `/predict`, pixi-based Dockerfile, and the app starts cleanly with **no model artifact present** (covered by a test, so the suite needs no weights). - **data-processing-pipeline** — group-aware, leakage-preventing splits (split on video/match/scene, never the row) with a disjointness assertion. - **library-package** — the packaging furniture the README promised: `LICENSE`, `CHANGELOG.md`, `py.typed`, entry point. - **model-zoo** — model-card schema + **sha256-verified** weight fetch, with a test proving a corrupted file is rejected. - **research-notebook** — an actual `notebooks/` dir with a valid `.ipynb`, plus `nbstripout` so outputs stay out of git. **The guardrails are the real point:** - `tests/test_archetype_templates.py` renders every archetype through whet's **real** `render_template` and asserts the generated project has no unsubstituted placeholders, parses, passes `ruff`, **declares every package it imports**, and has src-layout + tests. That import-vs-dependency check catches the "zero dependencies declared" class of bug without installing torch. - `tests/test_archetypes.py` — archetype skills resolve to real skills, no `extra`-tier skill sits in `required`, `required` is non-empty. - New **`archetypes` CI job** running both suites. **Staleness swept** — the deleted Code Review / Test Engineer agents were still referenced in 5 archetype READMEs, `docs/archetypes/index.md`, `master-skill`, and two guides (`code-review.yml` → a plain `ci.yml`). Templates now use pixi consistently with tool-agnostic run commands; all `uv` references dropped from generated projects. ## Verification - `uv run pytest tests/` → **250 passed** - `uv run ruff check .` / `ruff format --check .` → clean - `uv run mypy src/whet/ tests/ --strict` → clean - `uv run mkdocs build --strict` → clean ## Notes for review - Deliberately **not** in this PR: further skill-composition additions the audit suggested (no archetype pulls in `pixi` despite every README opening with `pixi install`; `pydantic-ai` is referenced by zero archetypes). Kept separate to keep this diff to "make the templates work." - Each archetype still has up to three conflicting directory trees documented (archetype README vs docs page vs actual `template/`). Worth a follow-up making `template/` the single source of truth. - Two caveats from template verification: mypy on a real 3.11 interpreter can trip over current numpy stubs (`--python-version 3.12` is clean); and pixi warns that `[project]` is deprecated in favor of `[workspace]` — left as-is because `skills/pixi/SKILL.md` documents `[project]` repo-wide, so changing it should be coordinated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
ortizeg
added a commit
that referenced
this pull request
Jul 24, 2026
main carried a squash commit (7ee1eaa, 'Release v0.1.0') that was never merged back into develop, so the same files were added independently on both sides and git saw ~100 add/add conflicts. Resolved with -s ours: main's content is a strict subset of this branch, and every file present only on main is a reviewed deletion — the agents/ tree and its docs (removed in #7), skills/dvc, and skills/pydantic-strict (renamed to pydantic). Nothing unique is discarded. Recording main as a parent reconciles the histories so future develop -> main merges are clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follows #6 (merged). Result: 32 skills, 0 agents.
Why remove the agents
They were never Claude Code subagents. Four independent pieces of evidence:
expert-coder,ml-engineer,code-review,test-engineerbegan directly with an H1. They installed with the heading as their entire description (expert-coder: Expert Coder Agent) and were effectively untriggerable. The two that worked were the two that happened to have frontmatter..claude/skills/, not.claude/agents/.discover_agents()returnedSkillobjects; there was noAgentmodel anywhere insrc/.agent.tomlwas never parsed — only a doctor check and a test asserted the file existed. Theadvisory/blockingfield was read exactly once, by a test.action.ymlfiles were broken — they ranpixi runagainst a repo with nopixi.toml(whet itself uses uv), and no workflow referenced them.Content-wise ~77% of their 3,047 lines duplicated existing skills. Because they were written independently they diverged:
test-engineertimed GPU inference withoutcuda.synchronize()(meaningless) whileskills/testingdoes it correctly;expert-coderrecommendedlogging.getLoggeragainst the repo's own Loguru mandate.GSD already ships 33 correctly-formatted subagents. GSD owns agency; whet owns domain knowledge — and knowledge is a skill.
Promoted to a skill
skills/data-pipelines(481 lines) fromdata-engineer— storage-format decision matrix, group-aware leakage-preventing splitting (frames from one match must not straddle splits), schema evolution/migration, Great Expectations suites.Also removed (per review)
dvc— not part of the workflow. Removed the skill, its docs page, nav entry, archetype/skill.tomlreferences, and rewrote prose that pointed at it. Where DVC appeared as a generic data-versioning concept, the guidance is now tool-neutral (object storage plus a versioned/content-hashed manifest) rather than naming an unused tool.cv-model-selection— not wanted.Salvaged before deletion
docker-cvkubernetesgithub-actionstestingRemoved plumbing
agents/,docs/agents/,discover_agents(),--agents-only/--skills-only,agents_dirconfig, the two doctor agent checks (remaining checks renumbered 1–8),tests/test_agents.py, and the agents nav/how-to sections.Verification
uv run pytest tests/→ 192 passeduv run ruff check ./ruff format --check .→ cleanuv run mypy src/whet/ tests/ --strict→ cleanuv run mkdocs build --strict→ clean (caught and fixed dangling agent links)🤖 Generated with Claude Code