home / skills / lihaoze123 / my-claude-code / writing-best-practices

writing-best-practices skill

safe

This skill helps you create structured, scalable best-practices guides and agent-ready documentation, separating quick references from comprehensive AGENTS

npx playbooks add skill lihaoze123/my-claude-code --skill writing-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (13)

SKILL.md

2.9 KB

---
name: writing-best-practices
description: Use when creating structured best practices guides, organizing technical documentation, or establishing reference materials for teams or agents
license: MIT
metadata:
  author: chumeng
  version: "2.0.0"
  lastUpdated: "2026-01-24"
---

# Writing Best Practices

Create structured, maintainable best practices documentation that scales from quick reference to detailed guides.

## Core Principle

**Separate quick reference from comprehensive documentation.**

## When to Use

- Creating technical best practices guides
- Organizing reference documentation for teams or agents
- Building structured knowledge bases
- Documenting proven patterns and approaches

**Don't use for:**
- One-time documentation (use simple README)
- Project-specific notes (use CLAUDE.md)
- Narrative blog posts or tutorials

## Quick Reference

| Topic | Rule File |
|-------|-----------|
| Core structure and organization | [structure](rules/structure.md) |
| Frontmatter format | [frontmatter](rules/frontmatter.md) |
| Impact levels | [impact-levels](rules/impact-levels.md) |
| Validation and verification | [validation](rules/validation.md) |
| Writing individual rules | [writing-rules](rules/writing-rules.md) |
| Code examples and patterns | [code-examples](rules/code-examples.md) |
| Quick reference tables | [quick-reference](rules/quick-reference.md) |
| Maintenance and updates | [maintenance](rules/maintenance.md) |
| Common anti-patterns | [anti-patterns](rules/anti-patterns.md) |

## Essential Structure

```
best-practice-name/
├── SKILL.md          # Quick reference (human scan)
├── AGENTS.md         # Full content (agent read)
└── rules/            # Modular rule files
    ├── rule-1.md
    ├── rule-2.md
    └── ...
```

**SKILL.md** (2-3 pages):
- Overview and core principle
- When to use/not use
- Quick reference table
- Essential pattern code
- Red flags
- Link to full doc

**AGENTS.md** (complete compilation):
- All content in single document
- Generated or compiled from rules/
- Comprehensive with all details

**rules/** (modular sections):
- One file per focused topic
- Mix of concept + examples
- Easy to update independently

## Common Patterns

| Need | Pattern |
|------|---------|
| Quick lookup | Table with rule file links |
| Deep understanding | AGENTS.md with all details |
| Specific topic | Individual rule file |
| Code variations | Tables instead of multiple examples |

## Red Flags - STOP

| Anti-pattern | Fix |
|--------------|-----|
| "Put everything in one file" | Use modular structure |
| "No need for quick reference" | Humans scan, agents read |
| "Five language examples" | One excellent example is enough |
| "Narrative style rules" | Use problem/solution format |

## How to Use

Each rule file contains:
- Why the pattern matters
- ❌ Incorrect vs ✅ Correct examples
- Additional context and references

For the complete guide: `AGENTS.md`

Overview

This skill provides a repeatable framework for creating structured, maintainable best-practices documentation that scales from a concise quick reference to a comprehensive guide. It enforces separation between human-facing summaries and machine/agent-oriented full documentation so teams can find answers fast and maintain content easily. The goal is predictable, modular files that are easy to update and reuse.

How this skill works

The skill defines a three-part approach: a short human-scannable reference, a complete compiled document for deep reading or agent consumption, and a set of modular rule files for focused topics. Each rule file explains why a pattern matters, shows incorrect vs correct examples, and includes context and references. Authors can compile rule files into the full guide and keep the quick reference synchronized for fast lookup.

When to use it

Creating technical best-practices guides for teams or products
Organizing reference documentation that must be both human- and agent-consumable
Building a knowledge base of proven patterns and validation checks
Maintaining policies or style guides that evolve over time
Documenting reusable code examples, patterns, or impact levels

Best practices

Separate quick-reference content from comprehensive documentation to serve different reader needs
Structure content into modular rule files so individual topics can be updated independently
Use problem/solution format with ❌ incorrect and ✅ correct examples for clarity
Keep one strong example per pattern rather than many small variations to reduce maintenance
Include frontmatter or metadata for each file to enable automated compilation and filtering

Example use cases

Create a team-facing quick reference that lists core rules, red flags, and links to full topics
Compile all modular rule files into a single comprehensive document for agent consumption
Document validation, impact levels, and verification steps for operational procedures
Maintain code-pattern libraries with one authoritative example per pattern
Publish a short human summary for onboarding and a detailed guide for audits or automation

FAQ

How granular should each rule file be?

Make each file focused on a single concept or decision so it can be updated independently and linked from the quick reference.

What belongs in the quick reference vs the full doc?

Quick reference contains overview, red flags, essential patterns, and links. The full doc contains full explanations, examples, and references.

How do I avoid duplication across files?

Keep reusable guidance in a single rule file and reference it from the quick summary; use metadata and automated compilation to ensure consistency.