# Readme Md

> Guides README creation and improvement with audience-matched templates. Use when writing READMEs for open source, personal, internal, or config projects, or when the user mentions documentation, README, or project setup.

- **Type:** Skill
- **Install:** `agentstack add skill-costa-marcello-skillkit-readme-md`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [costa-marcello](https://agentstack.voostack.com/s/costa-marcello)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [costa-marcello](https://github.com/costa-marcello)
- **Source:** https://github.com/costa-marcello/skillkit/tree/main/skills/readme-md

## Install

```sh
agentstack add skill-costa-marcello-skillkit-readme-md
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Crafting Effective READMEs

## Overview

Identify the audience first. Match sections, depth, and tone to what that audience needs.

## User Input

**User request:** $ARGUMENTS

If `$ARGUMENTS` is non-empty, extract the task type (creating, adding, updating, reviewing) and project type (OSS, personal, internal, config) from it. Skip Step 1 and proceed to Step 2. Only ask clarifying questions if the task or project type is entirely unclear.

If `$ARGUMENTS` is empty, begin at Step 1.

## Quick Workflow

Copy this checklist:

```
README Progress:
- [ ] Task identified: Creating / Adding / Updating / Reviewing
- [ ] Audience identified: _____
- [ ] Project type: OSS / Personal / Internal / Config
- [ ] Template selected from templates/
- [ ] Draft complete
- [ ] Verified: draft matches actual project state (package.json, directory structure, commands)
- [ ] Asked: "Anything else to highlight or include that I might have missed?"
```

## 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 | `assets/templates/oss.md` |
| **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `assets/templates/personal.md` |
| **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `assets/templates/internal.md` |
| **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `assets/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)

## Examples

**Task:** Creating README for OSS CLI tool

**Before (typical first draft):**
```markdown
# mytool
A tool for doing stuff with files.

## Installation
npm install mytool

## Usage
mytool [options]
```

**After (audience-focused):**
```markdown
# mytool
Convert CSV files to JSON with one command. Handles messy data, encoding issues, and files up to 2GB.

## Quick Start
```bash
npm install -g mytool
mytool input.csv > output.json
```

## Common Use Cases
```bash
# Skip header row
mytool --skip-header data.csv

# Handle non-UTF8 encoding
mytool --encoding latin1 legacy.csv
```
```

**Why better:** Shows the problem it solves, demonstrates real scenarios, gives copy-paste commands.

**Task:** Updating README after adding new feature

**Before (buried in wall of text):**
```markdown
## Features
This tool does X, Y, Z. It also now supports authentication via OAuth which can be configured using environment variables or a config file.
```

**After (scannable, actionable):**
```markdown
## Features
- **X** - Does this
- **Y** - Does that
- **Z** - Does the other thing
- **OAuth auth** (new in v2.0) - See [Authentication](#authentication)

## Authentication
Set `MYTOOL_OAUTH_TOKEN` or add to `~/.mytoolrc`:
```yaml
auth:
  provider: oauth
  token: your-token
```
```

**Why better:** New feature is discoverable, has its own section, shows exactly how to use it.

**Task:** Config folder README (for future-you)

**Before (no README or unhelpful):**
```markdown
# Config
My config files.
```

**After (answers future-you's questions):**
```markdown
# Neovim Config

## What's Here
- `init.lua` - Entry point, loads everything else
- `lua/plugins/` - Plugin configs (lazy.nvim)
- `lua/keymaps.lua` - All custom keybindings

## Key Choices
- **Why lazy.nvim?** Fastest loader, good defaults
- **Why no LSP here?** Using Mason, see `lua/plugins/lsp.lua`

## Gotchas
- Run `:Lazy sync` after pulling changes
- `` is space (set in init.lua line 12)
```

**Why better:** Future-you at 2am will thank past-you for the "Gotchas" section.

**Task:** Creating README for internal team service

**Before (missing operational context):**
```markdown
# User Service
Handles users.

## Setup
Run `docker compose up`.
```

**After (onboarding-ready):**
```markdown
# User Service

Manages authentication, profiles, and role-based access for the platform.

**Team**: #platform-eng | **On-call**: PagerDuty rotation

## Dependencies
- **Upstream**: PostgreSQL, Redis, Auth0
- **Downstream**: Billing Service, Notification Service

## Local Setup

### Prerequisites
- Docker Desktop >= 4.x
- Access to 1Password `Platform Eng` vault for env vars

### Run

```bash
cp .env.example .env        # then fill from 1Password
docker compose up -d
curl http://localhost:3000/health   # expect {"status":"ok"}
```

### Tests

```bash
npm test                     # unit tests
npm run test:integration     # requires running Docker services
```

## Troubleshooting

### Auth0 callback fails locally
**Fix**: Set `AUTH0_BASE_URL=http://localhost:3000` in `.env`. The default points to staging.
```

**Why better:** New team members can run the service in under 5 minutes. Troubleshooting section prevents the most common support question.

**Task:** Reviewing an existing README for accuracy

**Before (stale, misleading):**
```markdown
# datakit
A Python library for CSV processing.

## Installation
pip install datakit

## Usage
```python
from datakit import process
process("input.csv")
```
```

**Review findings:**
1. Project now supports JSON and Parquet (added 6 months ago), not just CSV
2. `process()` was renamed to `transform()` in v2.0
3. Requires Python 3.10+, not mentioned anywhere
4. No mention of the new CLI interface added in v1.8

**After (accurate, current):**
```markdown
# datakit
Transform CSV, JSON, and Parquet files with a single API or CLI command.

## Installation
Requires Python 3.10+

```bash
pip install datakit
```

## Usage

### Python API
```python
from datakit import transform
transform("input.csv", output_format="json")
```

### CLI
```bash
datakit convert input.csv --to json
datakit convert data.parquet --to csv
```
```

**Why better:** Every section matches the actual project state. Stale docs erode trust faster than no docs.

## References

| File | Purpose |
|------|---------|
| `references/section-checklist.md` | Which sections to include by project type |
| `references/style-guide.md` | Common README mistakes and prose guidance |
| `references/art-of-readme.md` | Philosophy: cognitive funneling, brevity, key elements |
| `references/make-a-readme.md` | Section-by-section guidance for what to include |
| `references/standard-readme-spec.md` | Formal spec for standardised README format |
| `references/standard-readme-example-minimal.md` | Minimal compliant README example |
| `references/standard-readme-example-maximal.md` | Full-featured README example |
| `assets/templates/` | Ready-to-use templates: oss, personal, internal, xdg-config |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [costa-marcello](https://github.com/costa-marcello)
- **Source:** [costa-marcello/skillkit](https://github.com/costa-marcello/skillkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-costa-marcello-skillkit-readme-md
- Seller: https://agentstack.voostack.com/s/costa-marcello
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.