skill-writer（技能作家）

Skill Writer Guide

Overview

This skill provides comprehensive guidance for creating Agent Skills that follow the official Agent Skills specification. Agent Skills are a simple, open format for giving agents new capabilities and expertise through folders of instructions, scripts, and resources.

What are Agent Skills?

Agent Skills are:

• Portable: Work across different AI platforms (Claude, GPT, Copilot, etc.)
• Filesystem-based: Simple directory structure with markdown files
• Modular: Each skill is self-contained and reusable
• Open format: No vendor lock-in, community-driven standard

Creating a New Agent Skill

1. Directory Structure

Every Agent Skill lives in its own directory:

skill-name/
├── SKILL.md           # Required: Main skill file with metadata and instructions
├── scripts/           # Optional: Helper scripts or tools
├── references/        # Optional: Supporting documentation
└── assets/            # Optional: Images, files, or other resources

2. SKILL.md Format

The SKILL.md file is the heart of every skill. It has two parts:

Part 1: YAML Frontmatter (Required)

At the top of SKILL.md, include YAML frontmatter with metadata:

---
name: skill-name                    # Required: lowercase, max 64 chars, matches folder name
description: Brief description      # Required: max 1024 chars, explain what and when
license: MIT                        # Optional: license identifier or file path
compatibility: Linux, Python 3.10+  # Optional: system requirements
metadata:                           # Optional: custom key-value pairs
  author: your-name
  version: "1.0"
  category: development
allowed-tools: tool1 tool2         # Optional/Experimental: approved tools
---

Required Fields:

• name: Skill identifier (lowercase, hyphens allowed, no consecutive hyphens)
• description: Clear explanation of:

- What the skill does - When to use it - Key capabilities

Optional Fields:

• license: License type (e.g., MIT, Apache-2.0) or path to LICENSE file
• compatibility: System requirements, dependencies
• metadata: Any additional info (author, version, tags, etc.)
• allowed-tools: List of tools the skill can use (experimental feature)

Part 2: Markdown Body (Instructions)

After the frontmatter, write clear instructions in markdown format:

# Skill Name Guide

## Overview
Brief introduction to the skill's purpose and capabilities.

## Quick Start
Simple example to get started quickly.

## Main Instructions
Step-by-step guidance organized by task or feature.

## Common Tasks
Frequent use cases with examples.

## Examples
Real-world examples with input/output.

## Troubleshooting
Common issues and solutions.

## Reference
Additional details, edge cases, advanced usage.

3. Writing Effective Instructions

Best Practices:

1. Be Clear and Specific

- Use simple, direct language - Provide step-by-step instructions - Include code examples where relevant

1. Structure for Scannability

- Use headers to organize content - Break long sections into subsections - Use lists, tables, and code blocks

1. Include Examples

- Show both input and output - Cover common use cases - Demonstrate edge cases

1. Keep it Focused

- One skill = one capability domain - Aim for under 5000 tokens - Link to references for details

1. Make it Actionable

- Provide complete, working examples - Include error handling patterns - Show command-line usage when relevant

4. Optional Subdirectories

scripts/

• Place executable scripts, tools, or programs
• Include installation instructions in SKILL.md
• Document each script's purpose and usage

references/

• Additional documentation
• API references
• Detailed guides
• Link from SKILL.md with relative paths

assets/

• Images, diagrams, or visual aids
• Sample files or templates
• Reference with relative paths from skill root

Complete Example

Here's a minimal but complete skill:

hello-world/
└── SKILL.md

hello-world/SKILL.md:

---
name: hello-world
description: Simple example skill that demonstrates the basic structure of an Agent Skill. Use this as a template when creating new skills.
license: MIT
metadata:
  author: example
  version: "1.0"
---

# Hello World Skill

## Overview

This is a minimal example skill that demonstrates the Agent Skills format.

## Instructions

To use this skill:

1. Create a file called `hello.txt`
2. Write "Hello, World!" to the file
3. Display the contents

## Example

echo "Hello, World!" > hello.txt cat hello.txt

Expected output:

Hello, World!

## Next Steps

Use this template to create more complex skills with additional features.

Skill Creation Checklist

When creating a new skill, verify:

• [ ] Skill name is lowercase with hyphens only
• [ ] Folder name matches the name field in frontmatter
• [ ] YAML frontmatter is valid and complete
• [ ] name field is present (required)
• [ ] description field is present and clear (required)
• [ ] Description explains WHAT the skill does
• [ ] Description explains WHEN to use it
• [ ] Description is under 1024 characters
• [ ] Instructions are clear and actionable
• [ ] Examples are provided for main use cases
• [ ] Code examples are complete and tested
• [ ] Relative paths are used for internal references
• [ ] Total content is reasonable size (aim for <5000 tokens)
• [ ] All optional files (scripts, references, assets) are documented

Common Patterns

Task-Oriented Skills

Focus on accomplishing specific tasks:

• File processing (PDF, Excel, images)
• System administration
• Testing and validation
• Code generation

Domain Expertise Skills

Provide specialized knowledge:

• Programming languages
• Frameworks and libraries
• APIs and protocols
• Best practices and patterns

Workflow Skills

Guide multi-step processes:

• Project setup
• Deployment procedures
• Review checklists
• Documentation workflows

Tips for Success

1. Start Simple: Begin with core functionality, add advanced features later
2. Test Instructions: Verify examples work as documented
3. Think Like a User: What would someone need to know to use this skill?
4. Iterate: Skills can evolve—start with v1.0 and improve over time
5. Be Consistent: Follow conventions from existing skills in your domain
6. Document Assumptions: State prerequisites and dependencies clearly
7. Handle Errors: Include troubleshooting for common issues

Naming Conventions

• Use lowercase letters
• Separate words with hyphens (kebab-case)
• Be descriptive but concise
• Avoid abbreviations unless widely known
• Match folder name to skill name

Good names:

• pdf-processing
• web-testing
• api-documentation
• code-review

Avoid:

• PDFProcessing (uppercase)
• pdf_processing (underscores)
• pdfproc (unclear abbreviation)
• skill-1 (not descriptive)

Validation

Before finalizing a skill:

1. Check YAML Syntax

- Use a YAML validator - Ensure proper indentation - Verify no syntax errors

1. Test Instructions

- Follow your own instructions step-by-step - Verify all examples work - Check all file paths

1. Review Content

- Proofread for clarity - Remove unnecessary complexity - Ensure completeness

1. Check Structure

- SKILL.md is at skill root - All referenced files exist - Paths are relative from skill root

Resources

• Specification: https://agentskills.io/specification
• Documentation: https://agentskills.io
• Examples: https://github.com/anthropics/skills
• Community: https://github.com/agentskills/agentskills
• Template: See references/template.md for a ready-to-use skill template

Advanced Features

Multi-file Skills

For complex skills, organize content across multiple files:

advanced-skill/
├── SKILL.md           # Main instructions and quick start
├── references/
│   ├── api.md        # Detailed API documentation
│   ├── examples.md   # Extended examples
│   └── troubleshoot.md
├── scripts/
│   ├── setup.sh      # Installation script
│   └── helper.py     # Utility functions
└── assets/
    └── diagram.png   # Visual aids

Reference from SKILL.md:

For detailed API documentation, see [references/api.md](references/api.md).

Using Scripts

When including scripts:

1. Document clearly in SKILL.md
2. Make executable (chmod +x script.sh)
3. Include shebang (#!/bin/bash or #!/usr/bin/env python3)
4. Add comments explaining key steps
5. Handle errors gracefully

Example script reference:

## Installation

Run the setup script:

chmod +x scripts/setup.sh ./scripts/setup.sh

The script will:
1. Check system requirements
2. Install dependencies
3. Configure the environment

Tool Restrictions

Use the allowed-tools field (experimental) to specify approved tools:

---
name: secure-skill
description: Skill with restricted tool access
allowed-tools: pdftotext qpdf
---

This helps ensure skills only use vetted, secure tools.

Conclusion

Agent Skills provide a simple, powerful way to give AI agents specialized capabilities. By following this guide and the official specification, you can create high-quality skills that work across platforms and help agents perform better at specific tasks.

Start simple, iterate based on feedback, and share your skills with the community!