@simpleapps-com/augur-skills 2026.3.10 → 2026.3.12

package/package.json

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

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

@@ -19,7 +19,7 @@ This skill is a **stub, not an archive**. New packages are created, existing pac
 
 **Always read the installed packages in your project's `node_modules/`:**
 
-1. Run `ls repo/node_modules/@simpleapps-com/` to discover ALL available packages — there may be packages not listed here
+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>/package.json` for the `exports` field to find available sub-paths
 3. Read files in `repo/node_modules/@simpleapps-com/<package>/dist/` to understand the current API surface
 4. Do NOT look at the source repo or other folders — only read what is installed in your project's `node_modules/`
@@ -42,7 +42,7 @@ These are starting hints — not a complete list. Always check `node_modules/@si
 
 When considering custom code:
 
-1. Run `ls repo/node_modules/@simpleapps-com/` to see what's installed
+1. Use `Glob("repo/node_modules/@simpleapps-com/*")` to see what's installed
 2. Read the package's `package.json` `exports` and its `dist/` files for available functions, hooks, and components
 3. Look for the hook triple pattern in augur-hooks: `use<Name>`, `get<Name>Options`, `get<Name>Key`
 4. Check augur-web for UI components before building custom ones
@@ -76,4 +76,4 @@ The goal is to grow the packages over time so sites write less custom code.
 - **Tailwind:** v4, CSS-first
 - **Validation:** Valibot (not Zod, not Yup)
 - **Auth:** NextAuth 5 via package auth factory
-- **Reference site:** ampro-online
+- **Reference site:** ampro-online — use `Grep`, `Glob`, and `Read` with path `~/projects/clients/ampro-online/repo` to see how patterns are implemented. MUST NOT use `find`, `grep`, or other shell commands.

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

@@ -6,6 +6,10 @@ user-invocable: false
 
 # Bash Simplicity
 
+## Why This Matters
+
+Every permission prompt makes the user the bottleneck. If the user doesn't see the prompt for an hour, that hour is lost — the agent is blocked, the task stalls, and the system designed for autonomous work stops working. The entire plugin system exists to remove the user as the bottleneck. A permission prompt works directly against that goal. Use dedicated tools and simple commands to avoid ever triggering one.
+
 ## One Command Per Call
 
 MUST run each Bash command as a separate, simple call. MUST NOT chain commands with `&&`, `||`, pipes, or sub-shells. Complex commands trigger permission prompts and break automation.
@@ -16,6 +20,13 @@ Right: Three separate Bash calls, one per command.
 Wrong: `pnpm --filter ampro-online run typecheck 2>&1; echo "EXIT: $?"`
 Right: `pnpm --filter ampro-online run typecheck` — the Bash tool already captures stderr and exit codes. Never add `2>&1`, `; echo $?`, or other shell plumbing — it triggers permission prompts for no benefit.
 
+Wrong: `gh issue close 367 --repo org/repo --comment "$(< tmp/file.txt)" 2>&1`
+Right: Write the comment to a tmp file, then use two separate calls:
+1. `gh issue comment 367 --repo org/repo --body-file tmp/file.txt`
+2. `gh issue close 367 --repo org/repo`
+
+MUST NOT use `$()` command substitution in Bash commands — it triggers a permission prompt every time. Write content to a tmp file first, then pass it with a `-F`, `--body-file`, or similar flag.
+
 ## Use Dedicated Tools
 
 Dedicated tools are faster, require no permission, and produce better output. MUST use them instead of Bash equivalents:
@@ -33,6 +44,22 @@ Reserve Bash for commands that have no dedicated tool equivalent: build tools, t
 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.
+
+## Cross-Project Searching
+
+When looking at another project's code (e.g., the reference site ampro-online), use dedicated tools with the known project path — MUST NOT use shell commands:
+
+Wrong: `find ~/projects/clients/ampro-online/repo -name "*.ts" -exec grep -l "pattern" {} \; 2>/dev/null | head -10`
+Right: `Grep(pattern: "pattern", path: "~/projects/clients/ampro-online/repo", glob: "*.ts")`
+
+Wrong: `ls ~/projects/clients/ampro-online/repo/src/components/`
+Right: `Glob(pattern: "~/projects/clients/ampro-online/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.
+
 ## 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.

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

@@ -0,0 +1,70 @@
+---
+name: context-efficiency
+description: How to write token-efficient CLAUDE.md, rules, and skills. Use when creating or editing always-loaded content (CLAUDE.md, .claude/rules/) or authoring skills. Covers the context loading hierarchy, evergreen content principles, and platform limits.
+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.
+
+## Context Loading Hierarchy
+
+| Layer | When loaded | What belongs here |
+|-------|------------|-------------------|
+| CLAUDE.md | Every prompt | Orient + link. Under 200 lines (official limit). |
+| Rules (no `paths`) | Every prompt | Short guardrails. One topic per file. Invoke a skill for detail. |
+| Rules (with `paths`) | On demand | Scoped guidance that only matters for specific file types. |
+| Skills (descriptions) | Every prompt | One-line descriptions. 2% of context window for ALL combined. |
+| Skills (full content) | When invoked | Full behavioral detail. Under 500 lines per skill. |
+| Wiki | When read | Complete project knowledge. Unlimited but we budget 20K tokens. |
+
+## Platform Limits
+
+- **CLAUDE.md**: under 200 lines. "Bloated files cause Claude to ignore your actual instructions."
+- **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.
+
+## Evergreen Content
+
+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.
+- **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.
+
+Instead: describe the **pattern**, give **1-2 examples**, and **link** to the source for the current state.
+
+## The Pointer Pattern
+
+Always-loaded files SHOULD be pointers that invoke on-demand content:
+
+```markdown
+# Git Safety (rule — 3 lines, always loaded)
+MUST NOT commit without user approval.
+Load Skill("git-safety") for full guardrails.
+```
+
+The rule costs ~40 tokens per prompt. The skill costs nothing until invoked, then loads ~800 tokens of detailed guidance. This is 20x more efficient than putting the full content in the rule.
+
+## When to Use Each Layer
+
+| Question | Answer |
+|----------|--------|
+| Does the agent need this on EVERY prompt? | CLAUDE.md or rule |
+| Is it a critical guardrail? | Rule (invokes skill for detail) |
+| Is it only relevant for certain files? | Rule with `paths` frontmatter |
+| Is it detailed behavioral guidance? | Skill |
+| Is it shared knowledge across projects? | Wiki |
+| Is it personal to one user? | Memory |
+
+## Checking Your Budget
+
+Run `/context` to see current token usage by category. Watch for:
+- Skills being excluded (descriptions exceeded 2% budget)
+- CLAUDE.md consuming more than ~5% of context
+- Many MCP servers inflating tool definitions

package/skills/simpleapps/github/SKILL.md

@@ -61,6 +61,8 @@ This avoids shell quoting issues with HEREDOCs and `cd` permission blocks. The W
 
 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.
+
 ### Title
 
 Conventional commit style: `fix: description`, `feat: description`, `chore: description`. Under 70 characters.
@@ -89,9 +91,14 @@ Bug reports also include **Steps to Reproduce** and **Current Behavior** with er
 gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body "..."
 gh issue list --repo simpleapps-com/<repo>
 gh issue view <number> --repo simpleapps-com/<repo>
-gh issue close <number> --repo simpleapps-com/<repo> --comment "message"
+gh issue close <number> --repo simpleapps-com/<repo>
 ```
 
+For closing with a comment, use two calls (avoids `$()` permission prompts):
+1. Write comment to `tmp/issue-comment.txt` using the Write tool
+2. `gh issue comment <number> --repo simpleapps-com/<repo> --body-file tmp/issue-comment.txt`
+3. `gh issue close <number> --repo simpleapps-com/<repo>`
+
 Include `Closes #N` in commit body to auto-close issues.
 
 ### Commenting on existing issues
@@ -120,12 +127,14 @@ Example cross-link in issue body: `Upstream: simpleapps-com/augur#44` or `Local
 ## Pull Requests
 
 ```bash
-gh pr create --repo simpleapps-com/<repo> --title "title" --body "..."
+gh pr create --repo simpleapps-com/<repo> --title "title" --body-file tmp/pr-body.txt
 gh pr list --repo simpleapps-com/<repo>
 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.
+
 ## Cross-Linking with Basecamp
 
 For client tasks originating in Basecamp, see `simpleapps:workflow` for the full cross-linking process.

package/skills/simpleapps/wiki/SKILL.md

@@ -73,6 +73,47 @@ Pages MUST link to related sections on other pages using `[[Page-Name#section]]`
 
 Cross-linking also eliminates duplication. If two pages explain the same concept, one MUST become the source of truth and the other MUST link to it. Never duplicate content across pages — link instead. This keeps the wiki lean and ensures updates happen in one place.
 
+## Wiki Over Memory
+
+When asked to save, document, or record knowledge — use the wiki, MUST NOT use memory. The wiki is shared across all agents, all projects, and all computers. Memory is personal to one user on one machine — invisible to everyone else.
+
+| Knowledge type | Where it belongs |
+|---------------|-----------------|
+| Conventions, patterns, decisions | **Wiki** |
+| Learnings from a task or session | **Wiki** |
+| Architecture and process docs | **Wiki** |
+| How a problem was solved | **Wiki** |
+| Personal preferences (writing style, response length) | Memory |
+| User role and background | Memory |
+
+If in doubt, it belongs in the wiki. The cost of putting shared knowledge in memory is that it dies with the session — no other agent, project, or computer will ever see it.
+
+## Cross-Project Wiki Access
+
+All SimpleApps projects follow the same directory layout under `~/projects/`. Every project's wiki is at a known, predictable path:
+
+| Project type | Wiki path |
+|-------------|-----------|
+| Client sites | `~/projects/clients/<site-name>/wiki/` |
+| Internal repos | `~/projects/simpleapps/<repo-name>/wiki/` |
+
+**Reference site:** `~/projects/clients/ampro-online/` is the reference implementation. When you need to see how something was done, check its wiki and repo first.
+
+**Key wikis to consult:**
+- `~/projects/simpleapps/augur-packages/wiki/` — shared package conventions, API surfaces, component patterns
+- `~/projects/simpleapps/augur-skills/wiki/` — plugin and skill authoring conventions
+- `~/projects/clients/ampro-online/wiki/` — reference site patterns, real-world usage examples
+
+**Before reading another project's wiki, pull the latest:**
+`git -C ~/projects/clients/<site>/wiki pull`
+
+**MUST use dedicated tools for cross-project access — MUST NOT use shell commands:**
+- Read files: `Read("~/projects/clients/<site>/wiki/Page.md")` or `Read("~/projects/clients/<site>/repo/path/to/file")`
+- Search code: `Grep(pattern: "...", path: "~/projects/clients/<site>/repo")`
+- Find files: `Glob(pattern: "~/projects/clients/<site>/repo/**/*.ts")`
+
+MUST NOT use `find`, `grep`, `cat`, `ls`, or any shell command to explore other projects. The paths are known — use the dedicated tools directly.
+
 ## Keep It Lean
 
 - Document patterns and principles, not exhaustive lists