skill-writing-best-practices

Skill Writing Best Practices

Patterns for creating effective AI agent skills that capture coding conventions and best practices. Contains 6 rules covering structure, content, and writing style.

When to Apply

Reference these guidelines when:

• Creating a new skill from scratch
• Extracting patterns from an existing codebase
• Reviewing or improving existing skills
• Converting documentation into skill format

Rules Summary

Structure (HIGH)

skill-directory-structure - @rules/skill-directory-structure.md

Every skill has a SKILL.md and a rules/ directory.

skills/
└── topic-best-practices/
    ├── SKILL.md              # Main summary with all rules
    └── rules/
        ├── rule-name.md      # Detailed individual rules
        └── another-rule.md

skill-md-structure - @rules/skill-md-structure.md

SKILL.md has frontmatter, overview, and condensed rule summaries.

---
name: topic-best-practices
description: When to use this skill.
---

# Topic Best Practices

Brief intro. Contains N rules across M categories.

## When to Apply

- Situation 1
- Situation 2

## Rules Summary

### Category (IMPACT)

#### rule-name - @rules/rule-name.md

One sentence. Code example.

rule-file-structure - @rules/rule-file-structure.md

Each rule file has frontmatter, explanation, examples, and takeaways.

---
title: Rule Title
impact: HIGH
tags: [relevant, tags]
---

# Rule Title

What to do and why.

## Why

- Benefit 1
- Benefit 2

## Pattern

\`\`\`ruby
# Bad
bad_code

# Good
good_code
\`\`\`

## Rules

1. Takeaway 1
2. Takeaway 2

Content (HIGH)

concrete-examples - @rules/concrete-examples.md

Every rule needs code examples. Abstract advice is hard to apply.

# Bad: Too abstract
"Keep your code organized."

# Good: Concrete
"Place concerns in `app/models/model_name/` not `app/models/concerns/`."

\`\`\`ruby
# Shows exactly what to do
app/models/card/closeable.rb
\`\`\`

explain-why - @rules/explain-why.md