From 24d065c43a4342b0a19f2502ed126ed1ea72f7c4 Mon Sep 17 00:00:00 2001 From: Sisyphus Date: Sun, 25 Jan 2026 13:45:00 +0900 Subject: [PATCH] fix: update documentation to use load_skills instead of skills parameter (#1088) All documentation, agent prompts, and skill descriptions were still referencing the old 'skills' parameter name for delegate_task, but the tool implementation requires 'load_skills' (renamed in commit aa2b052). This caused confusion and errors for users following the docs. Fixes #1008 Co-authored-by: sisyphus-dev-ai --- docs/category-skill-guide.md | 12 +++---- docs/configurations.md | 2 +- .../understanding-orchestration-system.md | 10 +++--- sisyphus-prompt.md | 32 +++++++++---------- src/agents/atlas.ts | 8 ++--- src/agents/sisyphus.ts | 8 ++--- .../builtin-skills/git-master/SKILL.md | 2 +- src/features/builtin-skills/skills.ts | 2 +- 8 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/category-skill-guide.md b/docs/category-skill-guide.md index 377b212f2..04cb028a5 100644 --- a/docs/category-skill-guide.md +++ b/docs/category-skill-guide.md @@ -70,12 +70,12 @@ A Skill is a mechanism that injects **specialized knowledge (Context)** and **to ### Usage -Add desired skill names to the `skills` array. +Add desired skill names to the `load_skills` array. ```typescript delegate_task( category="quick", - skills=["git-master"], + load_skills=["git-master"], prompt="Commit current changes. Follow commit message style." ) ``` @@ -110,17 +110,17 @@ You can create powerful specialized agents by combining Categories and Skills. ### 🎨 The Designer (UI Implementation) - **Category**: `visual-engineering` -- **Skills**: `["frontend-ui-ux", "playwright"]` +- **load_skills**: `["frontend-ui-ux", "playwright"]` - **Effect**: Implements aesthetic UI and verifies rendering results directly in browser. ### 🏗️ The Architect (Design Review) - **Category**: `ultrabrain` -- **Skills**: `[]` (pure reasoning) +- **load_skills**: `[]` (pure reasoning) - **Effect**: Leverages GPT-5.2's logical reasoning for in-depth system architecture analysis. ### ⚡ The Maintainer (Quick Fixes) - **Category**: `quick` -- **Skills**: `["git-master"]` +- **load_skills**: `["git-master"]` - **Effect**: Uses cost-effective models to quickly fix code and generate clean commits. --- @@ -131,7 +131,7 @@ When delegating, **clear and specific** prompts are essential. Include these 7 e 1. **TASK**: What needs to be done? (single objective) 2. **EXPECTED OUTCOME**: What is the deliverable? -3. **REQUIRED SKILLS**: Which skills should be used? +3. **REQUIRED SKILLS**: Which skills should be loaded via `load_skills`? 4. **REQUIRED TOOLS**: Which tools must be used? (whitelist) 5. **MUST DO**: What must be done (constraints) 6. **MUST NOT DO**: What must never be done diff --git a/docs/configurations.md b/docs/configurations.md index 0ade649f7..677350893 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -160,7 +160,7 @@ Available agents: `oracle`, `librarian`, `explore`, `multimodal-looker` Oh My OpenCode includes built-in skills that provide additional capabilities: - **playwright**: Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions. -- **git-master**: Git expert for atomic commits, rebase/squash, and history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with `delegate_task(category='quick', skills=['git-master'], ...)` to save context. +- **git-master**: Git expert for atomic commits, rebase/squash, and history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with `delegate_task(category='quick', load_skills=['git-master'], ...)` to save context. Disable built-in skills via `disabled_skills` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`: diff --git a/docs/guide/understanding-orchestration-system.md b/docs/guide/understanding-orchestration-system.md index c956a8ce0..8af82b444 100644 --- a/docs/guide/understanding-orchestration-system.md +++ b/docs/guide/understanding-orchestration-system.md @@ -326,13 +326,13 @@ Skills prepend specialized instructions to subagent prompts: // Category + Skill combination delegate_task( category="visual-engineering", - skills=["frontend-ui-ux"], // Adds UI/UX expertise + load_skills=["frontend-ui-ux"], // Adds UI/UX expertise prompt="..." ) delegate_task( category="general", - skills=["playwright"], // Adds browser automation expertise + load_skills=["playwright"], // Adds browser automation expertise prompt="..." ) ``` @@ -341,8 +341,8 @@ delegate_task( | Before | After | |--------|-------| -| Hardcoded: `frontend-ui-ux-engineer` (Gemini 3 Pro) | `category="visual-engineering" + skills=["frontend-ui-ux"]` | -| One-size-fits-all | `category="visual-engineering" + skills=["unity-master"]` | +| Hardcoded: `frontend-ui-ux-engineer` (Gemini 3 Pro) | `category="visual-engineering" + load_skills=["frontend-ui-ux"]` | +| One-size-fits-all | `category="visual-engineering" + load_skills=["unity-master"]` | | Model bias | Category-based: model abstraction eliminates bias | --- @@ -365,7 +365,7 @@ sequenceDiagram Note over Orchestrator: Prompt Structure:
1. TASK (exact checkbox)
2. EXPECTED OUTCOME
3. REQUIRED SKILLS
4. REQUIRED TOOLS
5. MUST DO
6. MUST NOT DO
7. CONTEXT + Wisdom - Orchestrator->>Junior: delegate_task(category, skills, prompt) + Orchestrator->>Junior: delegate_task(category, load_skills, prompt) Junior->>Junior: Create todos, execute Junior->>Junior: Verify (lsp_diagnostics, tests) diff --git a/sisyphus-prompt.md b/sisyphus-prompt.md index bd7ce018a..263e9c040 100644 --- a/sisyphus-prompt.md +++ b/sisyphus-prompt.md @@ -239,7 +239,7 @@ Ask yourself: I will use delegate_task with: - **Category**: [selected-category-name] - **Why this category**: [how category description matches task domain] -- **Skills**: [list of selected skills] +- **load_skills**: [list of selected skills] - **Skill evaluation**: - [skill-1]: INCLUDED because [reason based on skill description] - [skill-2]: OMITTED because [reason why skill domain doesn't apply] @@ -256,7 +256,7 @@ I will use delegate_task with: I will use delegate_task with: - **Category**: [category-name] - **Why this category**: Category description says "[quote description]" which matches this task's requirements -- **Skills**: ["skill-a", "skill-b"] +- **load_skills**: ["skill-a", "skill-b"] - **Skill evaluation**: - skill-a: INCLUDED - description says "[quote]" which applies to this task - skill-b: INCLUDED - description says "[quote]" which is needed here @@ -265,7 +265,7 @@ I will use delegate_task with: delegate_task( category="[category-name]", - skills=["skill-a", "skill-b"], + load_skills=["skill-a", "skill-b"], prompt="..." ) ``` @@ -276,12 +276,12 @@ delegate_task( I will use delegate_task with: - **Agent**: [agent-name] - **Reason**: This requires [agent's specialty] based on agent description -- **Skills**: [] (agents have built-in expertise) +- **load_skills**: [] (agents have built-in expertise) - **Expected Outcome**: [what agent should return] delegate_task( subagent_type="[agent-name]", - skills=[], + load_skills=[], prompt="..." ) ``` @@ -292,13 +292,13 @@ delegate_task( I will use delegate_task with: - **Agent**: explore - **Reason**: Need to find all authentication implementations across the codebase - this is contextual grep -- **Skills**: [] +- **load_skills**: [] - **Expected Outcome**: List of files containing auth patterns delegate_task( subagent_type="explore", run_in_background=true, - skills=[], + load_skills=[], prompt="Find all authentication implementations in the codebase" ) ``` @@ -306,7 +306,7 @@ delegate_task( **WRONG: No Skill Evaluation** ``` -delegate_task(category="...", skills=[], prompt="...") // Where's the justification? +delegate_task(category="...", load_skills=[], prompt="...") // Where's the justification? ``` **WRONG: Vague Category Selection** @@ -329,11 +329,11 @@ I'll use this category because it seems right. ```typescript // CORRECT: Always background, always parallel // Contextual Grep (internal) -delegate_task(subagent_type="explore", run_in_background=true, skills=[], prompt="Find auth implementations in our codebase...") -delegate_task(subagent_type="explore", run_in_background=true, skills=[], prompt="Find error handling patterns here...") +delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="Find auth implementations in our codebase...") +delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="Find error handling patterns here...") // Reference Grep (external) -delegate_task(subagent_type="librarian", run_in_background=true, skills=[], prompt="Find JWT best practices in official docs...") -delegate_task(subagent_type="librarian", run_in_background=true, skills=[], prompt="Find how production apps handle auth in Express...") +delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="Find JWT best practices in official docs...") +delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="Find how production apps handle auth in Express...") // Continue working immediately. Collect with background_output when needed. // WRONG: Sequential or blocking @@ -416,7 +416,7 @@ Skills inject specialized instructions into the subagent. Read the description t For EVERY skill listed above, ask yourself: > "Does this skill's expertise domain overlap with my task?" -- If YES → INCLUDE in `skills=[...]` +- If YES → INCLUDE in `load_skills=[...]` - If NO → You MUST justify why (see below) **STEP 3: Justify Omissions** @@ -444,14 +444,14 @@ SKILL EVALUATION for "[skill-name]": ```typescript delegate_task( category="[selected-category]", - skills=["skill-1", "skill-2"], // Include ALL relevant skills + load_skills=["skill-1", "skill-2"], // Include ALL relevant skills prompt="..." ) ``` **ANTI-PATTERN (will produce poor results):** ```typescript -delegate_task(category="...", skills=[], prompt="...") // Empty skills without justification +delegate_task(category="...", load_skills=[], prompt="...") // Empty load_skills without justification ``` ### Delegation Table: @@ -724,7 +724,7 @@ If the user's approach seems problematic: | **Error Handling** | Empty catch blocks `catch(e) {}` | | **Testing** | Deleting failing tests to "pass" | | **Search** | Firing agents for single-line typos or obvious syntax errors | -| **Delegation** | Using `skills=[]` without justifying why no skills apply | +| **Delegation** | Using `load_skills=[]` without justifying why no skills apply | | **Debugging** | Shotgun debugging, random changes | ## Soft Guidelines diff --git a/src/agents/atlas.ts b/src/agents/atlas.ts index f8a65ffea..36fa8a373 100644 --- a/src/agents/atlas.ts +++ b/src/agents/atlas.ts @@ -58,7 +58,7 @@ Categories spawn \`Sisyphus-Junior-{category}\` with optimized settings: ${categoryRows.join("\n")} \`\`\`typescript -delegate_task(category="[category-name]", skills=[...], prompt="...") +delegate_task(category="[category-name]", load_skills=[...], prompt="...") \`\`\`` } @@ -84,12 +84,12 @@ ${skillRows.join("\n")} **MANDATORY: Evaluate ALL skills for relevance to your task.** Read each skill's description and ask: "Does this skill's domain overlap with my task?" -- If YES: INCLUDE in skills=[...] +- If YES: INCLUDE in load_skills=[...] - If NO: You MUST justify why in your pre-delegation declaration **Usage:** \`\`\`typescript -delegate_task(category="[category]", skills=["skill-1", "skill-2"], prompt="...") +delegate_task(category="[category]", load_skills=["skill-1", "skill-2"], prompt="...") \`\`\` **IMPORTANT:** @@ -102,7 +102,7 @@ function buildDecisionMatrix(agents: AvailableAgent[], userCategories?: Record - `| ${getCategoryDescription(name, userCategories)} | \`category="${name}", skills=[...]\` |` + `| ${getCategoryDescription(name, userCategories)} | \`category="${name}", load_skills=[...]\` |` ) const agentRows = agents.map((a) => { diff --git a/src/agents/sisyphus.ts b/src/agents/sisyphus.ts index 70fd40464..380aff0d8 100644 --- a/src/agents/sisyphus.ts +++ b/src/agents/sisyphus.ts @@ -144,11 +144,11 @@ ${librarianSection} \`\`\`typescript // CORRECT: Always background, always parallel // Contextual Grep (internal) -delegate_task(subagent_type="explore", run_in_background=true, skills=[], prompt="Find auth implementations in our codebase...") -delegate_task(subagent_type="explore", run_in_background=true, skills=[], prompt="Find error handling patterns here...") +delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="Find auth implementations in our codebase...") +delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="Find error handling patterns here...") // Reference Grep (external) -delegate_task(subagent_type="librarian", run_in_background=true, skills=[], prompt="Find JWT best practices in official docs...") -delegate_task(subagent_type="librarian", run_in_background=true, skills=[], prompt="Find how production apps handle auth in Express...") +delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="Find JWT best practices in official docs...") +delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="Find how production apps handle auth in Express...") // Continue working immediately. Collect with background_output when needed. // WRONG: Sequential or blocking diff --git a/src/features/builtin-skills/git-master/SKILL.md b/src/features/builtin-skills/git-master/SKILL.md index edd0a9780..39af06a65 100644 --- a/src/features/builtin-skills/git-master/SKILL.md +++ b/src/features/builtin-skills/git-master/SKILL.md @@ -1,6 +1,6 @@ --- name: git-master -description: "MUST USE for ANY git operations. Atomic commits, rebase/squash, history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with delegate_task(category='quick', skills=['git-master'], ...) to save context. Triggers: 'commit', 'rebase', 'squash', 'who wrote', 'when was X added', 'find the commit that'." +description: "MUST USE for ANY git operations. Atomic commits, rebase/squash, history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with delegate_task(category='quick', load_skills=['git-master'], ...) to save context. Triggers: 'commit', 'rebase', 'squash', 'who wrote', 'when was X added', 'find the commit that'." --- # Git Master Agent diff --git a/src/features/builtin-skills/skills.ts b/src/features/builtin-skills/skills.ts index 75cc9e5eb..66bff8e99 100644 --- a/src/features/builtin-skills/skills.ts +++ b/src/features/builtin-skills/skills.ts @@ -95,7 +95,7 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo const gitMasterSkill: BuiltinSkill = { name: "git-master", description: - "MUST USE for ANY git operations. Atomic commits, rebase/squash, history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with delegate_task(category='quick', skills=['git-master'], ...) to save context. Triggers: 'commit', 'rebase', 'squash', 'who wrote', 'when was X added', 'find the commit that'.", + "MUST USE for ANY git operations. Atomic commits, rebase/squash, history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with delegate_task(category='quick', load_skills=['git-master'], ...) to save context. Triggers: 'commit', 'rebase', 'squash', 'who wrote', 'when was X added', 'find the commit that'.", template: `# Git Master Agent You are a Git expert combining three specializations: