Agent skill

markdown-documentation

Use when writing technical documentation, READMEs, or project documentation in markdown. Covers structure, conventions, and best practices.

View SKILL.md on GitHub Repository
Stars 129
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/TheBushidoCollective/han/tree/main/plugins/validation/markdown/skills/markdown-documentation

SKILL.md

Markdown Documentation

Best practices for writing effective technical documentation in markdown.

README Structure

Minimal README

markdown
# Project Name

Brief description of what this project does.

## Installation

Instructions to install.

## Usage

Basic usage example.

## License

MIT

Comprehensive README

markdown
# Project Name

![Build Status](badge-url)
![Version](badge-url)

One-paragraph description of the project.

## Features

- Feature one
- Feature two
- Feature three

## Installation

### Prerequisites

- Requirement 1
- Requirement 2

### Steps

Instructions...

## Usage

### Basic Example

Code example...

### Advanced Usage

More examples...

## Configuration

Configuration options...

## API Reference

API documentation...

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT License - see [LICENSE](LICENSE)

Document Organization

File Naming

docs/
├── README.md           # Entry point
├── CONTRIBUTING.md     # Contribution guidelines
├── CHANGELOG.md        # Version history
├── CODE_OF_CONDUCT.md  # Community guidelines
├── getting-started.md  # Onboarding guide
├── api/
│   ├── README.md       # API overview
│   └── endpoints.md    # Endpoint reference
└── guides/
    ├── installation.md
    └── configuration.md

Linking Between Documents

markdown
See the [installation guide](./guides/installation.md) for details.

For API reference, check [endpoints](./api/endpoints.md#authentication).

Writing Style

Be Concise

markdown
<!-- Bad -->
In order to install the application, you will need to run the following command.

<!-- Good -->
Install the application:

Use Active Voice

markdown
<!-- Bad -->
The configuration file should be created in the home directory.

<!-- Good -->
Create the configuration file in your home directory.

Address the Reader

markdown
<!-- Bad -->
Users can configure the timeout setting.

<!-- Good -->
You can configure the timeout setting.

Code Documentation

Inline Code vs Code Blocks

markdown
Use `npm install` to install dependencies.

For multiple commands, use a code block:

```bash
npm install
npm run build
npm start


### Command Examples

Show both command and output:

```bash
$ npm --version
10.2.0

Configuration Examples

Always show complete, valid examples:

Create config.json:

json
{
  "port": 3000,
  "debug": true,
  "database": {
    "host": "localhost",
    "name": "myapp"
  }
}

Admonitions and Callouts

GitHub-Style Alerts

markdown
> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Custom Callouts (Emoji-Based)

markdown
⚠️ **Warning**: This action cannot be undone.

💡 **Tip**: Use environment variables for sensitive data.

📝 **Note**: This feature requires version 2.0+.

API Documentation

Endpoint Documentation

Create User

Creates a new user account.

Request: POST /api/users

Headers:

Header Value Required
Content-Type application/json ✅
Authorization Bearer {token} ✅

Body:

json
{
  "name": "John Doe",
  "email": "john@example.com"
}

Response (201):

json
{
  "id": "abc123",
  "name": "John Doe",
  "email": "john@example.com"
}

Error (400):

json
{
  "error": "Invalid email format"
}

Function Documentation

parseConfig(path, options?)

Parses a configuration file.

Parameters:

Name Type Default Description
path string — Path to config file
options.strict boolean false Throw on unknown keys
options.env boolean true Expand environment variables

Returns: Config - Parsed configuration object

Throws:

  • FileNotFoundError - Config file doesn't exist
  • ParseError - Invalid JSON/YAML syntax

Example:

javascript
const config = parseConfig('./config.json', { strict: true });

Changelogs

Keep a Changelog Format

markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature X

### Changed
- Updated dependency Y

## [1.2.0] - 2024-01-15

### Added
- Feature A
- Feature B

### Fixed
- Bug in feature C

### Deprecated
- Old API endpoint

## [1.1.0] - 2024-01-01

### Added
- Initial release

Diagrams

Mermaid (GitHub Supported)

markdown
```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

ASCII Diagrams

markdown
```
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Client  │────▶│ Server  │────▶│Database │
└─────────┘     └─────────┘     └─────────┘
```

Best Practices

  1. Start with why: Explain what the project does and why it exists
  2. Show, don't tell: Provide working code examples
  3. Keep it current: Update docs when code changes
  4. Test examples: Ensure code samples actually work
  5. Use consistent terminology: Define terms and use them consistently
  6. Provide context: Link to prerequisites and related docs
  7. Consider your audience: Write for your users' skill level
  8. Include troubleshooting: Document common errors and solutions

Common Documentation Files

File Purpose
README.md Project overview and quick start
CONTRIBUTING.md How to contribute
CHANGELOG.md Version history
LICENSE Legal terms
CODE_OF_CONDUCT.md Community guidelines
SECURITY.md Security policy
SUPPORT.md How to get help

Didn't find tool you were looking for?

Be as detailed as possible for better results