writing-best-practices_skill

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