1  ---
  2  name: skill-creator
  3  description: Create, edit, improve, or audit skills for SwarmClaw agents. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory. Triggers on phrases like "create a skill", "author a skill", "tidy up a skill", "improve this skill", "review the skill", "clean up the skill", "audit the skill".
  4  ---
  5  
  6  # Skill Creator
  7  
  8  Guidance for creating effective skills that extend SwarmClaw agent capabilities.
  9  
 10  ## About Skills
 11  
 12  Skills are modular, self-contained packages that provide specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized one equipped with procedural knowledge that no model can fully possess.
 13  
 14  ### What Skills Provide
 15  
 16  1. Specialized workflows — multi-step procedures for specific domains
 17  2. Tool integrations — instructions for working with specific file formats or APIs
 18  3. Domain expertise — company-specific knowledge, schemas, business logic
 19  4. Bundled resources — scripts, references, and assets for complex and repetitive tasks
 20  
 21  ## Core Principles
 22  
 23  ### Concise is Key
 24  
 25  The context window is a shared resource. Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" Prefer concise examples over verbose explanations.
 26  
 27  ### Set Appropriate Degrees of Freedom
 28  
 29  - **High freedom** (text instructions): Multiple valid approaches, context-dependent decisions
 30  - **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists, some variation OK
 31  - **Low freedom** (specific scripts): Fragile operations, consistency critical, exact sequence required
 32  
 33  ### Anatomy of a Skill
 34  
 35  ```
 36  skill-name/
 37  ├── SKILL.md (required)
 38  │   ├── YAML frontmatter (name + description, required)
 39  │   └── Markdown instructions (required)
 40  └── Bundled Resources (optional)
 41      ├── scripts/      — Executable code (Python/Bash/etc.)
 42      ├── references/   — Documentation loaded into context as needed
 43      └── assets/       — Files used in output (templates, icons, fonts)
 44  ```
 45  
 46  #### Frontmatter
 47  
 48  - `name`: Skill name (hyphen-case, lowercase)
 49  - `description`: Primary triggering mechanism. Include what the skill does AND when to use it. All "when to use" info goes here — not in the body.
 50  
 51  #### Scripts (`scripts/`)
 52  
 53  Executable code for tasks that require deterministic reliability or are repeatedly rewritten. Token efficient and may be executed without loading into context.
 54  
 55  #### References (`references/`)
 56  
 57  Documentation loaded as needed to inform the agent's process. Keep only essential instructions in SKILL.md; move detailed reference material here.
 58  
 59  #### Assets (`assets/`)
 60  
 61  Files not loaded into context but used in output (templates, images, fonts). Separates output resources from documentation.
 62  
 63  ### What NOT to Include
 64  
 65  - README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other auxiliary docs
 66  - Setup/testing procedures or user-facing documentation
 67  - Information the agent already knows from general training
 68  
 69  ## Skill Creation Process
 70  
 71  1. Understand the skill with concrete examples
 72  2. Plan reusable contents (scripts, references, assets)
 73  3. Initialize the skill
 74  4. Edit the skill (implement resources, write SKILL.md)
 75  5. Validate the skill
 76  6. Iterate based on real usage
 77  
 78  ### Skill Naming
 79  
 80  - Lowercase letters, digits, and hyphens only (hyphen-case)
 81  - Under 64 characters
 82  - Prefer short, verb-led phrases describing the action
 83  - Name the skill folder exactly after the skill name
 84  
 85  ### Step 1: Understanding with Concrete Examples
 86  
 87  Ask the user clarifying questions:
 88  
 89  - What functionality should the skill support?
 90  - Can you give examples of how it would be used?
 91  - What would a user say that should trigger this skill?
 92  
 93  ### Step 2: Planning Reusable Contents
 94  
 95  Analyze each example to identify what scripts, references, and assets would be helpful:
 96  
 97  - **Repeated code** → `scripts/` (e.g., `scripts/rotate_pdf.py`)
 98  - **Boilerplate** → `assets/` (e.g., `assets/hello-world/` template)
 99  - **Domain knowledge** → `references/` (e.g., `references/schema.md`)
100  
101  ### Step 3: Initializing the Skill
102  
103  Use the bundled init script to create the directory structure:
104  
105  ```bash
106  python3 {baseDir}/scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
107  ```
108  
109  Examples:
110  
111  ```bash
112  python3 {baseDir}/scripts/init_skill.py my-skill --path skills
113  python3 {baseDir}/scripts/init_skill.py my-skill --path skills --resources scripts,references
114  ```
115  
116  ### Step 4: Edit the Skill
117  
118  Write instructions that would help another agent instance execute tasks effectively. Include information that is beneficial and non-obvious.
119  
120  **Writing guidelines:** Use imperative/infinitive form. Keep SKILL.md body under 500 lines.
121  
122  **Frontmatter description:** Include both what the skill does and specific triggers for when to use it. This is the primary mechanism for skill selection.
123  
124  ### Step 5: Validate the Skill
125  
126  Run the validator to check structure and frontmatter:
127  
128  ```bash
129  python3 {baseDir}/scripts/quick_validate.py <path/to/skill-folder>
130  ```
131  
132  ### Step 6: Iterate
133  
134  1. Use the skill on real tasks
135  2. Notice struggles or inefficiencies
136  3. Update SKILL.md or bundled resources
137  4. Test again
138  
139  ## Progressive Disclosure
140  
141  Skills use a three-level loading system:
142  
143  1. **Metadata** (name + description) — always in context (~100 words)
144  2. **SKILL.md body** — when skill triggers (<5k words)
145  3. **Bundled resources** — as needed (unlimited, since scripts can be executed without reading)
146  
147  Keep SKILL.md lean. Move detailed information to reference files and describe clearly when to read them.