Agent-Skills.md

Agent Skills: Writing Best Practices

Use when creating structured best practices guides, organizing technical documentation, or establishing reference materials for teams or agents

UncategorizedID: lihaoze123/my-skills/writing-best-practices

Repository

lihaoze123/my-skills
lihaoze123
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lihaoze123/my-claude-code/tree/HEAD/skills/writing-best-practices

Skill Files

Browse the full folder contents for writing-best-practices.

Download Skill

Loading file tree…

skills/writing-best-practices/SKILL.md

Skill Metadata

Name
writing-best-practices
Description
Use when creating structured best practices guides, organizing technical documentation, or establishing reference materials for teams or agents

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 | | Frontmatter format | frontmatter | | Impact levels | impact-levels | | Validation and verification | validation | | Writing individual rules | writing-rules | | Code examples and patterns | code-examples | | Quick reference tables | quick-reference | | Maintenance and updates | maintenance | | Common anti-patterns | anti-patterns |

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