跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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:

  1. 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?
  2. 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)
    allowed-tools: read
    
    Use for:
    • 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)
  • 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
阅读完整来源 ↗