@simpleapps-com/augur-skills 2026.4.9 → 2026.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "2026.04.9",
+  "version": "2026.04.11",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/augur-api/SKILL.md

@@ -25,9 +25,9 @@ All 5 data tools (`augur_list`, `augur_get`, `augur_create`, `augur_update`, `au
 
 Always start with discovery:
 
-1. `augur_sites()` — see which sites are configured and which is default
-2. `augur_discover()` — lists all available services
-3. `augur_discover(service="<name>")` — lists endpoints for a specific service
+1. `augur_sites()`: see which sites are configured and which is default
+2. `augur_discover()`: lists all available services
+3. `augur_discover(service="<name>")`: lists endpoints for a specific service
 4. Use data tools for CRUD, passing `site` when targeting a non-default site
 
 Do NOT hardcode service names or endpoints. Use `augur_discover` to find them at runtime.
@@ -38,10 +38,10 @@ Credentials resolve automatically from `.simpleapps/` directories.
 
 Resolution order (first match wins):
 
-1. **Env vars** — `AUGUR_TOKEN` + `AUGUR_SITE_ID`
-2. **Explicit file** — `AUGUR_CREDS_FILE` env var pointing to a JSON file
-3. **Project file** — `<cwd>/.simpleapps/augur-api.json`
-4. **Global file** — `~/.simpleapps/augur-api.json`
+1. **Env vars**: `AUGUR_TOKEN` + `AUGUR_SITE_ID`
+2. **Explicit file**: `AUGUR_CREDS_FILE` env var pointing to a JSON file
+3. **Project file**: `<cwd>/.simpleapps/augur-api.json`
+4. **Global file**: `~/.simpleapps/augur-api.json`
 
 Project and global files are merged (project takes precedence).
 
@@ -67,9 +67,9 @@ Project and global files are merged (project takes precedence).
 
 Documentation hub: https://augur-api.info/
 
-- **Service directory** — https://items.augur-api.com/llms.txt lists all available services
-- **Per-service docs** — `https://{service}.augur-api.com/llms.txt` (LLM-friendly), `/openapi.json`, `/postman.json`, `/endpoints.jsonl`
-- **FAQ for agents** — https://augur-api.info/faq.md (auth, pagination, rate limits)
+- **Service directory**: https://items.augur-api.com/llms.txt lists all available services
+- **Per-service docs**: `https://{service}.augur-api.com/llms.txt` (LLM-friendly), `/openapi.json`, `/postman.json`, `/endpoints.jsonl`
+- **FAQ for agents**: https://augur-api.info/faq.md (auth, pagination, rate limits)
 
 Services include items, pricing, commerce, orders, customers, payments, shipping, open-search, and more. Use `augur_discover` at runtime rather than hardcoding service names.
 
@@ -79,3 +79,13 @@ If tools return authentication errors:
 - Check for `.simpleapps/augur-api.json` in the project directory or home directory
 - Verify the file contains valid credentials (single-site or multi-site format)
 - Fallback: set `AUGUR_TOKEN` and `AUGUR_SITE_ID` env vars
+
+## When the MCP Server Is Unavailable
+
+If `augur_*` tools are not present in the toolset (server not configured) or every call returns connection errors:
+
+1. Stop trying. Repeated calls will keep failing.
+2. Tell the user the Augur API MCP is unavailable and ask whether to (a) fix it, (b) skip the data check, or (c) use a different approach (e.g., reading data directly from the codebase, asking the user for the value)
+3. MUST NOT fabricate API responses or guess at data the API would have returned
+
+There is no documented HTTP fallback. The MCP server holds the credential and routing logic. If the MCP is down, that path is closed for this session.

package/skills/simpleapps/augur-packages/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: augur-packages
-description: Shared npm packages under @simpleapps-com/augur-*. Directs agents to check installed packages before writing custom code. This skill is a starting point — always read the actual package code for current API surface.
+description: Shared npm packages under @simpleapps-com/augur-*. Directs agents to check installed packages before writing custom code. This skill is a starting point; always read the actual package code for current API surface.
 allowed-tools:
   - Read
   - Glob
@@ -11,7 +11,7 @@ allowed-tools:
 
 ## Custom code is a liability. Shared code is an asset.
 
-Every line of custom site code carries maintenance cost — it must be understood, tested, and updated by whoever touches it next. Shared packages are the opposite: maintained once, benefiting every site. When you write custom code that a package already handles, you are adding a liability. When you adopt a package export, you are removing one.
+Every line of custom site code carries maintenance cost: it must be understood, tested, and updated by whoever touches it next. Shared packages are the opposite: maintained once, benefiting every site. When you write custom code that a package already handles, you are adding a liability. When you adopt a package export, you are removing one.
 
 This means: always prefer package solutions over custom code. When no package solution exists but the code would benefit other sites, suggest it as a package addition. The goal is to shrink the liability (custom code) and grow the asset (shared packages) over time.
 
@@ -25,23 +25,23 @@ This skill is a **stub, not an archive**. New packages are created, existing pac
 
 **Always read the installed packages' documentation in `node_modules/`:**
 
-1. Use `Glob("repo/node_modules/@simpleapps-com/*")` to discover ALL available packages — there may be packages not listed here
-2. Read `repo/node_modules/@simpleapps-com/<package>/llms.txt` — machine-readable, lists every export with descriptions and usage examples. This is the fastest path to discovering what exists.
+1. Use `Glob("repo/node_modules/@simpleapps-com/*")` to discover ALL available packages. There may be packages not listed here.
+2. Read `repo/node_modules/@simpleapps-com/<package>/llms.txt`, which is machine-readable and lists every export with descriptions and usage examples. This is the fastest path to discovering what exists.
 3. Read `repo/node_modules/@simpleapps-com/<package>/README.md` for full API docs, code examples, and "Replaces" guidance
-4. MUST NOT read `dist/`, `.d.ts`, or compiled JS files to discover capabilities — they are minified, chunked, and incomplete. The README and llms.txt are the source of truth.
+4. MUST NOT read `dist/`, `.d.ts`, or compiled JS files to discover capabilities. They are minified, chunked, and incomplete. The README and llms.txt are the source of truth.
 
 When this skill and the installed docs disagree, **the installed docs win**. This skill exists to point you in the right direction, not to replace reading the docs.
 
 ## Known Packages
 
-These are starting hints — not a complete list. Always check `node_modules/@simpleapps-com/` for the full set.
+These are starting hints, not a complete list. Always check `node_modules/@simpleapps-com/` for the full set.
 
 | Package | Purpose |
 |---------|---------|
 | `augur-utils` | Types, formatters, cache config, Valibot schemas. Zero framework dependencies. |
 | `augur-web` | shadcn/Radix UI components. Per-component entry points. |
 | `augur-hooks` | React Query hooks and Zustand stores. Cross-platform. |
-| `augur-server` | Server-side utilities for Next.js — Redis caching, auth factory, query client. |
+| `augur-server` | Server-side utilities for Next.js: Redis caching, auth factory, query client. |
 | `augur-tailwind` | Tailwind v4 CSS theme. No config file needed. |
 
 ## How to Check for Package Solutions
@@ -62,33 +62,33 @@ If llms.txt shows a relevant export, read the README for full API, code examples
 
 ### Step 3: MUST NOT grep compiled output
 
-MUST NOT read or grep `dist/`, `.d.ts`, `.js`, or any compiled files to discover package capabilities. These are minified build artifacts — unreliable for discovery. The README and llms.txt are the ONLY source of truth.
+MUST NOT read or grep `dist/`, `.d.ts`, `.js`, or any compiled files to discover package capabilities. These are minified build artifacts, unreliable for discovery. The README and llms.txt are the ONLY source of truth.
 
 ### Step 4: Before filing a package issue
 
 Before creating an issue on `simpleapps-com/augur-packages` requesting a new feature:
 1. Search ALL package llms.txt files for the function/hook name
 2. Search ALL package README.md files for the concept
-3. If found, the problem is site adoption — not a package gap. Use the existing export.
+3. If found, the problem is site adoption, not a package gap. Use the existing export.
 
 ### Step 5: Before writing custom code
 
 Before creating a custom hook, utility, or action in a site:
 1. Search ALL package llms.txt files for similar functionality
 2. Check the augur-hooks README "Examples" section for the pattern
-3. If a package export exists, use it. If it does not work as expected, file a bug on the package — not a reimplementation in the site.
+3. If a package export exists, use it. If it does not work as expected, file a bug on the package, not a reimplementation in the site.
 
 ## What Stays Site-Specific
 
 MUST NOT be replaced by packages:
-- **Server actions** (`"use server"`) — site-specific business logic
-- **Layout components** (Header, Footer, MainMenu) — brand-specific
-- **Domain components** (ProductItem, CartTable, CategoryCard) — compose UI primitives
-- **Auth callbacks** — injected into package auth factory
-- **Cart mutation callbacks** — depend on site-specific server actions
-- **CSS variable overrides** — brand colors, fonts, radius
-- **next.config** — image domains, redirects, security headers
-- **Site integrations** — GA4, Maps, reCAPTCHA
+- **Server actions** (`"use server"`): site-specific business logic
+- **Layout components** (Header, Footer, MainMenu): brand-specific
+- **Domain components** (ProductItem, CartTable, CategoryCard): compose UI primitives
+- **Auth callbacks**: injected into package auth factory
+- **Cart mutation callbacks**: depend on site-specific server actions
+- **CSS variable overrides**: brand colors, fonts, radius
+- **next.config**: image domains, redirects, security headers
+- **Site integrations**: GA4, Maps, reCAPTCHA
 
 ## Suggest Package Improvements
 
@@ -102,7 +102,7 @@ The goal is to grow the packages over time so sites write less custom code.
 
 ## augur-doctor
 
-`augur-doctor` ships with `@simpleapps-com/augur-config`. It checks version alignment, latest versions, and platform standard conformance. Run via `pnpm augur-doctor .` from the site directory — pre-approved, no permission prompt. For full documentation, see the augur-packages wiki page `guide-site-assessment.md` (use the cross-project wiki path from `simpleapps:wiki`).
+`augur-doctor` ships with `@simpleapps-com/augur-config`. It checks version alignment, latest versions, and platform standard conformance. Run via `pnpm augur-doctor .` from the site directory (pre-approved, no permission prompt). For full documentation, see the augur-packages wiki page `guide-site-assessment.md` (use the cross-project wiki path from `simpleapps:wiki`).
 
 ## Platform Standards
 

package/skills/simpleapps/basecamp/SKILL.md

@@ -29,7 +29,7 @@ This opens the browser for OAuth, user clicks "Allow", credentials are saved aut
 
 The `basecamp` MCP server is bundled with this plugin and starts automatically. API reference: https://github.com/basecamp/bcx-api
 
-All tools are available as `mcp__plugin_simpleapps_basecamp__*`. The tool names and parameters are self-documenting via the MCP schema — do not hardcode tool signatures. Key tool groups: projects, people, todos, comments, todo lists, messages, documents, calendar events, topics, attachments/uploads, activity, access management, stars, forwards.
+All tools are available as `mcp__plugin_simpleapps_basecamp__*`. The tool names and parameters are self-documenting via the MCP schema. Do not hardcode tool signatures. Key tool groups: projects, people, todos, comments, todo lists, messages, documents, calendar events, topics, attachments/uploads, activity, access management, stars, forwards.
 
 **Note**: The BCX API does not have a search endpoint. To find content, use `list_topics(project_id)` to browse, or `list_messages(project_id)` for messages. For cross-project browsing, use `list_topics()` (no project_id) to get recent topics across all projects.
 
@@ -43,9 +43,9 @@ A URL like `https://basecamp.com/2805226/projects/18932786/todos/514631271` give
 
 Attachments can be on todos, comments, messages, or uploads. To retrieve them:
 
-1. **Discover**: Call `get_todo` or `get_message` — attachments appear with IDs in both the top-level section and within individual comments
+1. **Discover**: Call `get_todo` or `get_message`. Attachments appear with IDs in both the top-level section and within individual comments.
 2. **Inspect** (optional): Call `get_attachment(project_id, attachment_id)` to see metadata, size, content type, and download URL
-3. **Download**: Call `download_attachment(project_id, attachment_id)` — saves to `~/.simpleapps/downloads/{project_id}/`
+3. **Download**: Call `download_attachment(project_id, attachment_id)`. Saves to `~/.simpleapps/downloads/{project_id}/`.
 4. **Read**: Use the `Read` tool on the local file path to view content (works for images, PDFs, Excel, text)
 
 To browse all attachments in a project, use `list_attachments(project_id)`.
@@ -74,9 +74,9 @@ If the MCP server is unavailable (credentials expired, server not running), use
 | Todo lists | `/projects/<project_id>/todolists` |
 | Documents | `/projects/<project_id>/documents` |
 
-**Me** page (`/people/<person_id>`) — open to-dos (~45+ shows a "See all X open to-dos" link, YOU MUST click it). The full list is at `/people/<person_id>/outstanding_todos`.
+**Me** page (`/people/<person_id>`): open to-dos (~45+ shows a "See all X open to-dos" link, YOU MUST click it). The full list is at `/people/<person_id>/outstanding_todos`.
 
-**JSON API via Chrome**: Navigate to `/api/v1/projects/<project_id>/todos/<todo_id>.json` then use `get_page_text`. WebFetch will NOT work — Chrome carries session cookies.
+**JSON API via Chrome**: Navigate to `/api/v1/projects/<project_id>/todos/<todo_id>.json` then use `get_page_text`. WebFetch will NOT work; Chrome carries session cookies.
 
 ## Tips
 

package/skills/simpleapps/bash-simplicity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bash-simplicity
-description: Bash command conventions — one command per call, use dedicated tools over shell equivalents, check wiki for approved commands. Load this skill before running Bash commands.
+description: Bash command conventions. One command per call, use dedicated tools over shell equivalents, check wiki for approved commands. Load this skill before running Bash commands.
 user-invocable: false
 ---
 
@@ -8,13 +8,13 @@ user-invocable: false
 
 ## Why This Matters
 
-A complex command feels efficient — do more in one call. But the more complex the command, the higher the probability it triggers a permission prompt. A permission prompt blocks the agent until the user responds. If the user doesn't see it for an hour, that hour is lost.
+A complex command feels efficient: do more in one call. But the more complex the command, the higher the probability it triggers a permission prompt. A permission prompt blocks the agent until the user responds. If the user doesn't see it for an hour, that hour is lost.
 
-**Simple commands are faster than complex ones because they never wait for a human.** Ten simple commands that execute instantly are faster than one complex command that waits an hour for approval. The agent's goal is to complete work — a blocked prompt completes nothing.
+**Simple commands are faster than complex ones because they never wait for a human.** Ten simple commands that execute instantly are faster than one complex command that waits an hour for approval. The agent's goal is to complete work; a blocked prompt completes nothing.
 
 The entire plugin system exists to remove the user as the bottleneck. Every permission prompt puts them back in the critical path.
 
-**Three tiers of execution speed — always use the highest tier available:**
+**Three tiers of execution speed. Always use the highest tier available:**
 
 | Tier | Method | Speed | Example |
 |------|--------|-------|---------|
@@ -26,7 +26,7 @@ Prefer tier 1 over tier 2. Use tier 2 only when no dedicated tool exists. NEVER
 
 ## The Bash Tool Is Not a Terminal
 
-The Bash tool is a managed environment, not a raw shell. It already captures stdout, stderr, and the exit code automatically. There is NEVER a reason to add shell plumbing — every shell operator triggers a permission prompt that blocks the user for zero benefit.
+The Bash tool is a managed environment, not a raw shell. It already captures stdout, stderr, and the exit code automatically. There is NEVER a reason to add shell plumbing. Every shell operator triggers a permission prompt that blocks the user for zero benefit.
 
 **If the Bash tool already does it, do not do it yourself:**
 
@@ -39,7 +39,7 @@ The Bash tool is a managed environment, not a raw shell. It already captures std
 | Pass output to another command | Write to a tmp file | `$(...)`, backticks |
 | Run inline code | Use Read/Grep/Edit tools | `node -e`, `python -c` |
 
-**One command per Bash call. No operators. No plumbing. If the command has a `;`, `&&`, `|`, `$()`, `2>&1`, or `2>/dev/null` in it — it is wrong.**
+**One command per Bash call. No operators. No plumbing. If the command has a `;`, `&&`, `|`, `$()`, `2>&1`, or `2>/dev/null` in it, it is wrong.**
 
 ## Use Dedicated Tools
 
@@ -55,10 +55,10 @@ Dedicated tools are faster, require no permission, and produce better output. MU
 
 Reserve Bash for commands that have no dedicated tool equivalent: build tools, test runners, git, package managers, and system commands.
 
-These commands are **denied** in project settings and will always be rejected — do not attempt them:
+These commands are **denied** in project settings and will always be rejected. Do not attempt them:
 `cd`, `cat`, `grep`, `rg`, `find`, `sed`, `awk`, `head`, `tail`, `sleep`, `kill`, `pkill`
 
-MUST NOT use `node -e` or `python -c` to run inline scripts — these trigger permission prompts. If you need to read a file, use the Read tool. If you need to process data, do it in your response, not in a shell script.
+MUST NOT use `node -e` or `python -c` to run inline scripts. These trigger permission prompts. If you need to read a file, use the Read tool. If you need to process data, do it in your response, not in a shell script.
 
 ## Background Tasks
 
@@ -68,7 +68,7 @@ When you start a background task with `run_in_background`, you receive a task ID
 - **Check output**: use `TaskGet` or `Read` on the output file
 - **List running tasks**: use `TaskList`
 
-MUST NOT use `kill` or `pkill` to stop background tasks — these are denied and will fail. Use `TaskStop` instead — it cleanly shuts down the process and updates internal tracking.
+MUST NOT use `kill` or `pkill` to stop background tasks. These are denied and will fail. Use `TaskStop` instead. It cleanly shuts down the process and updates internal tracking.
 
 If a process was started **outside your session** (by the user in a terminal), you cannot stop it with `TaskStop`. Ask the user to restart or stop it themselves.
 
@@ -76,15 +76,15 @@ If a process was started **outside your session** (by the user in a terminal), y
 
 When a dev server fails with EADDRINUSE, a process from a previous session is occupying the port. Follow this sequence:
 
-1. Check `TaskList` — if the task is listed, use `TaskStop`
-2. If `TaskList` is empty, the process is from outside your session — ask the user: "Port N is in use by a process from a previous session. Can you stop it?"
-3. MUST NOT attempt `kill`, `pkill`, or ask for permission to kill — these are denied and waste turns
+1. Check `TaskList`. If the task is listed, use `TaskStop`.
+2. If `TaskList` is empty, the process is from outside your session. Ask the user: "Port N is in use by a process from a previous session. Can you stop it?"
+3. MUST NOT attempt `kill`, `pkill`, or ask for permission to kill. These are denied and waste turns.
 
 Do not retry the server start until the user confirms the port is free.
 
 ## Cross-Project Searching
 
-When looking at another project's code, use dedicated tools with the project path — MUST NOT use shell commands:
+When looking at another project's code, use dedicated tools with the project path. MUST NOT use shell commands.
 
 Wrong: `find {path}/repo -name "*.ts" -exec grep -l "pattern" {} \; 2>/dev/null | head -10`
 Right: `Grep(pattern: "pattern", path: "{path}/repo", glob: "*.ts")`
@@ -92,10 +92,20 @@ Right: `Grep(pattern: "pattern", path: "{path}/repo", glob: "*.ts")`
 Wrong: `ls {path}/repo/src/components/`
 Right: `Glob(pattern: "{path}/repo/src/components/**/*")`
 
-All project paths are known and predictable (see `simpleapps:wiki` Cross-Project Wiki Access). MUST NOT search the filesystem with `find` or download from the internet — just use the dedicated tool with the known path.
+All project paths are known and predictable (see `simpleapps:wiki` Cross-Project Wiki Access). MUST NOT search the filesystem with `find` or download from the internet. Just use the dedicated tool with the known path.
+
+## Subagent Responsibility
+
+Subagents do NOT inherit this skill. They see only the prompt you give them. The primary agent MUST brief every subagent on bash-simplicity before delegating shell work, and owns the output that comes back.
+
+Every subagent prompt that touches Bash MUST include a one-liner: "One command per Bash call. No operators. Use dedicated tools (Read, Grep, Glob, Edit, Write) over shell equivalents."
+
+If a subagent returns a command containing any forbidden operator (see the table above), that is the primary agent's failure. Reject and ask for a re-plan, or translate into separate simple calls. Do not execute it. A subagent violating this is running on a stale prompt; fix the prompt.
+
+Parallel subagents each need their own briefing.
 
 ## Check Before Prompting
 
 Before running a command that will trigger a permission prompt, check the wiki and project settings for approved commands. The wiki documents which commands are pre-approved and how to invoke them. Unnecessary permission prompts interrupt the user's flow.
 
-**`pnpm:*` is pre-approved** — any command in `package.json` scripts runs without permission via `pnpm <script>`. If a tool needs to run repeatedly (linters, formatters, test runners), it SHOULD be a `package.json` script so it can run via pnpm without prompting. Suggest adding missing scripts when you notice the gap.
+**`pnpm:*` is pre-approved**: any command in `package.json` scripts runs without permission via `pnpm <script>`. If a tool needs to run repeatedly (linters, formatters, test runners), it SHOULD be a `package.json` script so it can run via pnpm without prompting. Suggest adding missing scripts when you notice the gap.

package/skills/simpleapps/claude-code-docs/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools:
 
 ## Entry Points
 
-- **Doc index**: https://code.claude.com/docs/llms.txt — fetch first, find relevant page URL, then fetch that page
-- **Full content**: https://code.claude.com/docs/llms-full.txt — large, use when broad context is needed
+- **Doc index**: https://code.claude.com/docs/llms.txt. Fetch first, find relevant page URL, then fetch that page.
+- **Full content**: https://code.claude.com/docs/llms-full.txt. Large, use when broad context is needed.
 
-IMPORTANT: YOU MUST start from `llms.txt` for current URLs. Doc pages are renamed and reorganized with each release — never rely on memorized URLs.
+IMPORTANT: YOU MUST start from `llms.txt` for current URLs. Doc pages are renamed and reorganized with each release. Never rely on memorized URLs.

package/skills/simpleapps/context-efficiency/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 # Context Efficiency
 
-Always-loaded content (CLAUDE.md, rules without `paths`) is paid on every prompt — even when irrelevant. Every token spent here is a token taken from working context. Write always-loaded content as pointers, not content.
+Always-loaded content (CLAUDE.md, rules without `paths`) is paid on every prompt, even when irrelevant. Every token spent here is a token taken from working context. Write always-loaded content as pointers, not content.
 
 ## Context Loading Hierarchy
 
@@ -25,17 +25,17 @@ Always-loaded content (CLAUDE.md, rules without `paths`) is paid on every prompt
 - **Skill descriptions**: 2% of context window for all skills combined (16K char fallback). Override with `SLASH_COMMAND_TOOL_CHAR_BUDGET`.
 - **SKILL.md**: under 500 lines. Move detail to supporting files.
 - **Auto memory**: first 200 lines of MEMORY.md loaded. Topic files on demand.
-- **Overhead**: ~31% of a 200K context window is consumed by system prompt, tools, and autocompact buffer before you type anything.
+- **Overhead**: a meaningful share of the context window is consumed by system prompt, tool definitions, and autocompact buffer before you type anything. The exact percentage depends on which MCP servers and tools are loaded. Run `/context` to see the current breakdown.
 
 ## Evergreen Content
 
-Always-loaded content MUST be evergreen — true regardless of when it's read. MUST NOT contain:
+Always-loaded content MUST be evergreen, true regardless of when it's read. MUST NOT contain:
 
-- **File counts or lists** — "12 skills" becomes wrong the next commit. Say "check `ls plugins/simpleapps/skills/`" instead.
-- **Version numbers** — "currently v2026.03.8" is stale immediately. Point to the VERSION file.
-- **Process data** — timestamps, recent activity, who did what. That's git history.
+- **File counts or lists**: "12 skills" becomes wrong the next commit. Say "check `ls plugins/simpleapps/skills/`" instead.
+- **Version numbers**: "currently v2026.03.8" is stale immediately. Point to the VERSION file.
+- **Process data**: timestamps, recent activity, who did what. That's git history.
 - **Hardcoded paths** that change across machines or environments.
-- **Content that duplicates the code** — the code is the source of truth. Describe the pattern, link to the file.
+- **Content that duplicates the code**: the code is the source of truth. Describe the pattern, link to the file.
 
 Instead: describe the **pattern**, give **1-2 examples**, and **link** to the source for the current state.
 
@@ -44,7 +44,7 @@ Instead: describe the **pattern**, give **1-2 examples**, and **link** to the so
 Always-loaded files SHOULD be pointers that invoke on-demand content:
 
 ```markdown
-# Git Safety (rule — 3 lines, always loaded)
+# Git Safety (rule, 3 lines, always loaded)
 MUST NOT commit without user approval.
 Load Skill("git-safety") for full guardrails.
 ```
@@ -53,7 +53,7 @@ The rule costs ~40 tokens per prompt. The skill costs nothing until invoked, the
 
 ### Wiki Links: Highest-ROI Pointer
 
-The cheapest pointer with the biggest payoff is a **wiki link in CLAUDE.md**. A link like `[Deployment](../../wiki/Deployment.md)` costs ~15 tokens but gives the agent instant access to a full page of detailed knowledge (~500-2000 tokens) on demand. CLAUDE.md SHOULD link to every wiki content page — it becomes the agent's table of contents. Missing a link means the agent must guess where to find information or ask the user.
+The cheapest pointer with the biggest payoff is a **wiki link in CLAUDE.md**. A link like `[Deployment](../../wiki/Deployment.md)` costs ~15 tokens but gives the agent instant access to a full page of detailed knowledge (~500-2000 tokens) on demand. CLAUDE.md SHOULD link to every wiki content page; it becomes the agent's table of contents. Missing a link means the agent must guess where to find information or ask the user.
 
 ## When to Use Each Layer
 

package/skills/simpleapps/conventional-commits/SKILL.md

@@ -19,8 +19,8 @@ Spec: https://www.conventionalcommits.org/en/v1.0.0/
 
 ## Types
 
-- `feat` — new feature (SemVer MINOR)
-- `fix` — bug fix (SemVer PATCH)
+- `feat`: new feature (SemVer MINOR)
+- `fix`: bug fix (SemVer PATCH)
 - Also permitted: `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`
 
 ## Rules

package/skills/simpleapps/deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deployment
-description: Project deployment conventions — reads the wiki Deployment page and executes submit, deploy, or publish steps. Refuses to operate without a Deployment page.
+description: Project deployment conventions. Reads the wiki Deployment page and executes submit, deploy, or publish steps. Refuses to operate without a Deployment page.
 user-invocable: false
 allowed-tools:
   - Read
@@ -8,15 +8,13 @@ allowed-tools:
   - Grep
   - Bash
   - Skill(git-safety)
-  - Skill(conventional-commits)
-  - Skill(github)
 ---
 
-First, use Skill("git-safety") to load git guardrails.
+First, use Skill("git-safety") to load git guardrails. The shipping commands (`/submit`, `/deploy`, `/publish`) load `conventional-commits` and `github` directly when they need them. This skill does not pre-load them.
 
 # Deployment
 
-This skill reads the project's `wiki/Deployment.md` and executes the steps defined there. Each project defines its own deployment workflow — this skill is the executor, the wiki is the config.
+This skill reads the project's `wiki/Deployment.md` and executes the steps defined there. Each project defines its own deployment workflow. This skill is the executor, the wiki is the config.
 
 ## Deployment Page Format
 
@@ -39,22 +37,32 @@ Not all projects need all three. Client sites may only have Submit and Deploy. P
 
 1. Read `wiki/Deployment.md`
 2. Find the section matching the requested action (Submit, Deploy, or Publish)
-3. If the page or section is missing, **refuse to operate** — tell the user to run `/curate-wiki` to generate it
+3. If the page or section is missing, **refuse to operate**. Tell the user to run `/curate-wiki` to generate it.
 4. Execute the steps in that section
 
 ## Command approval model
 
 The user invoking a command IS the approval to execute all its steps, including git writes. Do not stop to ask for confirmation mid-execution.
 
-- `/submit` — execute all steps (commit, push, PR). Report at the end.
-- `/deploy` — execute all steps. Report at the end.
-- `/publish` — **EXCEPTION**: must complete the verification gate below and get secondary confirmation BEFORE executing any publish steps. This is the only command that pauses for approval.
+- `/submit`: execute all steps (commit, push, PR). Report at the end.
+- `/deploy`: execute all steps. Report at the end.
+- `/publish`: **EXCEPTION**. Must complete the verification gate below and get secondary confirmation BEFORE executing any publish steps. This is the only command that pauses for approval.
 
 ## Guard Rails
 
 - **If `wiki/Deployment.md` does not exist, STOP IMMEDIATELY.** Do not guess, do not improvise, do not infer steps from the codebase. Tell the user to run `/curate-wiki` to generate it. Then do nothing else.
-- **If the relevant section (Submit, Deploy, or Publish) is missing from the page, STOP IMMEDIATELY.** Same rule — do not guess the steps.
-- MUST NOT guess deployment steps — only execute what the wiki defines
+- **If the relevant section (Submit, Deploy, or Publish) is missing from the page, STOP IMMEDIATELY.** Same rule: do not guess the steps.
+- MUST NOT guess deployment steps. Only execute what the wiki defines.
+
+## Translating Wiki Shell Commands
+
+Wiki Deployment pages often contain shell snippets written for humans, e.g. `pnpm typecheck && pnpm test` or `git add -A; git commit -m "..."`. These violate `simpleapps:bash-simplicity` (no `&&`, `;`, `|`, `$()`).
+
+When a wiki step uses shell operators, you MUST translate it into separate, single-command Bash calls. The wiki defines **what** to run; `bash-simplicity` defines **how** to run it. Both rules stand. One does not override the other.
+
+Example: wiki says `pnpm typecheck && pnpm test` → make two Bash calls: `pnpm typecheck`, then `pnpm test`. If the first fails, stop and report. Do not run the second.
+
+Translation does NOT mean skipping or reordering the wiki's logic. It means executing the same operations through compliant tool calls. If a wiki step truly requires a compound operation that cannot be split (rare), flag it and ask the user before proceeding.
 
 ## Publish Verification Gate
 
@@ -66,4 +74,4 @@ Before executing any Publish steps, MUST:
 4. Present a summary: version transition, commit count, test status
 5. Require the user to **explicitly confirm** the specific version going to production
 
-This is not just git-safety. It is an active verification checklist — the user MUST see exactly what they are releasing and confirm that specific version.
+This is not just git-safety. It is an active verification checklist. The user MUST see exactly what they are releasing and confirm that specific version.

package/skills/simpleapps/fyxer/SKILL.md

@@ -7,10 +7,12 @@ description: Fyxer AI meeting recording integration. Covers extraction, local ca
 
 Fyxer AI records and summarizes meetings. Use the `/fyxer` command to process recordings end-to-end.
 
+**Platform**: macOS only. The extraction flow uses `pbpaste` for clipboard reads. On Linux/Windows the command will fail at the clipboard step. There is no portable fallback yet.
+
 ## Key Conventions
 
 - **Recording URL**: `https://app.fyxer.com/call-recordings/<meeting-uuid>:<calendar-event-id>`
-- **Cache location**: `~/.simpleapps/fyxer/<meeting-uuid>/` — contains `summary.txt`, `transcript.txt`, `message.txt`
+- **Cache location**: `~/.simpleapps/fyxer/<meeting-uuid>/` contains `summary.txt`, `transcript.txt`, `message.txt`
 - **Use only the meeting UUID** (before the colon) for cache folders, duplicate checks, and frontmatter
 - **Fyxer Index**: a `Fyxer Index` document in each Basecamp project for duplicate detection. One line per posted meeting, newest first: `<meeting-uuid> | <date> | <message-id> | <subject>`
 - **Post format**: plain text with YAML frontmatter (meeting, date, time, participants, topics, fyxer-id) followed by the full transcript
@@ -18,11 +20,11 @@ Fyxer AI records and summarizes meetings. Use the `/fyxer` command to process re
 
 ## Dependencies
 
-- `simpleapps:basecamp` skill — MCP tools for posting and index management
-- Chrome browser automation — for extraction when cache is empty
+- `simpleapps:basecamp` skill: MCP tools for posting and index management
+- Chrome browser automation: for extraction when cache is empty
 
 ## Finding Posted Transcripts
 
 - Check the index: `list_documents(project_id)` then find `Fyxer Index` then `get_document`
 - View a specific transcript: `get_message(project_id, message_id)` using the message_id from the index
-- Browse all messages: `list_messages(project_id)` — Fyxer posts use the title format `Fyxer: YYYY-MM-DD`
+- Browse all messages: `list_messages(project_id)`. Fyxer posts use the title format `Fyxer: YYYY-MM-DD`.

package/skills/simpleapps/git-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-safety
-description: Git safety guardrails — MUST NOT commit, push, create PRs, or merge without explicit user approval. Load this skill before any git write operations.
+description: Git safety guardrails. MUST NOT commit, push, create PRs, or merge without explicit user approval. Load this skill before any git write operations.
 user-invocable: false
 ---
 
@@ -10,20 +10,20 @@ user-invocable: false
 
 MUST NOT run any git write operation unless the user explicitly approves it. Git write operations include: `commit`, `push`, `tag`, `merge`, `rebase`, `reset`, `cherry-pick`, `stash`, `branch -D`, and any `gh` command that creates or modifies PRs, issues, or releases.
 
-`git add` (staging) is permitted as part of preparing to show the user what will be committed — but the commit itself requires approval.
+`git add` (staging) is permitted as part of preparing to show the user what will be committed, but the commit itself requires approval.
 
-No skill, command, or workflow overrides this rule. Even instructions like "complete all steps without stopping" do not bypass it. This applies to ALL repos — the main repo, the wiki repo, and any other git repo.
+No skill, command, or workflow overrides this rule. Even instructions like "complete all steps without stopping" do not bypass it. This applies to ALL repos: the main repo, the wiki repo, and any other git repo.
 
 ## Why
 
-Every git push, every PR, every wiki edit that hits GitHub is done under the user's credentials — their name, their reputation. The user is responsible for every action taken on their behalf. That is why they decide when to commit, not the agent.
+Every git push, every PR, every wiki edit that hits GitHub is done under the user's credentials: their name, their reputation. The user is responsible for every action taken on their behalf. That is why they decide when to commit, not the agent.
 
 ## How Approval Works
 
 The user gives approval in one of two ways:
 
-1. **Direct instruction** — the user says "commit", "push", "tag", or equivalent
-2. **Shipping commands** — the user invokes `/submit`, `/deploy`, or `/publish`. Invoking the command IS the approval for the git operations defined in that command's workflow.
+1. **Direct instruction**: the user says "commit", "push", "tag", or equivalent
+2. **Shipping commands**: the user invokes `/submit`, `/deploy`, or `/publish`. Invoking the command IS the approval for the git operations defined in that command's workflow.
 
 ### Approval is scoped, not blanket
 
@@ -39,7 +39,7 @@ Previous approvals do NOT grant future permissions. If the user approved a commi
 
 ### When /submit follows earlier work
 
-If you made changes and the user then runs `/submit`, the command starts fresh — it reads the Deployment page and follows those steps. There is no conflict with earlier work. The user chose to invoke `/submit` at this moment, and that is all the approval needed for the operations within it.
+If you made changes and the user then runs `/submit`, the command starts fresh. It reads the Deployment page and follows those steps. There is no conflict with earlier work. The user chose to invoke `/submit` at this moment, and that is all the approval needed for the operations within it.
 
 Do NOT ask for redundant confirmation inside `/submit` if the user just invoked it. The invocation is the approval. But each discrete git operation within the flow (commit, then push) should still be reported before execution.
 
@@ -53,4 +53,4 @@ Better yet, avoid stashing entirely. If you need to create a branch from a diffe
 
 **Do the work → report results → wait.**
 
-After making changes: report what was done, then stop. Do not ask "want me to commit?" or "should I push?" — that wastes tokens. Just report and wait silently. The user will say "commit", "push", or run a shipping command when ready.
+After making changes: report what was done, then stop. Do not ask "want me to commit?" or "should I push?". That wastes tokens. Just report and wait silently. The user will say "commit", "push", or run a shipping command when ready.

package/skills/simpleapps/github/SKILL.md

@@ -59,7 +59,7 @@ This avoids shell quoting issues with HEREDOCs and `cd` permission blocks. The W
 
 ## Issues
 
-MUST use `--repo simpleapps-com/<repo>` on every `gh` call. MUST ask the user which repo — never assume.
+MUST use `--repo simpleapps-com/<repo>` on every `gh` call. MUST ask the user which repo. Never assume.
 
 **MUST NOT use `$()` or inline content in `gh` commands.** Any `gh` command that needs a body, comment, or multi-line text MUST use the file-based flag (`--body-file`, `--comment-file`, etc.). Write the content to `tmp/` using the Write tool first, then pass the file path. This avoids `$()` command substitution which triggers a permission prompt every time. Delete the tmp file after the command succeeds.
 
@@ -103,18 +103,18 @@ Include `Closes #N` in commit body to auto-close issues.
 
 ### Commenting on existing issues
 
-Before adding a comment to a closed issue, check its state first with `gh issue view`. If the issue is closed but the problem still exists, reopen it with `gh issue reopen` before commenting — a comment on a closed issue is easily missed.
+Before adding a comment to a closed issue, check its state first with `gh issue view`. If the issue is closed but the problem still exists, reopen it with `gh issue reopen` before commenting. A comment on a closed issue is easily missed.
 
 ## Cross-Repo Issues
 
-Use `/file-issue` to automate this process — it creates the upstream issue, cross-links back to the local issue, and adds the `blocked` label. `/triage` surfaces blocked issues in its output.
+Use `/file-issue` to automate this process. It creates the upstream issue, cross-links back to the local issue, and adds the `blocked` label. `/triage` surfaces blocked issues in its output.
 
 When a project hits a blocker that depends on another team's repo, create two issues and keep working:
 
-1. **Local issue** (in the site/project repo) — describe the impact and what's blocked
-2. **Upstream issue** (in the dependency repo) — describe the ask, include reproduction steps or specifics
-3. **Cross-link** — reference the other issue using `simpleapps-com/repo#N` syntax in both issue bodies
-4. **Don't block** — continue with other tasks while waiting for the upstream fix
+1. **Local issue** (in the site/project repo): describe the impact and what's blocked
+2. **Upstream issue** (in the dependency repo): describe the ask, include reproduction steps or specifics
+3. **Cross-link**: reference the other issue using `simpleapps-com/repo#N` syntax in both issue bodies
+4. **Don't block**: continue with other tasks while waiting for the upstream fix
 
 Target repos:
 
@@ -135,7 +135,7 @@ gh pr view <number> --repo simpleapps-com/<repo>
 gh pr merge <number> --repo simpleapps-com/<repo>
 ```
 
-Write PR body to `tmp/pr-body.txt` using the Write tool first — MUST NOT use `--body "$(cat ...)"` or any `$()` substitution.
+Write PR body to `tmp/pr-body.txt` using the Write tool first. MUST NOT use `--body "$(cat ...)"` or any `$()` substitution.
 
 ## Cross-Linking with Basecamp