Crafting Effective READMEsSAFE
A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
A skill for Claude Code that helps you write, update, and improve README files tailored to your specific project type and audience.
Purpose
Not all READMEs are the same. An open-source library needs different documentation than a personal project or an internal tool. This skill provides:
- Audience-aware guidance - Different readers need different information
- Project-type templates - Ready-to-use structures for OSS, personal, internal, and config projects
- Task-specific workflows - Whether creating, updating, adding to, or reviewing READMEs
- Quality checks - Style guidance and section checklists to avoid common mistakes
When to Use
Use this skill when you need to:
- Create a README for a new project
- Add a new section to an existing README
- Update stale documentation after changes
- Review and refresh README content
- Choose the right sections for your project type
Trigger phrases:
- "Write a README for this project"
- "Help me document this"
- "Create documentation for..."
- "Update the README"
- "Review my README"
- "What sections should my README have?"
How It Works
The skill follows a three-step process:
Step 1: Identify the Task
The skill determines what README task you are working on:
Step 2: Gather Context
Based on the task, the skill asks targeted questions:
- Creating: What type of project? What problem does it solve? What is the quickest path to "it works"?
- Adding: What needs documenting? Where should it go? Who needs this info most?
- Updating: What changed? Which sections are stale?
- Reviewing: Compares README against actual project state (package.json, main files, etc.)
###
28aecfe29fbfOBSERVED · 2026-10-27Host compatibility
What the documentation claims. We have not run a compatibility test.
| Host | Status | Notes |
|---|---|---|
| claude-code | mentioned |
What it tells the agent
The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.
--- name: crafting-effective-readmes description: Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type. --- # 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:** 1. What type of project? (see Project Types below) 2. What problem does this solve in one sentence? 3. What's the quickest path to "it works"? 4. Anything notable to highlight? **Adding a section:** 1. What needs documenting? 2. Where should it go in the existing structure? 3. Who needs this info most? **Updating existing content:** 1. What changed? 2. Read current README, identify stale sections 3. Propose specific edits **Reviewing/refreshing:** 1. Read current README 2. Check against actual project state (package.json, main files, etc.) 3. Flag outdated sections 4. 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: 1. **Name** - Self-explanatory title 2. **Description** - What + why in 1-2 sentences 3. **Usage** - How to use it (examples help) ## References - `section-checklist.md` - Which sections to include by project type - `style-guide.md` - Common README mistakes and prose guidance - `using-references.md` - Guide to deeper reference materials
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | NA |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (1)
CLAUDE.md
Gates applied: no_behavioural_pass.
28aecfe29fbffull audit observations/trust-audit/skill/softaworks__crafting-effective-readmes.json · Report an issue / request a re-scanAudit history
Every audit this skill has had.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-27 | 28aecfe29fbf | SAFE | B | 89 | first audit |
Questions
What does the crafting-effective-readmes — softaworks/agent-toolkit skill do?
A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.
Is crafting-effective-readmes — softaworks/agent-toolkit safe to install?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean skill reads B.
What can crafting-effective-readmes — softaworks/agent-toolkit access on my machine?
The audit observed no filesystem, network or shell use at all in its source.
Which assistants does crafting-effective-readmes — softaworks/agent-toolkit work with?
Its documentation mentions claude-code. That is what the text claims, not a compatibility test we ran.
How current is this page?
The grade is for one exact copy of the source (28aecfe29fbf), read on 2026-10-27. The repository is watched, and a new audit runs when it changes — this is the first audit.
Add this badge to your README
Shows this page's audit result and links back to it. It updates when the audit does.
[](https://modelsatlas.com/skills/softaworks/crafting-effective-readmes/)
Not your listing, or something out of date? Claim or update your listing.