AgentSkillsCN

creating-documentation

创建并审查 README 文件及仓库文档，遵循清晰性、可访问性和可发现性的最佳实践。适用于用户要求创建 README、撰写项目文档、改进现有文档、添加 CONTRIBUTING 指南、审查文档的可访问性，或为新仓库编写文档时使用。

SKILL.md
--- frontmatter
name: creating-documentation
description: 'Create and review README files and repository documentation that follows best practices for clarity, accessibility, and discoverability. Use when a user asks to create a README, write project documentation, improve existing documentation, add a CONTRIBUTING guide, review documentation for accessibility, or document a new repository.'
license: MIT
allowed-tools: Bash

Creating Documentation

Overview

This skill provides capabilities for creating and reviewing README files and other repository documentation that follows established best practices for structure, accessibility, and user experience.

Good documentation is the front door to your project. It helps users understand what your project does, how to use it, and how to contribute. This skill ensures documentation is clear, accessible, and follows industry standards.

Capabilities

CapabilityActionDescription
Create READMEactions/create-readme.mdGenerate a comprehensive README for a repository
Create CONTRIBUTINGactions/create-contributing.mdGenerate contribution guidelines
Reviewactions/review-documentation.mdAnalyse existing documentation for quality and accessibility

Standards

This skill bundles the following standards in standards/:

StandardFileDescription
README Structurereadme-structure.mdEssential sections and organization for README files
Accessibilityaccessibility.mdAccessibility requirements for inclusive documentation
Writing Stylewriting-style.mdPlain language and readability guidelines
Markdownmarkdown.mdMarkdown formatting best practices
Checklistchecklist.mdConsolidated compliance and quality checklist

Principles

1. Audience First

Write for your audience. A README's primary purpose is to help visitors quickly understand your project and get started. Don't assume prior knowledge—provide context and links for unfamiliar concepts.

2. Progressive Disclosure

Present information in order of importance:

  • •Title & Description: What is this project? (immediate)
  • •Installation & Usage: How do I use it? (primary)
  • •Contributing & License: How can I help? (secondary)

3. Accessibility Matters

Documentation should be accessible to all users:

  • •Use proper heading hierarchy (don't skip levels)
  • •Provide alt text for all images
  • •Write descriptive link text (not "click here")
  • •Use plain language and short sentences

4. Keep It Current

Outdated documentation is worse than no documentation. Include only information that can be maintained. Use automation where possible.

Usage

  1. •Load this skill manifest
  2. •Identify the required capability (create or review)
  3. •Load the bundled standards from standards/
  4. •Execute the action following actions/<capability>.md

References