skill-writer
Guide users through creating, updating, debugging, and validating Agent Skills for AI agents. Use when the user wants to create, write, author, design, troubleshoot, validate, or improve a Skill, or needs help with SKILL.md, frontmatter, or skill structure.
lessweb · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add lessweb/deepcode-cli --skill skill-writer技能说明
name: skill-writer description: Guide users through creating, updating, debugging, and validating Agent Skills for AI agents. Use when the user wants to create, write, author, design, troubleshoot, validate, or improve a Skill, or needs help with SKILL.md, frontmatter, or skill structure.
Skill Writer
This Skill helps you create well-structured Agent Skills for AI agents that follow best practices and validation requirements.
When to use this Skill
Use this Skill when:
- Creating a new Agent Skill
- Writing or updating SKILL.md files
- Designing skill structure and frontmatter
- Troubleshooting skill discovery issues
- Converting existing prompts or workflows into Skills
Instructions
Step 1: Determine Skill scope
First, understand what the Skill should do:
-
Ask clarifying questions:
- What specific capability should this Skill provide?
- When should AI agents use this Skill?
- What tools or resources does it need?
- Is this for personal use or team sharing?
-
Keep it focused: One Skill = one capability
- Good: "PDF form filling", "Excel data analysis"
- Too broad: "Document processing", "Data tools"
Step 2: Choose Skill location
Determine where to create the Skill:
Personal Skills (~/.agents/skills/):
- Individual workflows and preferences
- Experimental Skills
- Personal productivity tools
Project Skills (.agents/skills/):
- Team workflows and conventions
- Project-specific expertise
- Shared utilities (committed to git)
Step 3: Create Skill structure
Create the directory and files:
# Personal
mkdir -p ~/.agents/skills/skill-name
# Project
mkdir -p .agents/skills/skill-name
For multi-file Skills:
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│ └── helper.py (optional)
└── templates/
└── template.txt (optional)
Step 4: Write SKILL.md frontmatter
Create YAML frontmatter with required fields:
---
name: skill-name
description: Brief description of what this does and when to use it
---
Field requirements:
-
name:
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- Must match directory name
- Good:
pdf-processor,git-commit-helper - Bad:
PDF_Processor,Git Commits!
-
description:
- Max 1024 characters
- Include BOTH what it does AND when to use it
- Use specific trigger words users would say
- Mention file types, operations, and context
Optional frontmatter fields:
- allowed-tools: Restrict tool access (comma-separated list)
Use for:allowed-tools: read- Read-only Skills
- Security-sensitive workflows
- Limited-scope operations
Step 5: Write effective descriptions
The description is critical for AI agents to discover your Skill.
Formula: [What it does] + [When to use it] + [Key triggers]
Examples:
✅ Good:
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.
✅ Good:
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
❌ Too vague:
description: Helps with documents
description: For data analysis
Tips:
- Include specific file extensions (.pdf, .xlsx, .json)
- Mention common user phrases ("analyze", "extract", "generate")
- List concrete operations (not generic verbs)
- Add context clues ("Use when...", "For...")
Step 6: Structure the Skill content
Use clear Markdown sections:
# 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:
```bash
pip install package-name
```
Advanced usage
For complex scenarios, see reference.md.
### 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:
```markdown
For advanced usage, see [reference.md](reference.md).
Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`
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)
-
namefollows naming rules -
descriptionis 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
-
Restart AI agents (if running) to load the Skill
-
Ask relevant questions that match the description:
Can you help me extract text from this PDF? -
Verify activation: AI agents should use the Skill automatically
-
Check behavior: Confirm AI agents follows the instructions correctly
Step 10: Debug if needed
If AI agents doesn't use the Skill:
- *Make description more specific