skill-writing-best-practices
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.
- Installs
- 173
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/sergiodxa/agent-skills --skill skill-writing-best-practices- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads skill-writing-best-practices automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
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
Style (MEDIUM)
writing-style - @rules/writing-style.md
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.
Philosophy
Good skills are:
- Concrete - Every rule has code examples
- Reasoned - Explains why, not just what
- Scannable - Easy to find relevant rules quickly
- Honest - Shows when NOT to use a pattern
- Natural - Written like documentation, not AI output
FAQ
What does the skill-writing-best-practices skill do?
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.
How do I install skill-writing-best-practices?
Run npx skills add https://github.com/sergiodxa/agent-skills --skill skill-writing-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/skill-writing-best-practices/ (personal) or .claude/skills/skill-writing-best-practices/ (project).
Which AI agents can use skill-writing-best-practices?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is skill-writing-best-practices safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains skill-writing-best-practices?
It is published by sergiodxa in sergiodxa/agent-skills. It has 173 recorded installs.
More from sergiodxa/agent-skills
frontend-testing-best-practices
sergiodxa/agent-skills
Testing best practices for the frontend. Emphasizes E2E tests over unit tests, minimal mocking, and testing behavior over implementation details. Use when writing tests or reviewing test code.
owasp-security-check
sergiodxa/agent-skills
Security audit guidelines for web applications and REST APIs based on OWASP Top 10 and web security best practices. Use when checking code for vulnerabilities, reviewing auth/authz, auditing APIs, or before production deployment.
frontend-react-best-practices
sergiodxa/agent-skills
React performance optimization guidelines. Use when writing, reviewing, or refactoring React components to ensure optimal rendering and bundle patterns. Triggers on tasks involving React components, hooks, memoization, or bundle optimization.
frontend-accessibility-best-practices
sergiodxa/agent-skills
Accessibility (a11y) best practices for React components. Use when creating UI components, forms, interactive elements, or reviewing code for accessibility compliance.
frontend-tailwind-best-practices
sergiodxa/agent-skills
Tailwind CSS patterns and conventions for frontend apps. Use when writing component styles, layouts, or working with CSS classes.
frontend-react-router-best-practices
sergiodxa/agent-skills
Open the skill to read its SKILL.md instructions.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.