@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: skill-creator
+description: "This skill should be used when creating, refining, or auditing Claude Code Skills, including SKILL.md structure, scaffolding, packaging, and best practices."
+license: Complete terms in LICENSE.txt
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
+
+#### Bundled Resources (optional)
+
+##### Scripts ([scripts/](./scripts/))
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: [rotate_pdf.py](./scripts/rotate_pdf.py) for PDF rotation tasks (illustrative -- not included in this skill)
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
+- **Node scripts in this repo**: the repo root `package.json` is `type:module`, so a `.js` file using `module.exports`/`require` (CommonJS) fails at runtime with `MODULE_NOT_FOUND` (not at `tsc`). Name CommonJS helper/assert scripts `.cjs` (e.g. promptfoo custom asserts, which load via `require`); reserve `.js`/`.mjs` for genuine ESM. See `knowledge-base/project/learnings/build-errors/2026-06-15-cjs-required-for-commonjs-scripts-and-promptfoo-harness-gotchas.md`.
+
+##### References ([references/](./references/))
+
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Examples**: [finance.md](./references/finance.md) for financial schemas, [mnda.md](./references/mnda.md) for company NDA template, [policies.md](./references/policies.md) for company policies, [api_docs.md](./references/api_docs.md) for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets ([assets/](./assets/))
+
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: [logo.png](./assets/logo.png) for brand assets, [slides.pptx](./assets/slides.pptx) for PowerPoint templates, [frontend-template/](./assets/frontend-template/) for HTML/React boilerplate, [font.ttf](./assets/font.ttf) for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited*)
+
+*Unlimited because scripts can be executed without reading into context window.
+
+## Skill Creation Process
+
+Before creating a new skill, agent, or user-facing capability, run its domain assessment (brainstorm Phase 0.5, or plan Phase 2.5 on a pipeline run) with CPO and CMO in the room (CTO when architectural); CMO may be omitted with a one-line rationale for operator-facing-only capabilities, CPO never. The rule's canonical text is `plugins/soleur/skills/brainstorm/references/brainstorm-domain-config.md` under `## New-capability leader mandate`.
+
+To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A [scripts/rotate_pdf.py](./scripts/rotate_pdf.py) script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An [assets/hello-world/](./assets/hello-world/) template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A [references/schema.md](./references/schema.md) file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/skills/skill-creator/scripts/init_skill.py" <skill-name> --path <output-directory>
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates example resource directories: `scripts/`, `references/`, and `assets/`
+- Adds example files in each directory that can be customized or deleted
+
+After initialization, customize or remove the generated SKILL.md and example files as needed.
+
+- Before writing a new skill description, run `bun test plugins/soleur/test/components.test.ts` to check the current word budget; the cap is `SKILL_DESCRIPTION_WORD_BUDGET` in that file, which is the enforcing gate and the only authority on the number. Target 12-15 words for new skill descriptions, and assume **zero headroom until measured** — the budget has run at or near capacity for most of its life, and the cap itself has been raised several times, so any figure quoted from memory or from an older document is stale by default.
+- After creating a new skill, manually add it to `plugins/soleur/docs/_data/skills.js` in the `SKILL_CATEGORIES` map -- skills are NOT auto-discovered, and missing this step silently removes the skill from the docs site with no build error.
+- New agent files created mid-session cannot be invoked via `subagent_type` because the plugin registry is stale at session start; for live testing, use `general-purpose` agent type and embed the full instructions in the task prompt.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+
+#### Update SKILL.md
+
+**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
+
+To complete SKILL.md, answer the following questions:
+
+1. What is the purpose of the skill, in a few sentences?
+2. When should the skill be used?
+3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.
+
+### Step 5: Packaging a Skill
+
+Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/skills/skill-creator/scripts/package_skill.py" <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/skills/skill-creator/scripts/package_skill.py" <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 5b: Security scan (cooperative-fast-path)
+
+After `package_skill.py` validates the structure but BEFORE the zip is
+distributed, invoke the `skill-security-scan` advisory gate against the
+newly-scaffolded SKILL.md:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/skill-security-scan/scripts/run-scan.sh" < <skill-folder>/SKILL.md
+```
+
+Operator handling:
+
+- **`LOW-RISK`** — proceed with packaging.
+- **No verdict line** (a crash, or `No such file or directory` on an unresolved plugin root) — treat as
+  **`REVIEW`**, never `LOW-RISK`.
+- **`REVIEW`** — present findings as informational; ask operator to confirm
+  before packaging.
+- **`HIGH-RISK`** — present findings + override instructions referencing
+  [skill-security-scan/references/override-mechanism.md](../skill-security-scan/references/override-mechanism.md).
+  Block packaging until either (a) the SKILL.md is revised, or (b) a valid
+  override artifact is committed under `knowledge-base/engineering/security/skill-overrides/`.
+
+The PreToolUse hook on `Write` (`.claude/hooks/skill-security-scan-write.sh`)
+is the load-bearing gate at the tool layer — this Step 5b is the
+operator-friendly cooperative-fast-path that surfaces findings early.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
+
+### Sharp Edges
+
+- **Name a skill or command as `soleur:<name>` and an agent by its registry id, nothing else** — no slash, dollar or at-sign prefix, no bare agent leaf — the adapter renders the harness form (`formatSkillInvocation` / `spawnAgent`, `plugins/soleur/lib/harness.ts`); a doc that writes one harness's form names a component the other three cannot resolve (ADR-226). If a shell variable or glob collides with a skill name, brace or rename it (`"${work}"`) — never widen the gate's boundary set. `plugins/soleur/test/harness-parity-tree.test.ts` is the gate; `bun plugins/soleur/scripts/harness-parity-census.ts --fix` repairs the mechanical shapes.
+
+- When a SKILL.md prose fence documents shell-active patterns by design (e.g., `bash -c "$VAR"`, process substitution, an eval-style invocation), label the fence ` ```text ` instead of ` ```bash ` and document the load-bearing mitigations (timeout, reject-regex, env scrub, trust source) in a per-skill Sharp Edges section. Otherwise the `skill-security-scan` calibration suite fails the first-party SKILL.md with HIGH-RISK on `code-execution` — there is no per-finding override mechanism for first-party legitimate uses. The fence is documentation; the orchestrator still dispatches via the Bash tool when it reads the prose, so runtime behavior is unchanged. See `knowledge-base/project/learnings/2026-05-20-skill-md-shell-active-prose-calibration-carve-out.md`.
+
+## Auditing Existing Skills
+
+For auditing and improving existing skills, see the [audit-skill workflow](./workflows/audit-skill.md).
+
+## Reference Files
+
+For detailed guidance on skill authoring, see:
+
+- [official-spec.md](./references/official-spec.md) - Anthropic's official skill specification
+- [best-practices.md](./references/best-practices.md) - Skill authoring best practices
+- [core-principles.md](./references/core-principles.md) - Core principles for skill design
+- [authoring-levers.md](./references/authoring-levers.md) - Leading words, the two loads and the invocation choice, co-location, criterion demand
+- [skill-structure.md](./references/skill-structure.md) - Skill structure and organization
+- [recommended-structure.md](./references/recommended-structure.md) - Recommended file structure
+- [common-patterns.md](./references/common-patterns.md) - Common skill patterns (template, workflow, conditional)
+- [be-clear-and-direct.md](./references/be-clear-and-direct.md) - Writing clear skill instructions
+- [executable-code.md](./references/executable-code.md) - Working with executable code in skills
+- [using-scripts.md](./references/using-scripts.md) - Using scripts in skills
+- [using-templates.md](./references/using-templates.md) - Using templates in skills
+- [iteration-and-testing.md](./references/iteration-and-testing.md) - Iteration and testing guidance
+- [workflows-and-validation.md](./references/workflows-and-validation.md) - Workflow and validation patterns
+- [api-security.md](./references/api-security.md) - API security considerations
+- [fail-closed redaction pattern](../../../../knowledge-base/project/learnings/2026-05-15-fail-closed-redaction-enables-committed-default-output.md) - Designing output paths for skills that generate user-derived artifacts intended for external sharing
+
+## Workflows
+
+Step-by-step guides for specific skill authoring tasks:
+
+- [create-new-skill.md](./workflows/create-new-skill.md) - Create a new skill from scratch
+- [audit-skill.md](./workflows/audit-skill.md) - Audit an existing skill against best practices
+- [add-reference.md](./workflows/add-reference.md) - Add a reference file to a skill
+- [add-script.md](./workflows/add-script.md) - Add a script to a skill
+- [add-template.md](./workflows/add-template.md) - Add a template to a skill
+- [add-workflow.md](./workflows/add-workflow.md) - Add a workflow to a skill
+- [create-domain-expertise-skill.md](./workflows/create-domain-expertise-skill.md) - Create a domain expertise skill
+- [upgrade-to-router.md](./workflows/upgrade-to-router.md) - Upgrade a simple skill to a router skill
+- [verify-skill.md](./workflows/verify-skill.md) - Verify a skill meets requirements
+- [get-guidance.md](./workflows/get-guidance.md) - Get guidance on skill design decisions
+
+## Templates
+
+Starter templates for common skill types:
+
+- [simple-skill.md](./templates/simple-skill.md) - Template for a simple single-file skill
+- [router-skill.md](./templates/router-skill.md) - Template for a multi-workflow router skill

package/skills/skill-creator/references/api-security.md

@@ -0,0 +1,248 @@
+<overview>
+When building skills that make API calls requiring credentials (API keys, tokens, secrets), follow this protocol to prevent credentials from appearing in chat.
+</overview>
+
+<the_problem>
+Raw curl commands with environment variables expose credentials:
+
+```bash
+# ❌ BAD - API key visible in chat
+curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data
+```
+
+When Claude executes this, the full command with expanded `$API_KEY` appears in the conversation.
+</the_problem>
+
+<the_solution>
+Use `~/.claude/scripts/secure-api.sh` - a wrapper that loads credentials internally.
+
+<for_supported_services>
+
+```bash
+# ✅ GOOD - No credentials visible
+~/.claude/scripts/secure-api.sh <service> <operation> [args]
+
+# Examples:
+~/.claude/scripts/secure-api.sh facebook list-campaigns
+~/.claude/scripts/secure-api.sh ghl search-contact "email@example.com"
+```
+
+</for_supported_services>
+
+<adding_new_services>
+When building a new skill that requires API calls:
+
+1. **Add operations to the wrapper** (`~/.claude/scripts/secure-api.sh`):
+
+```bash
+case "$SERVICE" in
+    yourservice)
+        case "$OPERATION" in
+            list-items)
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items"
+                ;;
+            get-item)
+                ITEM_ID=$1
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items/$ITEM_ID"
+                ;;
+            *)
+                echo "Unknown operation: $OPERATION" >&2
+                exit 1
+                ;;
+        esac
+        ;;
+esac
+```
+
+2. **Add profile support to the wrapper** (if service needs multiple accounts):
+
+```text
+# In secure-api.sh, add to profile remapping section:
+yourservice)
+    SERVICE_UPPER="YOURSERVICE"
+    # Dynamically resolve the env var name using the profile:
+    # YOURSERVICE_API_KEY = value of YOURSERVICE_<PROFILE>_API_KEY
+    # YOURSERVICE_ACCOUNT_ID = value of YOURSERVICE_<PROFILE>_ACCOUNT_ID
+    ;;
+```
+
+3. **Add credential placeholders to `~/.claude/.env`** using profile naming:
+
+```bash
+# Check if entries already exist
+grep -q "YOURSERVICE_MAIN_API_KEY=" ~/.claude/.env 2>/dev/null || \
+  echo -e "\n# Your Service - Main profile\nYOURSERVICE_MAIN_API_KEY=\nYOURSERVICE_MAIN_ACCOUNT_ID=" >> ~/.claude/.env
+
+echo "Added credential placeholders to ~/.claude/.env - user needs to fill them in"
+```
+
+4. **Document profile workflow in your SKILL.md**:
+
+```markdown
+## Profile Selection Workflow
+
+**CRITICAL:** Always use profile selection to prevent using wrong account credentials.
+
+### When user requests YourService operation:
+
+1. **Check for saved profile:**
+   ```bash
+   ~/.claude/scripts/profile-state get yourservice
+   ```
+
+2. **If no profile saved, discover available profiles:**
+
+   ```bash
+   ~/.claude/scripts/list-profiles yourservice
+   ```
+
+3. **If only ONE profile:** Use it automatically and announce:
+
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+4. **If MULTIPLE profiles:** Ask user which one:
+
+   ```
+   "Which YourService profile: main, clienta, or clientb?"
+   ```
+
+5. **Save user's selection:**
+
+   ```bash
+   ~/.claude/scripts/profile-state set yourservice <selected_profile>
+   ```
+
+6. **Always announce which profile before calling API:**
+
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+7. **Make API call with profile:**
+
+   ```bash
+   ~/.claude/scripts/secure-api.sh yourservice:<profile> list-items
+   ```
+
+## Secure API Calls
+
+All API calls use profile syntax:
+
+```bash
+~/.claude/scripts/secure-api.sh yourservice:<profile> <operation> [args]
+
+# Examples:
+~/.claude/scripts/secure-api.sh yourservice:main list-items
+~/.claude/scripts/secure-api.sh yourservice:main get-item <ITEM_ID>
+```
+
+**Profile persists for session:** Once selected, use same profile for subsequent operations unless user explicitly changes it.
+
+```
+</adding_new_services>
+</the_solution>
+
+<pattern_guidelines>
+<simple_get_requests>
+```bash
+curl -s -G \
+    -H "Authorization: Bearer $API_KEY" \
+    "https://api.example.com/endpoint"
+```
+
+</simple_get_requests>
+
+<post_with_json_body>
+
+```bash
+ITEM_ID=$1
+curl -s -X POST \
+    -H "Authorization: Bearer $API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @- \
+    "https://api.example.com/items/$ITEM_ID"
+```
+
+Usage:
+
+```bash
+echo '{"name":"value"}' | ~/.claude/scripts/secure-api.sh service create-item
+```
+
+</post_with_json_body>
+
+<post_with_form_data>
+
+```bash
+curl -s -X POST \
+    -F "field1=value1" \
+    -F "field2=value2" \
+    -F "access_token=$API_TOKEN" \
+    "https://api.example.com/endpoint"
+```
+
+</post_with_form_data>
+</pattern_guidelines>
+
+<credential_storage>
+**Location:** `~/.claude/.env` (global for all skills, accessible from any directory)
+
+**Format:**
+
+```bash
+# Service credentials
+SERVICE_API_KEY=your-key-here
+SERVICE_ACCOUNT_ID=account-id-here
+
+# Another service
+OTHER_API_TOKEN=token-here
+OTHER_BASE_URL=https://api.other.com
+```
+
+**Loading in script:**
+
+```bash
+set -a
+source ~/.claude/.env 2>/dev/null || { echo "Error: ~/.claude/.env not found" >&2; exit 1; }
+set +a
+```
+
+</credential_storage>
+
+<best_practices>
+
+1. **Never use raw curl with `$VARIABLE` in skill examples** - always use the wrapper
+2. **Add all operations to the wrapper** - don't make users figure out curl syntax
+3. **Auto-create credential placeholders** - add empty fields to `~/.claude/.env` immediately when creating the skill
+4. **Keep credentials in `~/.claude/.env`** - one central location, works everywhere
+5. **Document each operation** - show examples in SKILL.md
+6. **Handle errors gracefully** - check for missing env vars, show helpful error messages
+</best_practices>
+
+<testing>
+Test the wrapper without exposing credentials:
+
+```bash
+# This command appears in chat
+~/.claude/scripts/secure-api.sh facebook list-campaigns
+
+# But API keys never appear - they're loaded inside the script
+```
+
+Verify credentials are loaded:
+
+```bash
+# Check .env exists
+ls -la ~/.claude/.env
+
+# Check specific variables (without showing values)
+grep -q "YOUR_API_KEY=" ~/.claude/.env && echo "API key configured" || echo "API key missing"
+```
+
+</testing>

package/skills/skill-creator/references/authoring-levers.md

@@ -0,0 +1,110 @@
+<!-- Inspired by mattpocock/skills/skills/productivity/writing-for-agents/SKILL.md, mattpocock/skills/skills/productivity/writing-for-agents/SKILL-MECHANICS.md and mattpocock/skills/.agents/invocation.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+# Authoring Levers
+
+Four levers decide whether an agent runs a skill the same way twice. Reach for this file when
+drafting or reviewing a `SKILL.md`, a reference, an agent file, or an always-loaded rule. The
+running example is a synthetic skill, `my-deploy-skill`, that ships a container to a server.
+
+## Leading words
+
+A leading word is one short token for a concept the model already learned in pretraining. Used
+consistently, it carries a whole behaviour in a single word, so the prose around it can shrink.
+
+Soleur already runs on a few. `red` in `reproduce-bug` turns "a check you trust" into a binary state:
+the command either goes red on this bug or it does not. `drain` in `drain-prs` and
+`drain-labeled-backlog` says "empty the queue, item by item, until nothing is left" without a
+paragraph of explanation.
+
+How to use the lever:
+
+- Look for a phrase that recurs, or a sentence that circles one idea. Replace it with a single
+  word the model already knows, then use that word every time.
+- Prefer an existing word to a coined one. A coined word brings no prior meaning, so you pay for its
+  definition in tokens.
+- Put the word in both places it works: the body (so each step pulls the same behaviour) and the
+  description (so the prompt that should fire the skill shares its vocabulary).
+
+For `my-deploy-skill`, "verify the new container answers health checks, and roll back if it does
+not" becomes one word used at every step: the deploy is **green** or it is rolled back.
+
+**Negation.** A prohibition names the behaviour it forbids, and naming it puts that behaviour in
+front of the model. Pair every prohibition with the positive target, and lead with the target:
+"write the health-check result to the PR body" beats "do not skip the health check". Keep a bare
+prohibition only as a hard guardrail with no positive form, and even then state what to do instead.
+This lever comes from the model vendors' prompting guidance, not from a Soleur measurement.
+Soleur's attempt to measure it on its own always-loaded rules (B5, #8290) was inconclusive with
+limited instrument validity. ADR-236 records it and #8497 tracks a rerun. Apply the lever to new
+text; do not rewrite existing rules for phrasing alone.
+
+## The two loads (context vs cognitive)
+
+Each pointer you add is paid from one of two budgets.
+
+- **Context load** is what the model carries on every turn: each skill description, each line of
+  an always-loaded rule. It costs tokens and attention whether or not the skill fires.
+- **Cognitive load** is what a human carries: knowing a thing exists and when to reach for it. It is
+  the right cost where human judgement should gate the action, and the wrong one anywhere else.
+
+A skill with no path to it from the model rides entirely on the human remembering it.
+
+### The invocation choice
+
+Ask one question of every skill: **could the model usefully reach for this on its own, or must
+another skill reach it?** If either is true, the skill stays model-invocable. If only a human ever
+fires it, mark it user-invoked and stop paying context load for it.
+
+`disable-model-invocation: true` removes the description from the model's always-loaded skill
+listing. Measured on Claude Code 2.1.278:
+
+- the description is absent from the listing;
+- the Skill tool refuses with a `tool_use_error` that tells the model to ask the user to type
+  `/plugin:skill`;
+- the user's slash command still runs, both headless and in the interactive TUI.
+
+ADR-236 holds the rest and is the single source for it: the three necessary conditions (K1-K3,
+where K3 means the model can still reach the capability another way, or it is deliberately
+operator-only), each harness's behaviour (the flag is inert on Codex and Grok), the headless-refusal
+policy (stop and file an `action-required` issue naming the command; never re-run the skill's steps
+by hand), and the sites that move together when a skill is flipped.
+
+"Operator tooling" and "only a human should fire it" are different properties. A skill that an
+always-loaded rule lists as the agent's own tool, a skill plans prescribe as an agent step, or a
+read-only audit the agent must pull itself before acting, stays model-invocable however
+operator-flavoured it looks. `my-deploy-skill` would qualify for the flag only if no other skill's
+steps call it and no founder reaches it from the web.
+
+## Co-location (vs duplication, single source of truth)
+
+Co-location is about placement inside one file: a concept's definition, its rules, and its caveats
+sit under one heading. Reading any part of it brings the rest along. Scattering the same concept
+across three sections makes the model assemble it, and it will sometimes assemble it wrong.
+
+Duplication is a different failure: one meaning written in two places. The copies drift, both cost
+tokens, and the repetition inflates the concept's apparent importance. Give every meaning exactly
+one authoritative home, a single source of truth, and point at it. For `my-deploy-skill`, the
+rollback rule lives once, under `## Rollback`, and the deploy steps link to that section instead
+of restating it.
+
+The repository itself is also authoritative. A command's `--help`, a `package.json` script, or the
+directory layout answers a lookup better than a copy in prose, which goes stale silently. Write
+down what the agent cannot discover by looking: the convention nobody encoded, the reason behind a
+choice, the trap the config hides.
+
+Structure follows the same rule. Markdown headings structure a skill body; XML tags are optional
+semantic wrappers inside a section and never replace headings (see `skill-structure.md`).
+
+## Criterion demand (clarity AND demand)
+
+Every step ends on a completion criterion, and a criterion has two independent properties.
+
+- **Clarity**: is the finished state unambiguous to the agent? "The deploy looks healthy" invites
+  stopping early. "`curl -fsS $HOST/health` returned 200 three times, 10 seconds apart" does not.
+- **Demand**: how much the criterion asks for. "Report the deploy status" asks for a sentence.
+  "Every service in the compose file answered its health check, and each result is in the PR body"
+  forces the agent to enumerate the services, check each one, and write the results.
+
+A clear criterion that demands little still produces thin work, and a demanding one that is vague
+still ends early. Write criteria that are both: checkable by a command or a count, and exhaustive
+over the set the step covers. When a fuzzy criterion keeps ending a step early, sharpen the
+criterion first; moving the later steps out of view helps only across a real context boundary, such
+as a subagent dispatch or a hand-off.