readme-platform

name	readme-platform
description	ReadMe.com platform integration for API documentation. Sync OpenAPI specs, manage versions, configure API reference settings, automate changelogs, and integrate with metrics dashboards.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-012
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:api-doc-generation","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]}

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

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

ReadMe CLI Configuration

.readme.yml

# 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

# 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

# .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

# 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

{
  "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

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

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

Page Frontmatter

---
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

---
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

# Sync all changelogs
rdme changelogs ./changelogs

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

API Explorer Configuration

openapi.yaml Enhancements

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

# 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

{
  "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

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

Webhook Handler

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

[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

[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

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

CLI Commands

# 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/docs/openapi-extensions

Target Processes

• api-doc-generation.js
• api-reference-docs.js
• docs-versioning.js