Merge pull request #702 from mhenke/issue-690-skill-reference

docs: add skill references to preset docs (#690)

README.md

@@ -166,9 +166,17 @@ The default generated configuration includes both `openai` and `opencode-go` pre
 }
 ```
 
+### Preset Docs
+
+- **[OpenAI Preset](docs/openai-preset.md)** — the default generated preset; runs all agents on OpenAI models.
+- **[OpenCode Go Preset](docs/opencode-go-preset.md)** — runs the agents on OpenCode Go models; enables the Observer agent for visual analysis since its orchestrator model isn't multimodal.
+- **[Author's Preset](docs/authors-preset.md)** — the exact config the author runs day to day, with third-party skills.
+- **[$30 Preset](docs/thirty-dollars-preset.md)** — a mixed-provider setup built around Codex Plus and GitHub Copilot Pro for about $30/month.
+- **[OpenCode Zen Free Preset](docs/opencode-zen-free-preset.md)** — every agent runs on an opencode free model; no usage cost.
+
 ### For Alternative Providers
 
-To use custom providers or a mixed-provider setup, use **[Configuration](docs/configuration.md)** for the full reference. If you want a ready-made starting point, check the **[Author's Preset](docs/authors-preset.md)** and **[$30 Preset](docs/thirty-dollars-preset.md)** - the `$30` preset is the best cheap setup.
+To use custom providers or a mixed-provider setup, use **[Configuration](docs/configuration.md)** for the full reference.
 
 ### ✅ Verify Your Setup
 

docs/authors-preset.md

@@ -118,3 +118,36 @@ This is the exact configuration the author runs day-to-day.
 }
 
 ```
+
+## Skill Reference
+
+Each skill is listed with a short description and its source. The config block above shows which agent uses it. `author` means the author's own third party skill (not part of the plugin); `public` means a public tool, framework, or MCP server.
+
+| Skill | Description | Source |
+| --- | --- | --- |
+| `*` (excl. `!make-interfaces-feel-better`) | All installed skills except those explicitly excluded | `author` |
+| `better-icons` | Icon design | `author` |
+| `ce-brainstorm` | Brainstorming workflow | `author` |
+| `codegraph` | (MCP) code graph navigation | `public` |
+| `context7` | (MCP) library docs lookup | `public` |
+| `crawl4ai` | (MCP) web crawling | `public` |
+| `customer-research` | Customer research | `author` |
+| `gh_app` | (MCP) GitHub app access | `public` |
+| `image` | Image generation/editing | `author` |
+| `make-interfaces-feel-better` | UI/UX polish | `author` |
+| `marketing-psychology` | Marketing psychology | `author` |
+| `motion` | Animation/motion design | `author` |
+| `nuxt` | Nuxt framework | `public` |
+| `pnpm` | pnpm package manager | `public` |
+| `searxng` | (MCP) metasearch engine | `public` |
+| `tsdown` | tsdown bundler | `public` |
+| `video` | Video generation/editing | `author` |
+| `vitest` | Vitest test runner | `public` |
+| `vite` | Vite build tool | `public` |
+| `vue` | Vue framework | `public` |
+| `web-perf` | Web performance optimization | `author` |
+| `websearch` | (MCP) web search | `public` |
+| `workers-best-practices` | Worker best practices | `author` |
+
+For the complete configuration reference, see [Configuration](configuration.md).
+

docs/openai-preset.md

@@ -0,0 +1,107 @@
+# OpenAI Preset
+
+`openai` is the default generated preset. The installer builds both `openai`
+and `opencode-go`; OpenAI is the one that runs unless you pick the other.
+
+## Install with OpenAI Active
+
+```bash
+bunx oh-my-opencode-slim@latest install
+```
+
+Then authenticate and refresh models:
+
+```bash
+opencode auth login
+opencode models --refresh
+```
+
+## Switch at Runtime
+
+If both presets are already in your config, switch from inside OpenCode:
+
+```text
+/preset openai
+```
+
+See [Preset Switching](preset-switching.md) for the full runtime switching
+workflow.
+
+## Bundled Model Mapping
+
+The generated `openai` preset assigns each specialist an OpenAI model:
+
+| Agent | Model |
+|-------|-------|
+| Orchestrator | `openai/gpt-5.5` (`medium`) |
+| Oracle | `openai/gpt-5.5` (`high`) |
+| Librarian | `openai/gpt-5.4-mini` (`low`) |
+| Explorer | `openai/gpt-5.4-mini` (`low`) |
+| Designer | `openai/gpt-5.4-mini` (`medium`) |
+| Fixer | `openai/gpt-5.5` (`low`) |
+
+## Generated Config Shape
+
+Your generated config includes `openai` under `presets` and activates it by
+setting the top-level `preset` field:
+
+```jsonc
+{
+  "preset": "openai",
+  "presets": {
+    "openai": {
+      "orchestrator": {
+        "model": "openai/gpt-5.5",
+        "variant": "medium",
+        "skills": ["*"],
+        "mcps": ["*", "!context7"]
+      },
+      "oracle": {
+        "model": "openai/gpt-5.5",
+        "variant": "high",
+        "skills": ["simplify"],
+        "mcps": []
+      },
+      "librarian": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "low",
+        "skills": [],
+        "mcps": ["websearch", "context7", "gh_grep"]
+      },
+      "explorer": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      },
+      "designer": {
+        "model": "openai/gpt-5.4-mini",
+        "variant": "medium",
+        "skills": [],
+        "mcps": []
+      },
+      "fixer": {
+        "model": "openai/gpt-5.5",
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      }
+    }
+  }
+}
+```
+
+## Skill Reference
+
+Each skill is listed with a short description and its source. The config block
+above shows which agent uses it. `author` means the author's own third party
+skill (not part of the plugin); `public` means a public tool, framework, or MCP
+server.
+
+| Skill | Description | Source |
+| --- | --- | --- |
+| `*` | All installed skills (wildcard) | `public` |
+| `simplify` | Code simplification | `public` |
+
+For the complete configuration reference, see
+[Configuration](configuration.md).

docs/opencode-go-preset.md

@@ -1,11 +1,10 @@
 # OpenCode Go Preset
 
-`opencode-go` is a bundled generated preset for users who want to run the
-Pantheon agents through OpenCode Go models instead of the default OpenAI setup.
+`opencode-go` runs the Pantheon agents on OpenCode Go models instead of the
+default OpenAI setup.
 
-The installer generates both `openai` and `opencode-go` presets. OpenAI stays
-active by default unless you select OpenCode Go during install or switch to it
-later.
+The installer builds both `openai` and `opencode-go`. OpenAI stays active unless
+you choose OpenCode Go at install time or switch to it later.
 
 Because the `opencode-go` preset uses GLM-5.1 for Orchestrator and GLM is not
 multimodal, installing with `--preset=opencode-go` also enables the Observer
@@ -67,13 +66,19 @@ setting the top-level `preset` field:
   "disabled_agents": [],
   "presets": {
     "opencode-go": {
-      "orchestrator": { "model": "opencode-go/glm-5.2" },
+      "orchestrator": {
+        "model": "opencode-go/glm-5.2"
+      },
       "oracle": {
         "model": "opencode-go/qwen3.7-max",
         "variant": "max"
       },
-      "librarian": { "model": "opencode-go/deepseek-v4-flash" },
-      "explorer": { "model": "opencode-go/deepseek-v4-flash" },
+      "librarian": {
+        "model": "opencode-go/deepseek-v4-flash"
+      },
+      "explorer": {
+        "model": "opencode-go/deepseek-v4-flash"
+      },
       "designer": {
         "model": "opencode-go/kimi-k2.7-code",
         "variant": "medium"
@@ -82,11 +87,21 @@ setting the top-level `preset` field:
         "model": "opencode-go/deepseek-v4-flash",
         "variant": "high"
       },
-      "observer": { "model": "opencode-go/kimi-k2.6" }
+      "observer": {
+        "model": "opencode-go/kimi-k2.6"
+      }
     }
   }
 }
 ```
 
+## Skill Reference
+
+This preset defines no per-agent `skills` or `mcps`. All agents use whatever skills are globally installed (the `*` wildcard).
+
+| Skill | Description | Source |
+| --- | --- | --- |
+| `*` | All installed skills (wildcard) | `public` |
+
 For the complete configuration reference, see
 [Configuration](configuration.md).

docs/opencode-zen-free-preset.md

@@ -0,0 +1,74 @@
+# OpenCode Zen Free Preset
+
+Every agent runs on an opencode free model; no usage cost.
+
+You need an API key for the `opencode` provider. Sign up at [OpenCode Zen](https://opencode.ai/zen) (skip billing; the free models need no balance) and connect it with `/connect`.
+
+---
+
+## The Config
+
+```jsonc
+{
+  "preset": "opencode-zen-free",
+  "presets": {
+    "opencode-zen-free": {
+      "orchestrator": {
+        "model": "opencode/hy3-free",
+        "temperature": 0.4,
+        "skills": ["*"],
+        "mcps": ["*", "!context7"]
+      },
+      "oracle": {
+        "model": "opencode/big-pickle",
+        "temperature": 0.4,
+        "variant": "max",
+        "skills": ["simplify"],
+        "mcps": []
+      },
+      "explorer": {
+        "model": "opencode/north-mini-code-free",
+        "temperature": 0.2,
+        "skills": [],
+        "mcps": []
+      },
+      "librarian": {
+        "model": "opencode/deepseek-v4-flash-free",
+        "temperature": 0.2,
+        "skills": [],
+        "mcps": ["websearch", "context7", "gh_grep"]
+      },
+      "designer": {
+        "model": "opencode/mimo-v2.5-free",
+        "temperature": 0.3,
+        "variant": "medium",
+        "skills": [],
+        "mcps": []
+      },
+      "fixer": {
+        "model": "opencode/deepseek-v4-flash-free",
+        "temperature": 0.2,
+        "variant": "high",
+        "skills": [],
+        "mcps": []
+      },
+      "observer": {
+        "model": "opencode/mimo-v2.5-free",
+        "temperature": 0.2,
+        "variant": "low",
+        "skills": [],
+        "mcps": []
+      }
+    }
+  }
+}
+```
+
+## Skill Reference
+
+| Skill | Description | Source |
+| --- | --- | --- |
+| `*` | All installed skills (wildcard) | `public` |
+| `simplify` | Code simplification | `public` |
+
+For the complete configuration reference, see [Configuration](configuration.md).

docs/thirty-dollars-preset.md

@@ -1,8 +1,8 @@
 # $30 Preset
 
-This preset is for people who want a strong setup built around **Codex Plus ($20/month)** and **GitHub Copilot Pro ($10/month)**.
+This preset pairs **Codex Plus ($20/month)** with **GitHub Copilot Pro ($10/month)**.
 
-It uses Codex Plus for the OpenAI models and GitHub Copilot for the premium design models, giving you a mixed-provider setup for about **$30/month total**.
+Codex Plus covers the OpenAI models and Copilot covers the design models, so you get a mixed-provider setup for about **$30/month total**.
 
 ---
 
@@ -22,3 +22,11 @@ It uses Codex Plus for the OpenAI models and GitHub Copilot for the premium desi
     }
   }
 ```
+
+## Skill Reference
+
+| Skill | Description | Source |
+| --- | --- | --- |
+| `*` | All installed skills (wildcard) | `public` |
+
+For the complete configuration reference, see [Configuration](configuration.md).