Add CLAUDE.md and generate-openapi-from-pr Claude skill

[VedranZoricic]

Why?

Engineers making API changes in the intercom monolith have to manually translate their Ruby code into OpenAPI YAML spec updates in this repo. Adding Claude configuration files makes it easier for people to create doc changes using Claude Code.

How?

Add a CLAUDE.md describing the repo structure and conventions, plus a Claude skill that takes an intercom monolith PR as input, analyzes the diff (controllers, presenters, version changes, routes), and generates the corresponding OpenAPI YAML updates.

Implementation Plan

Plan: Create "Generate OpenAPI from PR" Claude Skill

Context

Engineers making API changes in the intercom monolith must manually translate their Ruby code (controllers, presenters, version changes) into OpenAPI YAML spec updates in this repo (Intercom-OpenAPI). This is the most tedious part of the "Ship to Public API" workflow documented in the Engineering Wiki.

This skill automates that translation: given an intercom monolith PR, it analyzes the diff, identifies API changes, and generates the corresponding OpenAPI spec updates in descriptions/0/api.intercom.io.yaml (Unstable).

Scope: This repo only (Intercom-OpenAPI). Developer-docs PR remains a separate step.

---

Files to Create

1. .claude/skills/generate-openapi-from-pr/SKILL.md

Main skill entry point. Contains:

• Frontmatter: name, description, allowed-tools (Task, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion)
• Trigger conditions: When user provides an intercom monolith PR URL/number
• Step-by-step workflow:
  1. Parse the PR URL/number from user input
  2. Fetch PR details: gh pr view <number> --repo intercom/intercom
  3. Fetch PR diff: gh pr diff <number> --repo intercom/intercom
  4. Identify API changes in the diff (see analysis rules below)
  5. Ask user which versions to target (default: Unstable only)
  6. Read the target spec file(s)
  7. Generate and apply OpenAPI YAML changes
  8. Run fern check to validate
  9. Summarize what was added/changed

2. .claude/skills/generate-openapi-from-pr/ruby-to-openapi-mapping.md

Reference guide mapping Ruby patterns to OpenAPI YAML with concrete before/after YAML examples.

3. .claude/skills/generate-openapi-from-pr/openapi-patterns.md

Concrete YAML templates for all common endpoint and schema patterns, extracted from real examples in the current spec.

4. .claude/skills/generate-openapi-from-pr/version-propagation.md

Guide for when/how to propagate changes across API versions.

5. CLAUDE.md

Repo-level configuration documenting structure, CI/CD, editing conventions, and SDK generation safety rules.

_{Generated with Claude Code}