crafting-effective-readmes
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an O
- License 许可
- MIT
- 所属仓库
- ruake/AWARE
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- crafting-effective-readmes
- description
- READMEs answer questions your audience will have. Different audiences need different information - a contributor to an O
03 SKILL.md 正文
Crafting Effective READMEs
Overview
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
Process
Step 1: Identify the Task
Ask: "What README task are you working on?"
| Task | When |
|---|---|
| Creating | New project, no README yet |
| Adding | Need to document something new |
| Updating | Capabilities changed, content is stale |
| Reviewing | Checking if README is still accurate |
Step 2: Task-Specific Questions
Creating initial README:
- What type of project? (see Project Types below)
- What problem does this solve in one sentence?
- What's the quickest path to "it works"?
- Anything notable to highlight?
Adding a section:
- What needs documenting?
- Where should it go in the existing structure?
- Who needs this info most?
Updating existing content:
- What changed?
- Read current README, identify stale sections
- Propose specific edits
Reviewing/refreshing:
- Read current README
- Check against actual project state (package.json, main files, etc.)
- Flag outdated sections
- Update "Last reviewed" date if present
Step 3: Always Ask
After drafting, ask: "Anything else to highlight or include that I might have missed?"
Project Types
| Type | Audience | Key Sections | Template |
|---|---|---|---|
| Open Source | Contributors, users worldwide | Install, Usage, Contributing, License | templates/oss.md |
| Personal | Future you, portfolio viewers | What it does, Tech stack, Learnings | templates/personal.md |
| Internal | Teammates, new hires | Setup, Architecture, Runbooks | templates/internal.md |
| Config | Future you (confused) | What's here, Why, How to extend, Gotchas | templates/xdg-config.md |
Ask the user if unclear. Don't assume OSS defaults for everything.
Essential Sections (All Types)
Every README needs at minimum:
- Name - Self-explanatory title
- Description - What + why in 1-2 sentences
- Usage - How to use it (examples help)
References
section-checklist.md- Which sections to include by project typestyle-guide.md- Common README mistakes and prose guidanceusing-references.md- Guide to deeper reference materials
04 同仓库更多 Skills
xlsx
暂无简介
writing-plans
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste.
web-design-guidelines
Review files for compliance with Web Interface Guidelines.
web-component-design
Build reusable, maintainable UI components using modern frameworks with clean composition patterns and styling approache
web-artifacts-builder
暂无简介
vueuse-functions
This skill is a decision-and-implementation guide for VueUse composables in Vue.js / Nuxt projects. It maps requirements