@fro.bot/systematic 1.14.0 → 1.15.0

package/skills/create-agent-skills/references/api-security.md

@@ -14,23 +14,23 @@ When Claude executes this, the full command with expanded `$API_KEY` appears in
 </the_problem>
 
 <the_solution>
-Use `~/.claude/scripts/secure-api.sh` - a wrapper that loads credentials internally.
+Use `~/.config/opencode/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]
+~/.config/opencode/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"
+~/.config/opencode/scripts/secure-api.sh facebook list-campaigns
+~/.config/opencode/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`):
+1. **Add operations to the wrapper** (`~/.config/opencode/scripts/secure-api.sh`):
 
 ```bash
 case "$SERVICE" in
@@ -67,14 +67,14 @@ yourservice)
     ;;
 ```
 
-3. **Add credential placeholders to `~/.claude/.env`** using profile naming:
+3. **Add credential placeholders to `~/.config/opencode/.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
+grep -q "YOURSERVICE_MAIN_API_KEY=" ~/.config/opencode/.env 2>/dev/null || \
+  echo -e "\n# Your Service - Main profile\nYOURSERVICE_MAIN_API_KEY=\nYOURSERVICE_MAIN_ACCOUNT_ID=" >> ~/.config/opencode/.env
 
-echo "Added credential placeholders to ~/.claude/.env - user needs to fill them in"
+echo "Added credential placeholders to ~/.config/opencode/.env - user needs to fill them in"
 ```
 
 4. **Document profile workflow in your SKILL.md**:
@@ -88,12 +88,12 @@ echo "Added credential placeholders to ~/.claude/.env - user needs to fill them
 
 1. **Check for saved profile:**
    ```bash
-   ~/.claude/scripts/profile-state get yourservice
+   ~/.config/opencode/scripts/profile-state get yourservice
    ```
 
 2. **If no profile saved, discover available profiles:**
    ```bash
-   ~/.claude/scripts/list-profiles yourservice
+   ~/.config/opencode/scripts/list-profiles yourservice
    ```
 
 3. **If only ONE profile:** Use it automatically and announce:
@@ -108,7 +108,7 @@ echo "Added credential placeholders to ~/.claude/.env - user needs to fill them
 
 5. **Save user's selection:**
    ```bash
-   ~/.claude/scripts/profile-state set yourservice <selected_profile>
+   ~/.config/opencode/scripts/profile-state set yourservice <selected_profile>
    ```
 
 6. **Always announce which profile before calling API:**
@@ -118,7 +118,7 @@ echo "Added credential placeholders to ~/.claude/.env - user needs to fill them
 
 7. **Make API call with profile:**
    ```bash
-   ~/.claude/scripts/secure-api.sh yourservice:<profile> list-items
+   ~/.config/opencode/scripts/secure-api.sh yourservice:<profile> list-items
    ```
 
 ## Secure API Calls
@@ -126,11 +126,11 @@ echo "Added credential placeholders to ~/.claude/.env - user needs to fill them
 All API calls use profile syntax:
 
 ```bash
-~/.claude/scripts/secure-api.sh yourservice:<profile> <operation> [args]
+~/.config/opencode/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>
+~/.config/opencode/scripts/secure-api.sh yourservice:main list-items
+~/.config/opencode/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.
@@ -159,7 +159,7 @@ curl -s -X POST \
 
 Usage:
 ```bash
-echo '{"name":"value"}' | ~/.claude/scripts/secure-api.sh service create-item
+echo '{"name":"value"}' | ~/.config/opencode/scripts/secure-api.sh service create-item
 ```
 </post_with_json_body>
 
@@ -175,7 +175,7 @@ curl -s -X POST \
 </pattern_guidelines>
 
 <credential_storage>
-**Location:** `~/.claude/.env` (global for all skills, accessible from any directory)
+**Location:** `~/.config/opencode/.env` (global for all skills, accessible from any directory)
 
 **Format:**
 ```bash
@@ -191,7 +191,7 @@ 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; }
+source ~/.config/opencode/.env 2>/dev/null || { echo "Error: ~/.config/opencode/.env not found" >&2; exit 1; }
 set +a
 ```
 </credential_storage>
@@ -199,8 +199,8 @@ set +a
 <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
+3. **Auto-create credential placeholders** - add empty fields to `~/.config/opencode/.env` immediately when creating the skill
+4. **Keep credentials in `~/.config/opencode/.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>
@@ -210,7 +210,7 @@ Test the wrapper without exposing credentials:
 
 ```bash
 # This command appears in chat
-~/.claude/scripts/secure-api.sh facebook list-campaigns
+~/.config/opencode/scripts/secure-api.sh facebook list-campaigns
 
 # But API keys never appear - they're loaded inside the script
 ```
@@ -218,9 +218,9 @@ Test the wrapper without exposing credentials:
 Verify credentials are loaded:
 ```bash
 # Check .env exists
-ls -la ~/.claude/.env
+ls -la ~/.config/opencode/.env
 
 # Check specific variables (without showing values)
-grep -q "YOUR_API_KEY=" ~/.claude/.env && echo "API key configured" || echo "API key missing"
+grep -q "YOUR_API_KEY=" ~/.config/opencode/.env && echo "API key configured" || echo "API key missing"
 ```
 </testing>

package/skills/create-agent-skills/references/executable-code.md

@@ -45,7 +45,7 @@ skill-name/
 **Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
 
 ```bash
-python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+python ~/.config/opencode/skills/skill-name/scripts/analyze.py input.har
 ```
 </scripts_directory>
 </file_organization>

package/skills/create-agent-skills/references/official-spec.md

@@ -1,36 +1,56 @@
-# Anthropic Official Skill Specification
+# Official Skill Specification (2026)
 
 Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
 
-## SKILL.md File Structure
+## Commands and Skills Are Merged
+
+Custom slash commands have been merged into skills. A file at `.opencode/commands/review.md` and a skill at `.opencode/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.opencode/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
 
-Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
+If a skill and a command share the same name, the skill takes precedence.
+
+## SKILL.md File Structure
 
-### Basic Format
+Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
 
 ```markdown
 ---
 name: your-skill-name
-description: Brief description of what this Skill does and when to use it
+description: What it does and when to use it
 ---
 
 # Your Skill Name
 
 ## Instructions
-Provide clear, step-by-step guidance for Claude.
+Clear, step-by-step guidance.
 
 ## Examples
-Show concrete examples of using this Skill.
+Concrete examples of using this skill.
 ```
 
-## Required Frontmatter Fields
+## Complete Frontmatter Reference
+
+All fields are optional. Only `description` is recommended.
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
-| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
-| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
-| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
+| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
+| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
+| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
+| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. Default: `false` |
+| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` |
+| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | No | Model to use: `haiku`, `sonnet`, or `opus` |
+| `context` | No | Set `fork` to run in isolated subagent context |
+| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name |
+| `hooks` | No | Hooks scoped to this skill's lifecycle |
+
+## Invocation Control
+
+| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
+|-------------|----------------|-------------------|--------------------------|
+| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
+| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
+| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
 
 ## Skill Locations & Priority
 
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
 
 | Type | Path | Applies to |
 |------|------|-----------|
-| **Enterprise** | See managed settings | All users in organization |
-| **Personal** | `~/.claude/skills/` | You, across all projects |
-| **Project** | `.claude/skills/` | Anyone working in repository |
-| **Plugin** | Bundled with plugins | Anyone with plugin installed |
+| Enterprise | See managed settings | All users in organization |
+| Personal | `~/.config/opencode/skills/<name>/SKILL.md` | You, across all projects |
+| Project | `.opencode/skills/<name>/SKILL.md` | Anyone working in repository |
+| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
+
+Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
 
 ## How Skills Work
 
-1. **Discovery**: Claude loads only name and description at startup
-2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
-3. **Execution**: Claude follows the Skill's instructions and loads referenced files
+1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
+2. **Activation**: When your request matches a skill's description, Claude loads the full content
+3. **Execution**: Claude follows the skill's instructions
 
-**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
+## String Substitutions
 
-## Progressive Disclosure Pattern
+| Variable | Description |
+|----------|-------------|
+| `$ARGUMENTS` | All arguments passed when invoking |
+| `$ARGUMENTS[N]` | Specific argument by 0-based index |
+| `$N` | Shorthand for `$ARGUMENTS[N]` |
+| `${CLAUDE_SESSION_ID}` | Current session ID |
 
-Keep `SKILL.md` under 500 lines by linking to supporting files:
+## Dynamic Context Injection
 
-```
-my-skill/
-├── SKILL.md (required - overview and navigation)
-├── reference.md (detailed API docs - loaded when needed)
-├── examples.md (usage examples - loaded when needed)
-└── scripts/
-    └── helper.py (utility script - executed, not loaded)
-```
-
-### Example SKILL.md with References
+The `` !`command` `` syntax runs shell commands before content is sent to Claude:
 
 ```markdown
----
-name: pdf-processing
-description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
-allowed-tools: Read, Bash(python:*)
----
-
-# PDF Processing
-
-## Quick start
-
-Extract text:
-```python
-import pdfplumber
-with pdfplumber.open("doc.pdf") as pdf:
-    text = pdf.pages[0].extract_text()
+## Context
+- Current branch: !`git branch --show-current`
+- PR diff: !`gh pr diff`
 ```
 
-For form filling, see [FORMS.md](FORMS.md).
-For detailed API reference, see [REFERENCE.md](REFERENCE.md).
+Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
 
-## Requirements
+## Progressive Disclosure
 
-Packages must be installed:
-```bash
-pip install pypdf pdfplumber
 ```
+my-skill/
+├── SKILL.md           # Entry point (required)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
 ```
 
-## Restricting Tool Access
-
-```yaml
----
-name: reading-files-safely
-description: Read files without making changes. Use when you need read-only file access.
-allowed-tools: Read, Grep, Glob
----
+Keep SKILL.md under 500 lines. Link to supporting files:
+```markdown
+For API details, see [reference.md](reference.md).
 ```
 
-Benefits:
-- Read-only Skills that shouldn't modify files
-- Limited scope for specific tasks
-- Security-sensitive workflows
-
-## Writing Effective Descriptions
-
-The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
+## Running in a Subagent
 
-**Always write in third person.** The description is injected into the system prompt.
-
-- **Good:** "Processes Excel files and generates reports"
-- **Avoid:** "I can help you process Excel files"
-- **Avoid:** "You can use this to process Excel files"
-
-**Be specific and include key terms:**
-
-```yaml
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
-```
-
-**Avoid vague descriptions:**
+Add `context: fork` to run in isolation:
 
 ```yaml
-description: Helps with documents  # Too vague!
-```
-
-## Complete Example: Commit Message Generator
-
-```markdown
 ---
-name: generating-commit-messages
-description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
 ---
 
-# Generating Commit Messages
-
-## Instructions
-
-1. Run `git diff --staged` to see changes
-2. I'll suggest a commit message with:
-   - Summary under 50 characters
-   - Detailed description
-   - Affected components
-
-## Best practices
-
-- Use present tense
-- Explain what and why, not how
+Research $ARGUMENTS thoroughly...
 ```
 
-## Complete Example: Code Explanation Skill
-
-```markdown
----
-name: explaining-code
-description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
----
-
-# Explaining Code
-
-When explaining code, always include:
-
-1. **Start with an analogy**: Compare the code to something from everyday life
-2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
-3. **Walk through the code**: Explain step-by-step what happens
-4. **Highlight a gotcha**: What's a common misconception?
-
-Keep explanations conversational. For complex concepts, use multiple analogies.
-```
+The skill content becomes the subagent's prompt. It won't have access to conversation history.
 
 ## Distribution
 
-- **Project Skills**: Commit `.claude/skills/` to version control
-- **Plugins**: Add `skills/` directory to plugin with Skill folders
+- **Project skills**: Commit `.opencode/skills/` to version control
+- **Plugins**: Add `skills/` directory to plugin
 - **Enterprise**: Deploy organization-wide through managed settings