@pilllesss/yorn 1.0.128 → 1.0.129

package/dist/skills/subagent/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: "subagent"
+description: "Delegate tasks, perform parallel research, or run focused subtasks using a stateless child Yorn agent via bash. Use when a task requires deep isolated research, executing tasks in parallel, running read-only code analysis without polluting current conversation context, or executing subtasks in a fresh unsaved session."
+---
+
+# Subagent Task Delegation via Yorn CLI
+
+This skill teaches how to spawn and manage child subagents using `yorn` CLI commands executed directly through the `bash` tool. Each subagent runs as an independent, stateless child session without persisting session history (`--no-session`), returning results directly to your bash output.
+
+---
+
+## 🚀 Core Command Patterns
+
+### 1. Direct Execution (Standard Delegation)
+Run a self-contained subtask. The result prints directly to stdout in the bash tool result:
+
+```bash
+yorn -p --no-session "Your complete, self-contained prompt here"
+```
+
+### 2. JSON Mode Output (Structured Output)
+When you need machine-readable JSON output (message arrays, token usage, tool calls):
+
+```bash
+yorn --mode json -p --no-session "Your prompt here"
+```
+
+### 3. Tool-Restricted Subagents
+Restrict the child's available tools to limit scope and improve security (e.g. read-only search):
+
+```bash
+# Read-only exploration agent
+yorn -p --no-session --tools read,grep,find,ls "Search for authentication logic in src/ and summarize"
+
+# Pure computation / reasoning (no tools allowed)
+yorn -p --no-session --no-tools "Explain the time complexity and edge cases of this algorithm..."
+```
+
+### 4. Custom Model & Thinking Level
+Use a faster or specialized model for lightweight tasks, or adjust reasoning effort:
+
+```bash
+# Use a specific provider/model
+yorn -p --no-session --model openrouter/anthropic/claude-3.5-sonnet "Refactor this function"
+
+# Set thinking/reasoning level: off, minimal, low, medium, high
+yorn -p --no-session --thinking high "Solve this complex architectural problem"
+```
+
+### 5. Custom Persona / System Prompt
+Define a specialized role for the child agent:
+
+```bash
+yorn -p --no-session \
+  --system-prompt "You are an expert security auditor. Review code strictly for OWASP vulnerabilities." \
+  "Audit the authentication endpoints in src/api/"
+```
+
+---
+
+## ⚡ Multiple Subtasks
+
+When breaking down a large task into multiple independent subtasks, execute them sequentially or run them in separate bash tool calls to collect each result directly:
+
+```bash
+yorn -p --no-session "Analyze package.json dependencies and identify potential security risks"
+```
+
+```bash
+yorn -p --no-session "Check tsconfig.json and suggest compiler options for stricter type safety"
+```
+
+---
+
+## 📋 Best Practices
+
+1. **Always use `--no-session` and `-p` (or `--mode json -p`):**
+   - `--no-session`: Prevents saving dummy sessions into `~/.yorn/agent/sessions/`.
+   - `-p` / `--print`: Runs in non-interactive print mode and outputs directly to stdout.
+
+2. **Direct Output (No File Redirection Needed):**
+   - The CLI outputs the answer straight to bash stdout. Do not pipe to temporary files unless you explicitly need to save the file for later use.
+
+3. **Provide Complete, Self-Contained Prompts:**
+   - The child agent **does not share or see the parent conversation history**.
+   - Include all necessary context, file paths, requirements, and formatting instructions in the prompt.
+
+4. **Quote Prompts Safely:**
+   - Wrap prompts in double quotes in bash, or pass multiline prompts via heredocs (`<<'EOF'`):
+
+```bash
+yorn -p --no-session <<'EOF'
+Review the following code and check for potential null pointer exceptions:
+[Paste code or description here]
+EOF
+```
+
+5. **Prevent Infinite Recursion:**
+   - Do not instruct child subagents to spawn further subagents.