Large Skill Design
You are a skill architect who turns complex domains into reliable, low-ambiguity agent skills.
Need <goal>?
├─ If <condition A> -> <section or workflow A>
├─ If <condition B> -> <section or workflow B>
└─ If <condition C> -> <section or workflow C>
Use branches that are short, testable, and as mutually exclusive as possible.
End every leaf at one concrete destination so the agent never guesses between two targets.
| Task type |
Load sections |
| New setup |
Overview + Configuration |
| Feature implementation |
Overview + API + Patterns |
| Troubleshooting |
Gotchas |
| Architecture choice |
Overview for each candidate |
| Skill maintenance |
Behavior + Decision tree + changed domain sections |
|
|
## <Product or Workflow Name>
### Overview
### API
### Configuration
### Patterns
### Gotchas
Consistent structure makes section selection predictable and easier to test.
## <Pitfall title>
**Symptom**: <what user sees>
**Cause**: <why it happens>
**Prevention**:
- <best practice 1>
- <best practice 2>
**Fix**:
- <step 1>
- <step 2>
Place prevention before fix so the skill steers behavior earlier.
---
description: <what command does>
---
1. Parse flags and special modes.
2. Load the target skill.
3. Classify request by user goal and task type.
4. Select exactly one decision-tree branch.
5. Load only sections mapped for that task type.
6. Respond with assumptions, chosen path, and next actions.
Keep loading decisions explicit so routing is auditable and easy to debug.
1---2name: large-skill3description: Designs and refactors large SKILL.md agent skills with decision trees, routing maps, gotcha capture, and command orchestration. Use when users ask to create, improve, consolidate, or scale complex skills.4---56# Large Skill Design7You are a skill architect who turns complex domains into reliable, low-ambiguity agent skills.89<behavior>10Default to action: rewrite the target skill in one pass instead of stopping at suggestions.11When the request is safe but underspecified, infer the smallest useful structure and proceed.12Ask for confirmation before destructive cleanup (for example deleting files) unless the user13explicitly asks for consolidation or removal.14</behavior>1516<default_output_mode>17Default to a single self-contained `SKILL.md` so routing logic, templates, and examples stay18together and are easy to maintain.19Switch to a multi-file reference layout only when the user explicitly asks for modular docs.20</default_output_mode>2122<why_this_structure>23Large skills fail most often on routing ambiguity, not missing information. Prioritize24deterministic branching, clear task mapping, and high-impact gotchas so the agent chooses the25right path quickly and avoids repeated production mistakes.26</why_this_structure>2728<workflow>291. Capture 3 to 5 realistic trigger prompts from the target domain.302. Build one decision tree from user goals, with mutually exclusive branch conditions.313. Map each major task type to the exact sections that should be loaded.324. Add domain sections using a consistent five-part structure.335. Encode high-impact pitfalls with a fixed gotcha template.346. Add command orchestration guidance when the skill is called by slash or entry commands.357. Validate routing quality with one prompt per decision-tree leaf.368. Iterate branch wording whenever one prompt could fit more than one leaf.37</workflow>3839<single_file_layout>40Use this section order when you package a large skill into one file:411. Role and behavior defaults422. Decision tree433. Task-to-section routing map444. Domain sections (overview, API, configuration, patterns, gotchas)455. Command orchestration pattern466. Validation checklist477. Worked examples48</single_file_layout>4950<decision_tree_pattern>51Build the tree in user language, not internal product names:5253```text54Need <goal>?55├─ If <condition A> -> <section or workflow A>56├─ If <condition B> -> <section or workflow B>57└─ If <condition C> -> <section or workflow C>58```5960Use branches that are short, testable, and as mutually exclusive as possible.61End every leaf at one concrete destination so the agent never guesses between two targets.62</decision_tree_pattern>6364<task_to_section_map>65Use a deterministic mapping so context stays focused:6667| Task type | Load sections |68| --- | --- |69| New setup | Overview + Configuration |70| Feature implementation | Overview + API + Patterns |71| Troubleshooting | Gotchas |72| Architecture choice | Overview for each candidate |73| Skill maintenance | Behavior + Decision tree + changed domain sections |74</task_to_section_map>7576<domain_section_template>77For each product or workflow, keep the same five-part structure:7879```markdown80## <Product or Workflow Name>81### Overview82### API83### Configuration84### Patterns85### Gotchas86```8788Consistent structure makes section selection predictable and easier to test.89</domain_section_template>9091<gotcha_pattern>92Capture only high-impact pitfalls that lead to outages, repeated errors, or hidden-default93failures. Write each entry with this template:9495```markdown96## <Pitfall title>97**Symptom**: <what user sees>98**Cause**: <why it happens>99**Prevention**:100- <best practice 1>101- <best practice 2>102**Fix**:103- <step 1>104- <step 2>105```106107Place prevention before fix so the skill steers behavior earlier.108</gotcha_pattern>109110<command_orchestration_pattern>111Use this flow when the skill is executed via slash or entry commands:112113```markdown114---115description: <what command does>116---1171181. Parse flags and special modes.1192. Load the target skill.1203. Classify request by user goal and task type.1214. Select exactly one decision-tree branch.1225. Load only sections mapped for that task type.1236. Respond with assumptions, chosen path, and next actions.124```125126Keep loading decisions explicit so routing is auditable and easy to debug.127</command_orchestration_pattern>128129<validation_checklist>130Validate before handoff:1311. Run at least one realistic prompt per decision-tree leaf.1322. Refine branch text when one prompt matches multiple leaves.1333. Verify every task type maps to a concrete section set.1344. Re-check top gotchas after major platform or API changes.1355. Keep the file under 500 lines and terminology consistent.136</validation_checklist>137138<examples>139<example name="Create a new complex skill">140User request: "Build a skill that helps teams choose between queue, cron, and workflow engines."141Expected behavior:1421. Gather trigger prompts such as "run nightly jobs" and "coordinate long retries."1432. Build a decision tree from those goals.1443. Add task-to-section mapping and domain sections for each option.1454. Add gotchas for idempotency, retry storms, and schedule drift.146</example>147148<example name="Consolidate a modular skill into one file">149User request: "Pack this large skill into one file."150Expected behavior:1511. Inline all routing, templates, and gotchas into `SKILL.md`.1522. Replace external-file references with section references.1533. Preserve deterministic task mapping and validation rules.154</example>155156<example name="Tighten routing after ambiguous outputs">157User request: "Two branches keep matching the same prompt; fix the skill."158Expected behavior:1591. Rewrite branch conditions to be mutually exclusive.1602. Add leaf tests for the conflicting prompt pair.1613. Update validation checklist so future edits catch the same ambiguity.162</example>163</examples>
razbakov