skill generator
- Repo stars 679
- Author repo swarm-tools
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @joelhooks · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Bun · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Skill Generator
Generate new skills with proper format, structure, and conventions. This meta-skill helps agents create skills without hallucinating the format.
## Quick Start
To generate a new skill:
```bash
bash scripts/generate-skill.sh <skill-name> [target-directory]
```
This creates a complete skill scaffold with:
- SKILL.md with proper frontmatter
- scripts/ directory for executable helpers
- references/ directory for documentation
- Placeholder content following conventions
## Skill Format Conventions
Every skill MUST include:
1. **SKILL.md** (required) - Main skill file with:
- YAML frontmatter (name, description)
- Markdown body with instructions
2. **Bundled Resources** (optional):
- `scripts/` - Executable code (bash/python/etc)
- `references/` - Documentation loaded on-demand
- `assets/` - Files used in output (templates, etc)
### Frontmatter Requirements
```yaml
---
name: skill-name
description: What the skill does AND when to use it. Include triggering scenarios.
---
```
The description field is critical for skill discovery and triggering. Include:
- What the skill does
- When to use it (specific triggers)
- What contexts activate it
### Directory Structure
```
skill-name/
├── SKILL.md (required)
├── scripts/ (optional)
│ └── example-script.sh
├── references/ (optional)
│ └── conventions.md
└── assets/ (optional)
└── template-file
```
## Writing Effective Skills
### Keep SKILL.md Lean
Target <500 lines in SKILL.md. Move detailed content to references/:
- Core workflow → SKILL.md
- Detailed examples → references/
- API docs → references/
- Long explanations → references/
### Use Imperative Form
Write instructions as commands:
- "Read the file first" ✓
- "You should read the file" ✗
- "Check for patterns" ✓
- "Consider checking patterns" ✗
### Progressive Disclosure
Skills use three-level loading:
1. **Metadata** (~100 words) - Always in context
2. **SKILL.md body** (<5k words) - When skill triggers
3. **Bundled resources** (unlimited) - Loaded as needed
## Bundled Resources
### scripts/
Executable code for deterministic tasks:
- When the same code is rewritten repeatedly
- When reliability is critical
- Run via bash/python without loading to context
Make scripts executable:
```bash
chmod +x scripts/my-script.sh
```
### references/
Documentation loaded on-demand:
- Database schemas
- API documentation
- Detailed workflow guides
- Domain knowledge
Keep reference files focused. For files >100 lines, include a table of contents.
Reference from SKILL.md with clear guidance on when to read:
```markdown
See references/api-docs.md for complete API reference.
```
### assets/
Files used in output (not loaded to context):
- Templates
- Images/icons
- Boilerplate code
- Fonts/typography
## What NOT to Include
Do NOT create these files:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
Skills should contain only what an AI agent needs to execute the task. No auxiliary documentation.
## Validation
Before finalizing, validate the skill:
```bash
bun scripts/validate-skill.ts path/to/skill
```
Checks:
- YAML frontmatter format
- Required fields present
- No TODO placeholders
- No extraneous files
- Naming conventions
## Reference
See references/conventions.md for complete skill format specification.
Sections and files
Listed in source order.
sections -> Quick Start → Skill Format Conventions → Frontmatter Requirements → Directory Structure → Writing Effective Skills → Keep SKILL.md Lean
terms -> SKILL.md · Bundled Resources · Metadata · SKILL.md body · Bundled resources
files/cmd -> scripts/ · references/ · assets/ · scripts/generate-skill.sh · bash/python/etc · conventions.md · bash/python · scripts/my-script.sh
body sha256 -> 90fb1a61b871
Quick Start
To generate a new skill: This creates a complete skill scaffold with: SKILL.md with proper frontmatter scripts/ directory for executable helpers references/ directory for documentation
Skill Format Conventions
Every skill MUST include: SKILL.md (required) - Main skill file with: YAML frontmatter (name, description) Markdown body with instructions Bundled Resources (optional):
Frontmatter Requirements
The description field is critical for skill discovery and triggering. Include: What the skill does When to use it (specific triggers) What contexts activate it
Keep SKILL.md Lean
Target <500 lines in SKILL.md. Move detailed content to references/: Core workflow → SKILL.md Detailed examples → references/ API docs → references/ Long explanations → references/
Use Imperative Form
Write instructions as commands: "Read the file first" ✓ "You should read the file" ✗ "Check for patterns" ✓ "Consider checking patterns" ✗