lessweb/deepcode/skill-writer

# Personal
mkdir -p ~/.agents/skills/skill-name
 
# Project
mkdir -p .agents/skills/skill-name

skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│   └── helper.py (optional)
└── templates/
    └── template.txt (optional)

---
name: skill-name
description: Brief description of what this does and when to use it
---

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

description: Helps with documents
description: For data analysis

# Skill Name
 
Brief overview of what this Skill does.
 
## Quick start
 
Provide a simple example to get started immediately.
 
## Instructions
 
Step-by-step guidance for AI agents:
 
1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases
 
## Examples
 
Show concrete usage examples with code or commands.
 
## Best practices
 
- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use
 
## Requirements
 
List any dependencies or prerequisites:
 

 
### Step 7: Add supporting files (optional)
 
Create additional files for progressive disclosure:
 
**reference.md**: Detailed API docs, advanced options
**examples.md**: Extended examples and use cases
**scripts/**: Helper scripts and utilities
**templates/**: File templates or boilerplate
 
Reference them from SKILL.md:

 
### Step 8: Validate the Skill
 
Check these requirements:
 
✅ **File structure**:
 
- [ ] SKILL.md exists in correct location
- [ ] Directory name matches frontmatter `name`
 
✅ **YAML frontmatter**:
 
- [ ] Opening `---` on line 1
- [ ] Closing `---` before content
- [ ] Valid YAML (no tabs, correct indentation)
- [ ] `name` follows naming rules
- [ ] `description` is specific and < 1024 chars
 
✅ **Content quality**:
 
- [ ] Clear instructions for AI agents
- [ ] Concrete examples provided
- [ ] Edge cases handled
- [ ] Dependencies listed (if any)
 
✅ **Testing**:
 
- [ ] Description matches user questions
- [ ] Skill activates on relevant queries
- [ ] Instructions are clear and actionable
 
### Step 9: Test the Skill
 
1. **Restart AI agents** (if running) to load the Skill
 
2. **Ask relevant questions** that match the description:
 
   ```
   Can you help me extract text from this PDF?
   ```
 
3. **Verify activation**: AI agents should use the Skill automatically
 
4. **Check behavior**: Confirm AI agents follows the instructions correctly
 
### Step 10: Debug if needed
 
If AI agents doesn't use the Skill:
 
1. **Make description more specific**:
   - Add trigger words
   - Include file types
   - Mention common user phrases
 
2. **Check file location**:
 
   ```bash
   ls ~/.agents/skills/skill-name/SKILL.md
   ls .agents/skills/skill-name/SKILL.md
   ```
 
3. **Validate YAML**:
   ```bash
   cat SKILL.md | head -n 10
   ```
 
## Common patterns
 
### Read-only Skill
 

 
### Script-based Skill
 

 
### Multi-file Skill with progressive disclosure
 

 
## Best practices for Skill authors
 
1. **One Skill, one purpose**: Don't create mega-Skills
2. **Specific descriptions**: Include trigger words users will say
3. **Clear instructions**: Write for AI agents, not humans
4. **Concrete examples**: Show real code, not pseudocode
5. **List dependencies**: Mention required packages in description
6. **Test with teammates**: Verify activation and clarity
7. **Version your Skills**: Document changes in content
8. **Use progressive disclosure**: Put advanced details in separate files
 
## Validation checklist
 
Before finalizing a Skill, verify:
 
- [ ] Name is lowercase, hyphens only, max 64 chars
- [ ] Description is specific and < 1024 chars
- [ ] Description includes "what" and "when"
- [ ] YAML frontmatter is valid
- [ ] Instructions are step-by-step
- [ ] Examples are concrete and realistic
- [ ] Dependencies are documented
- [ ] File paths use forward slashes
- [ ] Skill activates on relevant queries
- [ ] AI agents follows instructions correctly
 
## Troubleshooting
 
**Skill doesn't activate**:
 
- Make description more specific with trigger words
- Include file types and operations in description
- Add "Use when..." clause with user phrases
 
**Multiple Skills conflict**:
 
- Make descriptions more distinct
- Use different trigger words
- Narrow the scope of each Skill
 
**Skill has errors**:
 
- Check YAML syntax (no tabs, proper indentation)
- Verify file paths (use forward slashes)
- Ensure scripts have execute permissions
- List all dependencies
 
## Examples
 
See the documentation for complete examples:
 
- Simple single-file Skill (commit-helper)
- Skill with tool permissions (code-reviewer)
- Multi-file Skill (pdf-processing)
 
## Output format
 
When creating a Skill, I will:
 
1. Ask clarifying questions about scope and requirements
2. Suggest a Skill name and location
3. Create the SKILL.md file with proper frontmatter
4. Include clear instructions and examples
5. Add supporting files if needed
6. Provide testing instructions
7. Validate against all requirements
 
The result will be a complete, working Skill that follows all best practices and validation rules.