Skip to content

aboylabs/ai-agent-skills / skills/mattpocock/productivity/write-a-skill

write-a-skill

Verified

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

FileKindSize
REFERENCE.mdmarkdown5.3 KB
SKILL.mdskill md3.1 KB

REFERENCE.md

View on GitHub
# Skill Writing Reference

Complete reference for writing high-quality agent skills.

---

## Skill Structure

### Required Components

1. **YAML Frontmatter**
   ```yaml
   ---
   name: skill-name
   description: Brief description (one sentence)
   ---
   ```

2. **Main Heading**
   ```markdown
   # Skill Name
   ```

3. **Core Sections**
   - When to Use
   - How It Works
   - Examples

---

## YAML Frontmatter Fields

### Required Fields

- **name**: Lowercase, hyphens/underscores, max 64 chars
- **description**: One-sentence summary, under 200 chars

### Optional Fields

- **tags**: Array of keywords for discovery
- **category**: Skill category (e.g., 'devops', 'creative')
- **version**: Semantic version (e.g., '1.0.0')
- **author**: Author name or GitHub username
- **disable-model-invocation**: Set to `true` for prompt-only skills

---

## Content Guidelines

### When to Use Section

Describe trigger conditions:
- User intent patterns
- Keywords that should activate the skill
- Specific scenarios

**Example:**
```markdown
## When to Use

- User mentions "code review" or "review my code"
- Before merging any pull request
- When implementing critical features
```

### How It Works Section

Explain the process:
- Step-by-step workflow
- What the agent will do
- Expected outcomes

**Example:**
```markdown
## How It Works

1. Read the changed files
2. Check for common issues
3. Provide actionable feedback
4. Suggest improvements
```

### Examples Section

Provide concrete examples:
- Real-world use cases
- Sample inputs/outputs
- Code snippets

**Example:**
```markdown
## Examples

### Basic Usage

User: "Review my changes"

Agent: [Reads files, analyzes code, provides feedback]
```

---

## Best Practices

### Writing Style

- **Be concise**: One skill, one purpose
- **Be specific**: Clear trigger conditions
- **Be actionable**: Concrete steps, not vague advice
- **Be complete**: Include all necessary context

### Skill Naming

- Use lowercase with hyphens: `code-review-and-quality`
- Be descriptive: Name should indicate purpose
- Avoid abbreviations unless widely known
- Keep under 64 characters

### Description Writing

- One sentence, under 200 characters
- Start with action verb: "Automates...", "Guides...", "Validates..."
- Include trigger hint: "Use when..."
- Be specific about what it does

---

## Common Patterns

### Workflow Skills

For multi-step processes:

```markdown
## Process

1. **Step 1**: Description
   - Sub-step A
   - Sub-step B

2. **Step 2**: Description
   - Sub-step A
   - Sub-step B
```

### Validation Skills

For checking/validating:

```markdown
## Validation Checklist

- [ ] Check A
- [ ] Check B
- [ ] Check C

## What to Look For

- Issue 1: How to detect, how to fix
- Issue 2: How to detect, how to fix
```

### Template Skills

For generating content:

```markdown
## Template

\`\`\`
[Template content here]
\`\`\`

## Customization

- Field 1: Description
- Field 2: Description
```

---

## File Organization

### Single-File Skills

Simple skills in one SKILL.md:

```
skill-name/
└── SKILL.md
```

### Multi-File Skills

Complex skills with supporting files:

```
skill-name/
├── SKILL.md
├── references/
│   ├── api-docs.md
│   └── examples.md
├── templates/
│   └── config.yaml
└── scripts/
    └── helper.sh
```

---

## Testing Your Skill

### Validation Checklist

- [ ] YAML frontmatter is valid
- [ ] Name is lowercase with hyphens
- [ ] Description is under 200 chars
- [ ] Has main heading
- [ ] Has "When to Use" section
- [ ] Has clear examples
- [ ] No broken links
- [ ] No typos

### Manual Testing

1. Install the skill
2. Trigger it with test input
3. Verify expected behavior
4. Check edge cases

---

## Examples of Great Skills

### Minimal Skill

```markdown
---
name: zoom-out
description: Request broader context or higher-level perspective
---

# Zoom Out

## When to Use

When you're unfamiliar with code and need the big picture.

## Request

I don't know this area well. Go up a layer of abstraction. 
Give me a map of relevant modules and callers.
```

### Complete Skill

```markdown
---
name: code-review-and-quality
description: Conduct multi-axis code review before merging
tags: [code-review, quality, testing]
---

# Code Review and Quality

## When to Use

- Before merging any pull request
- When implementing critical features
- After major refactoring

## Review Checklist

### Correctness
- [ ] Logic is sound
- [ ] Edge cases handled
- [ ] No obvious bugs

### Quality
- [ ] Code is readable
- [ ] Names are clear
- [ ] No duplication

### Testing
- [ ] Tests exist
- [ ] Tests pass
- [ ] Coverage adequate

## Process

1. Read all changed files
2. Check each item in checklist
3. Provide specific feedback
4. Suggest improvements

## Examples

[Concrete examples here]
```

---

## Common Mistakes

### ❌ Avoid

- Vague descriptions: "Helps with code"
- Missing trigger conditions
- No examples
- Overly complex single skills
- Broken internal links

### ✅ Do

- Specific descriptions: "Validates API responses against schema"
- Clear trigger patterns
- Concrete examples
- One focused purpose per skill
- Test all links

---

## Resources

- [Hermes Agent Docs](https://hermes-agent.nousresearch.com/docs)
- [Skill Examples](../../)
- [YAML Validator](https://www.yamllint.com/)

---

**Questions?** Open an issue or discussion in the repository.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall