readme-platform

What this skill does

# ReadMe Platform Skill

ReadMe.com platform integration for API documentation.

## Capabilities

- Sync OpenAPI specs to ReadMe
- Manage documentation versions
- Configure API reference settings
- Custom page management
- Changelog automation
- API metrics dashboard integration
- Recipe/tutorial creation
- Webhook and automation setup

## Usage

Invoke this skill when you need to:
- Deploy API documentation to ReadMe
- Sync OpenAPI specifications
- Manage versioned documentation
- Configure API Explorer settings
- Set up changelog automation

## Inputs

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | string | Yes | sync, version, page, changelog, metrics |
| apiKey | string | Yes | ReadMe API key |
| specPath | string | No | Path to OpenAPI spec |
| version | string | No | Documentation version |
| projectId | string | No | ReadMe project ID |

### Input Example

```json
{
  "action": "sync",
  "apiKey": "${README_API_KEY}",
  "specPath": "./api/openapi.yaml",
  "version": "1.0"
}
```

## ReadMe CLI Configuration

### .readme.yml

```yaml
# ReadMe CLI configuration
version: "1.0"
api:
  definition: ./api/openapi.yaml
  name: My API

changelogs:
  directory: ./changelogs

docs:
  directory: ./docs

categories:
  - slug: getting-started
    title: Getting Started
  - slug: api-reference
    title: API Reference
  - slug: guides
    title: Guides
```

## Sync OpenAPI Spec

### Using rdme CLI

```bash
# Login to ReadMe
rdme login

# Sync OpenAPI spec
rdme openapi ./api/openapi.yaml --version=1.0

# Sync with specific ID
rdme openapi ./api/openapi.yaml --id=abc123

# Validate before syncing
rdme openapi:validate ./api/openapi.yaml
```

### CI/CD Integration

```yaml
# .github/workflows/docs.yml
name: Sync API Docs

on:
  push:
    branches: [main]
    paths:
      - 'api/openapi.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync to ReadMe
        uses: readmeio/rdme@v8
        with:
          rdme: openapi ./api/openapi.yaml --key=${{ secrets.README_API_KEY }} --version=1.0
```

## Version Management

### Create Version

```bash
# Create new version
rdme versions:create 2.0 --fork=1.0

# Update version
rdme versions:update 2.0 --main=true

# List versions
rdme versions
```

### Version Configuration

```json
{
  "version": "2.0",
  "from": "1.0",
  "codename": "Major Release",
  "is_stable": true,
  "is_beta": false,
  "is_hidden": false,
  "is_deprecated": false
}
```

## Custom Pages

### Page Creation

```bash
# Create documentation page
rdme docs ./docs --version=1.0

# Create single page
rdme docs:single ./docs/getting-started.md --version=1.0
```

### Page Frontmatter

```markdown
---
title: Getting Started
slug: getting-started
category: 6123abc456def789
order: 1
hidden: false
---

# Getting Started

Welcome to our API documentation.

## Prerequisites

- API Key (get one from [dashboard](https://app.example.com))
- Node.js 18+ or Python 3.9+

## Installation

[block:code]
{
  "codes": [
    {
      "code": "npm install @example/sdk",
      "language": "bash",
      "name": "npm"
    },
    {
      "code": "pip install example-sdk",
      "language": "bash",
      "name": "pip"
    }
  ]
}
[/block]
```

## Changelog Management

### Changelog Entry

```markdown
---
title: Version 2.0 Release
type: added
hidden: false
createdAt: 2026-01-24
---

## New Features

### OAuth 2.0 Support
We now support OAuth 2.0 authentication in addition to API keys.

### Batch Operations
New batch endpoints for processing multiple items in a single request.

## Improvements

- Improved rate limiting with better error messages
- Enhanced webhook reliability

## Bug Fixes

- Fixed pagination issue in list endpoints
- Resolved timezone handling in date filters
```

### Sync Changelogs

```bash
# Sync all changelogs
rdme changelogs ./changelogs

# Sync single changelog
rdme changelogs:single ./changelogs/2.0-release.md
```

## API Explorer Configuration

### openapi.yaml Enhancements

```yaml
openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  x-readme:
    explorer-enabled: true
    proxy-enabled: true
    samples-enabled: true
    samples-languages:
      - curl
      - node
      - python
      - ruby

servers:
  - url: https://api.example.com/v1
    description: Production
    x-readme:
      explorer-default: true

paths:
  /users:
    get:
      x-readme:
        code-samples:
          - language: javascript
            name: Node.js
            code: |
              const response = await fetch('https://api.example.com/v1/users', {
                headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
              });
        explorer-enabled: true
```

## Metrics Dashboard

### API Metrics Query

```bash
# Get API metrics via API
curl -X GET 'https://dash.readme.com/api/v1/api-metrics' \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

### Metrics Response

```json
{
  "data": [
    {
      "endpoint": "GET /users",
      "requests": 15234,
      "success_rate": 99.2,
      "avg_latency": 145,
      "error_breakdown": {
        "400": 52,
        "401": 23,
        "500": 3
      }
    }
  ],
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  }
}
```

## Webhooks

### Webhook Configuration

```json
{
  "url": "https://api.example.com/readme-webhook",
  "events": [
    "doc.created",
    "doc.updated",
    "changelog.created",
    "api_spec.uploaded"
  ],
  "secret": "your-webhook-secret"
}
```

### Webhook Handler

```javascript
app.post('/readme-webhook', (req, res) => {
  const signature = req.headers['x-readme-signature'];

  // Verify signature
  if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, doc, project } = req.body;

  switch (event) {
    case 'doc.updated':
      console.log(`Doc updated: ${doc.title}`);
      break;
    case 'api_spec.uploaded':
      console.log('API spec updated');
      break;
  }

  res.status(200).send('OK');
});
```

## Custom Blocks

### Interactive Code Sample

```markdown
[block:code]
{
  "codes": [
    {
      "code": "const client = new Client({ apiKey: 'YOUR_KEY' });\nconst users = await client.users.list();",
      "language": "javascript",
      "name": "JavaScript"
    },
    {
      "code": "client = Client(api_key='YOUR_KEY')\nusers = client.users.list()",
      "language": "python",
      "name": "Python"
    }
  ]
}
[/block]
```

### Callout Blocks

```markdown
[block:callout]
{
  "type": "info",
  "title": "Rate Limiting",
  "body": "This endpoint is limited to 100 requests per minute."
}
[/block]

[block:callout]
{
  "type": "warning",
  "title": "Deprecation Notice",
  "body": "This endpoint will be removed in version 3.0."
}
[/block]
```

## Workflow

1. **Configure project** - Set up ReadMe project settings
2. **Sync OpenAPI** - Upload/update API specification
3. **Create pages** - Write custom documentation
4. **Configure explorer** - Set up API Explorer
5. **Add changelogs** - Document version changes
6. **Set up webhooks** - Enable automation

## Dependencies

```json
{
  "devDependencies": {
    "rdme": "^9.0.0"
  }
}
```

## CLI Commands

```bash
# Install CLI
npm install -g rdme

# Login
rdme login

# Sync OpenAPI spec
rdme openapi ./api/openapi.yaml --version=1.0

# Sync docs
rdme docs ./docs --version=1.0

# Create version
rdme versions:create 2.0 --fork=1.0

# Sync changelogs
rdme changelogs ./changelogs
```

## Best Practices Applied

- Version documentation with releases
- Use changelogs for release notes
- Configure code samples for all endpoints
- Enable API Explorer for testing
- Set up webhooks for automation
- Use custom blocks for rich content

## References

- ReadMe: https://readme.com/
- rdme CLI: https://github.com/readmeio/rdme
- ReadMe API: https://docs.readme.com/reference
- OpenAPI Extensions: https://docs.readme.com/doc