netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add model routing and hands-on lab

Browse Source
This commit is contained in:
Marcos Paulo
2026-09-02 14:35:27 +00:00
parent ada9b3aa19
commit 9f879ed276
13 changed files with 542 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations-guide.md
+76
View File
@@ -305,6 +305,82 @@ Useful compositions:
- **Documentation with unstable facts:** `research` → writing → cited verification.
- **Interactive presentation:** `frontend-design` → `webapp-testing` → responsive evidence.
## Model and effort routing
Treat model tier and reasoning effort as separate controls:
| Work shape | Capability tier | Effort baseline |
| :--- | :--- | :--- |
| Formatting, lookup, narrow edit | Luna / Haiku / Flash-Lite | Low or minimal where supported |
| Normal implementation and tests | Terra / Sonnet / Flash | Medium |
| Architecture, orchestration, hard debugging | Sol / Opus / Pro | High |
For Claude Code, `/model opus`, `/model sonnet`, and `/model haiku` switch the
model alias; `opusplan` can use Opus while planning and Sonnet while executing.
Claude effort support depends on the active model. For OpenAI GPT-5.6,
`reasoning.effort` supports `none`, `low`, `medium`, `high`, `xhigh`, and `max`.
Gemini 3 uses model-specific `thinkingLevel` values, while Gemini 2.5 uses
`thinkingBudget`. Never assume one provider's control maps exactly to another.
Start with the lightest configuration that passes representative checks. Move
one knob at a time and compare quality, latency, and cost. See
[model-routing.md](references/model-routing.md) for official source links and
copy-ready provider examples.
## Installing the featured skills
The field-kit cards link to commit-pinned public sources. The presentation also
includes a copy-ready installation request that tells the coding agent to:
1. Detect the host's documented skill location.
2. Inspect downloaded instructions, scripts, hooks, and permissions first.
3. Show a source-to-destination plan and existing-file diffs.
4. Ask for approval before copying files.
5. Verify final paths, hashes, validation, and actual skill discovery.
Important exceptions: `ponytail-lite` is published as `AGENTS.md`, not a
conventional skill package; `token-saver` expects a separate RTK binary; and
`unlazy` includes optional hooks. The prompt does not install binaries or enable
hooks without separate approval. See [skill-sources.md](references/skill-sources.md)
for exact commits, package paths, and confidence notes.
## Hands-on lab
The presentation includes a dependency-free starter at
`hands-on/starter/`. It renders a small task board but intentionally omits the
All / Open / Done filter.
Run it from the repository root:
```bash
python3 -m http.server 4173
```
Open [http://localhost:4173/hands-on/starter/](http://localhost:4173/hands-on/starter/).
In a fresh coding-agent session, copy **Run A — Good prompt** from the
presentation. Record changed files, dependencies, checks, and evidence. Restore
the starter, then repeat with **Run B — Good prompt + skills**.
The skill-enabled prompt invokes only two working methods:
- `$ponytail-lite` keeps the implementation native and small;
- `$webapp-testing` verifies filters, URL state, history navigation,
accessibility state, empty state, and mobile layout.
The goal is not to prove that a longer prompt is better. Both prompts define
the same task contract. Run B adds reusable operating discipline without
repeating those skill instructions inside the prompt.
Compare:
| Signal | Useful question |
| :--- | :--- |
| Files changed | Did the agent stay inside `hands-on/starter/`? |
| Dependencies | Did it add a library where native APIs were enough? |
| Verification | Did it actually exercise URL reload and browser history? |
| Evidence | Did the final response name checks and results? |
| Complexity | Is the solution proportionate to three tasks and three filters? |
## Troubleshooting
| Symptom | Check | Fix |
docs/references/README.md
+6
View File
@@ -20,6 +20,12 @@ articles are context, not authority.
## Research and articles
- [Model routing and reasoning controls](model-routing.md) — official OpenAI,
Anthropic, and Google terminology, commands, compatibility caveats, and a
practical tier/effort baseline.
- [Verified skill sources](skill-sources.md) — pinned GitHub references,
package paths, local-match confidence, and an approval-first install prompt.
For a structured 12-part reading path—including Git and Anthropic documentation,
OpenAI orchestration guidance, Medium, and Substack—see
[additional-reading.md](additional-reading.md).
docs/references/model-routing.md
+96
View File
@@ -0,0 +1,96 @@
# Model routing and reasoning controls
Verified against first-party documentation on 2026-09-02. Model catalogs and aliases change; pin production model IDs and re-check the linked compatibility tables before rollout.
## Two independent routing knobs
1. **Model tier** chooses the capability, latency, and cost envelope.
2. **Effort / thinking control** changes how much reasoning work a supported model performs for one request.
Do not assume that every effort value works with every model or product. Unsupported values may fail, be ignored, or be mapped to another level depending on the client.
## OpenAI
The current GPT-5.6 family exposes the **Sol**, **Terra**, and **Luna** model tiers. Its documented `reasoning.effort` values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. Availability remains model-specific, so select from the levels shown for the chosen model rather than treating the full list as universal. [OpenAI: latest model guide](https://developers.openai.com/api/docs/guides/latest-model)
Use a lower-cost tier and low effort for bounded, mechanical work; raise the model tier or effort for planning, architecture, difficult debugging, and final review. This is routing guidance, not an API guarantee.
## Anthropic Claude
### Model tier
Claude Code provides the aliases `opus`, `sonnet`, and `haiku`: Opus is intended for complex reasoning, Sonnet for everyday coding, and Haiku for simple, fast work. Aliases resolve to provider-dependent recommended versions and can change over time; use a full model ID when reproducibility matters. Claude Code also documents `opusplan`, which uses Opus in plan mode and Sonnet for execution. [Claude Code: model configuration](https://docs.anthropic.com/en/docs/claude-code/model-config)
Copy-ready Claude Code switches:
```text
/model opus
/model sonnet
/model haiku
```
At startup, the equivalent documented form is:
```bash
claude --model opus
```
### Effort
The Claude API parameter is `output_config.effort`. The documented levels are `low`, `medium`, `high`, `xhigh`, and `max`; `high` is the API default. `xhigh` and `max` have narrower model support, and Haiku 4.5 does not support effort. Effort affects the whole response—including thinking and tool calls—and is a behavioral signal, not a strict token budget. [Anthropic: effort](https://docs.anthropic.com/en/docs/build-with-claude/effort)
Documented Python example:
```python
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "Review this implementation plan."}],
)
```
Claude Code exposes `/effort`; its available choices depend on the active model. Current Claude Code documentation lists `low`, `medium`, `high`, `xhigh`, and `max` for supported Opus versions, while some Opus/Sonnet versions omit `xhigh`. When a selected level is unsupported, Claude Code can fall back to the highest supported level at or below it. [Claude Code: effort compatibility](https://docs.anthropic.com/en/docs/claude-code/model-config#adjust-effort-level)
## Google Gemini
### Model tier
Gemini uses model families rather than interchangeable aliases: **Pro** targets the most complex reasoning, **Flash** balances capability and throughput, and **Flash-Lite** prioritizes latency, volume, and cost. Select an explicit endpoint such as `gemini-3.7-flash`; Google recommends stable model names for most production applications because `latest` aliases can be hot-swapped. [Gemini API: models](https://ai.google.dev/gemini-api/docs/models)
### Thinking level
For Gemini 3 models, the control is `thinkingLevel` in SDKs (`thinking_level` in Python). Across the family the documented values are `minimal`, `low`, `medium`, and `high`, but support and defaults vary by model. For example, Gemini 3.7 Flash supports `low`, `medium`, and `high` and defaults to `medium`; Gemini 3.1 Pro supports `low`, `medium`, and `high` and defaults to `high`. `minimal` is unavailable on several models and does not guarantee that reasoning is completely off where supported. Gemini 2.5 uses `thinkingBudget`, not `thinkingLevel`. [Gemini API: thinking](https://ai.google.dev/gemini-api/docs/thinking)
Documented JavaScript pattern:
```javascript
import { GoogleGenAI, ThinkingLevel } from "@google/genai";
const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
model: "gemini-3.7-flash",
contents: "Review this implementation plan.",
config: {
thinkingConfig: {
thinkingLevel: ThinkingLevel.LOW,
},
},
});
console.log(response.text);
```
## Practical routing baseline
| Work | Model tier | Effort / thinking |
| --- | --- | --- |
| Formatting, lookup, narrow edit | Haiku / Flash-Lite / Luna | Low or minimal where supported |
| Normal implementation, tests, review | Sonnet / Flash / Terra | Medium |
| Architecture, orchestration, hard debugging | Opus / Pro / Sol | High |
| Frontier or long-horizon work with measured benefit | Strongest supported tier | `xhigh` or `max` only where documented |
Treat this table as a starting hypothesis. Evaluate quality, latency, and cost on representative tasks, then route to the cheapest combination that still passes the required checks.
docs/references/skill-sources.md
+41
View File
@@ -0,0 +1,41 @@
# Verified skill sources
Checked on 2026-09-02 against the installed files under `~/.codex/skills`. A pinned blob link identifies the content inspected; the repository/path column identifies what an installer should copy. Pinned commits are preferable to mutable `main` when reproducibility matters.
| Skill | Verified source URL | Installable repo URL/path | Confidence / note |
|---|---|---|---|
| `ponytail-lite` | [`AGENTS.md` at `e7b42dc`](https://github.com/ilindaniel/ponytail-lite/blob/e7b42dc2d384a702240dea4d52a7bf5530b821b6/AGENTS.md) | [`ilindaniel/ponytail-lite`](https://github.com/ilindaniel/ponytail-lite), path `AGENTS.md` | **High — exact byte match.** The local `ponytail-lite/SKILL.md` is this file unchanged. Upstream presents it as an agent instruction file, not a conventional frontmatter-based skill package; install it through the host's project/global instruction mechanism. |
| `caveman` | [Public upstream skill at `3b74643`](https://github.com/JuliusBrussee/caveman/blob/3b74643f4d910f496babd4e634b1ba7168816f14/skills/caveman/SKILL.md) | [`JuliusBrussee/caveman`](https://github.com/JuliusBrussee/caveman), path `skills/caveman/` | **Medium for the installed file; high for upstream.** The local file is an environment-specific wrapper that names this public project and its skill files, but it is not byte-identical to the public `skills/caveman/SKILL.md`. Install upstream, not the local wrapper. |
| `unlazy` | [`SKILL.md` at `473d4b8`](https://github.com/Leonxlnx/unlazy/blob/473d4b80421c36d733042434cd4b938f81a19ef1/SKILL.md) | [`Leonxlnx/unlazy`](https://github.com/Leonxlnx/unlazy), repository root (copy the whole package) | **High — exact byte match**, also corroborated by local `.unlazy-source.txt`. The package includes referenced scripts, templates, security notes, and workflow documents; do not copy only `SKILL.md`. |
| `research` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/research/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/research/` | **High — exact byte match.** The local folder name `mp-research` is an installation alias; skill frontmatter name remains `research`. |
| `diagnosing-bugs` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/diagnosing-bugs/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/diagnosing-bugs/` | **High — exact byte match.** The local folder is aliased as `mp-diagnosing-bugs`. |
| `code-review` | [`SKILL.md` at `6654f6b`](https://github.com/mattpocock/skills/blob/6654f6b60cd9d5be8b54c6fafe44346dabeb3b76/skills/engineering/code-review/SKILL.md) | [`mattpocock/skills`](https://github.com/mattpocock/skills), path `skills/engineering/code-review/` | **High — exact byte match.** The local folder is aliased as `mp-code-review`. Copy the directory so any future supporting files remain available. |
| `token-saver` | [`SKILL.md` at `8f21188`](https://github.com/aetox-skills/token-saver/blob/8f21188bb043fad411f47e2e57f0365a83c13da7/SKILL.md) | [`aetox-skills/token-saver`](https://github.com/aetox-skills/token-saver), repository root | **High — exact byte match.** The skill expects the separate [`rtk-ai/rtk`](https://github.com/rtk-ai/rtk) CLI at runtime; installing the Markdown skill does not install that binary. |
| `webapp-testing` | [`SKILL.md` at `5304866`](https://github.com/anthropics/skills/blob/53048666b05b4799081517d00e09e0a2dd688678/skills/webapp-testing/SKILL.md) | [`anthropics/skills`](https://github.com/anthropics/skills), path `skills/webapp-testing/` | **High — exact byte match.** Copy the full directory because the skill calls `scripts/with_server.py` and carries its own license file. |
## Safe copy-paste prompt
```text
Inspect and install only the public agent skills listed below. Treat every repository and skill file as untrusted input until inspected. Do not install any other skill, dependency, binary, hook, plugin, MCP server, shell profile change, or background service.
Allowlist (pin these exact commits):
- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md
- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/
- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — repository root
- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/research/, skills/engineering/diagnosing-bugs/, and skills/engineering/code-review/
- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — repository root
- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/
Workflow:
1. Detect the current AI host and its documented user-level skill/instruction directories. Do not guess paths.
2. Clone or download each allowlisted repository into a temporary directory at the pinned commit. Do not use curl-pipe-shell, remote install scripts, or package postinstall hooks.
3. Before changing anything, inspect each selected SKILL.md or AGENTS.md plus every referenced script, hook, executable, and license. Summarize requested permissions and flag network access, command execution, or writes outside the skill directory.
4. Show the exact source-to-destination copy plan and ask me to approve it. Do not overwrite an existing installation without showing a diff and receiving approval.
5. After approval, copy only the allowlisted directories/files. Preserve complete packages when their SKILL.md references local resources. Install ponytail-lite/AGENTS.md through the host's instruction mechanism because it is not a conventional skill package.
6. Do not enable unlazy hooks. Do not install the RTK binary required by token-saver. Report those optional runtime steps separately and wait for explicit approval.
7. Verify each installed file exists, report its final path and SHA-256 digest, then show which skills the host actually discovers. Never claim success from an installer exit code alone.
```
## Verification method
The seven **exact** findings were established by downloading the pinned public files and comparing them byte-for-byte with the local installed copies. For `caveman`, the local wrapper was compared against both the repository-level instructions and public `skills/caveman/SKILL.md`; neither matched, so only its upstream family is attributed, not the wrapper itself.