Markdown writer
Skill alextiannus/ClawTheater-skills-project/skills/markdown-writer
Generate well-structured technical documentation in Markdown. Use when a user asks to write docs, create a README, document an API, write a how-to guide, generate technical documentation, create a changelog, write a project wiki, or produce any structured Markdown content. Follows documentation best practices for clarity and completeness.From its SKILL.md
npx -y skills add alextiannus/ClawTheater-skills-project --skill markdown-writerAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
6.8 KB, as published. Nobody here has run it
Markdown Writer
Overview
Generate well-structured technical documentation in Markdown format. Covers READMEs, API docs, how-to guides, changelogs, and any structured technical content using documentation best practices.
Instructions
When a user asks you to write documentation or Markdown content, follow these steps:
Step 1: Determine the document type
| Type | Purpose | Audience |
|---|---|---|
| README | Project introduction, setup, usage | New users and contributors |
| API docs | Endpoint reference with parameters and responses | Developers integrating the API |
| How-to guide | Step-by-step walkthrough for a specific task | Users solving a problem |
| Tutorial | Learning-oriented, progressive complexity | Beginners |
| Reference | Complete technical specification | Experienced users |
| Changelog | Version history with changes | All users |
| ADR | Architecture decision record | Team members |
Step 2: Gather information
Before writing, collect:
- Read the codebase to understand what the project does
- Check existing docs for tone and style
- Identify the target audience (beginner, intermediate, expert)
- Note any prerequisites or dependencies
- Find code examples that demonstrate real usage
Step 3: Write using these templates
README template:
# Project Name
One-line description of what this project does.
## Installation
\`\`\`bash
npm install project-name
\`\`\`
## Quick Start
\`\`\`javascript
const lib = require('project-name');
lib.doSomething();
\`\`\`
## Usage
### Feature One
Explain the feature with a code example.
### Feature Two
Explain the feature with a code example.
## API Reference
### `functionName(param1, param2)`
- `param1` (string): Description
- `param2` (number, optional): Description. Default: `10`
- Returns: `Promise<Result>`
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | number | `3000` | Server port |
| `debug` | boolean | `false` | Enable debug logging |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT
API endpoint documentation:
### Create a User
\`\`\`
POST /api/users
\`\`\`
**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Full name |
| `email` | string | Yes | Email address |
| `role` | string | No | Default: `"user"` |
**Example request:**
\`\`\`bash
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Jane Doe", "email": "[email protected]"}'
\`\`\`
**Response (201 Created):**
\`\`\`json
{
"id": 42,
"name": "Jane Doe",
"email": "[email protected]",
"role": "user",
"created_at": "2024-03-15T10:30:00Z"
}
\`\`\`
**Error responses:**
| Status | Description |
|--------|-------------|
| `400` | Invalid request body |
| `409` | Email already exists |
How-to guide template:
# How to Deploy to Production
## Prerequisites
- Docker 20+ installed
- AWS CLI configured with credentials
## Steps
### 1. Build the image
\`\`\`bash
docker build -t myapp:latest .
\`\`\`
### 2. Push to registry
\`\`\`bash
docker tag myapp:latest ecr.example.com/myapp:latest
docker push ecr.example.com/myapp:latest
\`\`\`
### 3. Deploy
\`\`\`bash
aws ecs update-service --cluster prod --service myapp --force-new-deployment
\`\`\`
## Troubleshooting
**Build fails with "out of memory":**
Increase Docker memory limit to at least 4GB in Docker Desktop settings.
**Deployment times out:**
Check that the health check endpoint returns 200 within 30 seconds.
Step 4: Review and polish
Checklist before delivering:
- Title clearly states what the document covers
- Code examples are copy-paste ready (no placeholders that would break)
- Tables are used for structured data instead of long prose
- Headings follow a logical hierarchy (H1 > H2 > H3)
- Links are included for external references
- Prerequisites are listed before steps that require them
Examples
Example 1: Generate a README for a CLI tool
User request: "Write a README for my Node.js CLI tool that converts images"
Output structure:
# img-convert
Fast image format conversion from the command line.
## Installation
npm install -g img-convert
## Usage
img-convert input.png output.webp
img-convert --quality 80 --resize 800x600 photo.jpg photo.webp
img-convert --batch src/*.png --format webp --outdir dist/
## Options (table with flag, type, default, description)
## Supported Formats (table)
## Examples (3-4 real usage scenarios)
## Contributing
## License
Example 2: Document an existing API from code
User request: "Generate API docs from my Express routes"
Process:
- Read all route files to identify endpoints
- Extract HTTP method, path, middleware, request/response types
- Generate one section per endpoint with method, path, parameters, body, response, and example
Output structure:
# API Reference
Base URL: `https://api.example.com/v1`
Authentication: Bearer token in Authorization header
## Users
### GET /users - List all users
### GET /users/:id - Get a user
### POST /users - Create a user
### PUT /users/:id - Update a user
### DELETE /users/:id - Delete a user
## Orders
### GET /orders - List orders
### POST /orders - Create an order
Each endpoint includes parameters table, example request, and example response.
Guidelines
- Write for the reader, not yourself. Assume the reader has never seen this project.
- Start with the most common use case, not edge cases.
- Every code example must be complete enough to run. Do not leave out imports or setup.
- Use tables for anything with more than 3 key-value pairs. Tables are faster to scan than paragraphs.
- Keep paragraphs short (3-4 sentences max). Use bullet points for lists of items.
- Link to related documents rather than duplicating content.
- Use consistent formatting: backticks for code, bold for UI elements, italics sparingly.
- For API docs, always include at least one complete request/response example per endpoint.
- Version documentation alongside code. If the API changes, the docs must change.
- Do not document obvious things. "The
namefield is the name" adds no value.