Guidelines for creating AI agent skills. Use when writing new skills, documenting coding patterns, or reviewing skill files. Triggers when creating or modifying files in the skills/ directory.
npxskills add sergiodxa/agent-skills--skill skill-writing-best-practicesLoading…
Patterns for creating effective AI agent skills that capture coding conventions and best practices. Contains 6 rules covering structure, content, and writing style.
Reference these guidelines when:
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 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.
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
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
\`\`\`
Don't just show what. Explain why it matters.
## Why
- **Testability**: Sync method can be tested without job infrastructure
- **Flexibility**: Callers choose sync or async based on context
- **Clarity**: The `_later` suffix makes async behavior explicit
Write naturally. Avoid AI-isms and excessive formatting.
# Bad
---
Here is an overview of the key points:
---
# Good
Group related rules by category. Each rule gets a one-sentence
description and a short code example.
Good skills are:
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).