К основному содержанию
скилл CX Codex

reference-docs — скилл для Claude Code: справочные страницы API

Скилл reference-docs помогает писать справочные страницы для API и функций: таблицы параметров, возвращаемые значения, ошибки, запускаемые примеры.

Apache-2.0 121 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill reference-docs -a claude-code
Открыть на GitHub

Что делает reference-docs

Скилл задаёт шаблон справочной страницы: заголовок, короткое описание, таблица параметров с типами и признаком обязательности, блок возвращаемых значений, рабочий пример и ссылки на связанные символы. Дальше идут правила заполнения этих блоков. Для объекта описывается отдельная таблица свойств, для строкового поля перечисляются допустимые значения.

Главный принцип — только описание. Никаких объяснений «зачем» и пошаговых инструкций: для этого есть другие типы документации, и скилл отсылает к docs-style. Проза заменяется таблицами, у похожих страниц одинаковый порядок разделов, в примерах стоят реалистичные значения вместо foo и [email protected].

Вручную его не вызвать: во фронтматтере стоит user-invocable: false, так что скилл подхватывается, когда агент берётся за справочную страницу. Рассчитан он на пару с docs-style: внутри есть ссылка на ../docs-style/references/diataxis-compass.md, и без установленного docs-style она не откроется.

Какие задачи решает

  • собрать таблицу параметров с типами и значениями по умолчанию
  • описать возвращаемое значение функции и её ошибки
  • привести примеры к одному формату на всех страницах
  • заменить прозу таблицами, по которым быстро ищут
  • документировать HTTP-эндпоинт с path-параметрами

Примеры запросов агенту

  • Напиши справочную страницу для функции getUser: таблица параметров, возвращаемое значение, запускаемый пример.
  • Оформи API-референс для GET /api/v1/users/{userId} в том же порядке разделов, что и остальные страницы.
  • Перепиши этот раздел как reference: убери объяснения, оставь таблицы и один полный пример.

Как установить reference-docs

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill reference-docs -a claude-code

2Вручную: положить файлы

~/.claude/skills/reference-docs/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/reference-docs/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о reference-docs

Как установить reference-docs в Claude Code?

Выполните npx skills add existential-birds/beagle --skill reference-docs -a claude-code. Файл скилла появится по пути ~/.claude/skills/reference-docs/SKILL.md.

Что делает reference-docs?

Задаёт структуру и правила для справочных страниц: таблицы параметров и возвращаемых значений, перечень ошибок, примеры кода. Агент опирается на них, когда пишет API-референс или описание функции.

Нужен ли рядом скилл docs-style?

Да, они работают в паре: reference-docs ссылается на ../docs-style/references/diataxis-compass.md и берёт оттуда общие принципы письма. Без установленного docs-style эта ссылка не откроется.

Исходный текст

SKILL.md · Apache-2.0
---
name: reference-docs
description: Reference documentation patterns for API and symbol documentation. Use when writing reference docs, API docs, parameter tables, or technical specifications. Triggers on reference docs, API reference, function reference, parameters table, symbol documentation.
user-invocable: false
---

# Reference Documentation Patterns

Reference documentation is information-oriented - helping experienced users find precise technical details quickly. This skill provides patterns for writing clear, scannable reference pages.

**Dependency:** Always use this skill in conjunction with `docs-style` for core writing principles. To confirm reference is the right type — rather than a tutorial, how-to, or explanation — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

## Purpose and Audience

- **Who:** Experienced users seeking specific information
- **Goal:** Quick lookup of technical details
- **Mode:** Not for learning, for looking up
- **Expectation:** Brevity, consistency, completeness

## Document Structure Template

Use this template when creating reference documentation:

```markdown
---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
---

# [Name]

Brief description (1-2 sentences). State what it is and its primary purpose.

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `param1` | `string` | Yes | What this parameter controls |
| `param2` | `number` | No | Optional behavior modification. Default: `10` |

## Returns

| Type | Description |
|------|-------------|
| `ReturnType` | What the function returns and when |

## Example

```language
import { symbolName } from 'package';

// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});

console.log(result);
// Expected output: { ... }
```

## Related

- [RelatedSymbol](/reference/related-symbol) - Brief description
- [AnotherSymbol](/reference/another-symbol) - Brief description
```

## Writing Principles

### Describe, and Only Describe

Reference is austere, neutral, and authoritative — a map the reader can trust without independent verification. Its one job is to describe the machinery: commands, options, parameters, return values, limits, warnings. It does not instruct (that's How-To), teach (Tutorial), or argue (Explanation). When you feel the urge to explain *why* or walk the reader through a task, link out instead of inlining it; a digression interrupts and obscures the facts the reader came to consult.

### Structure Mirrors the Product

> "The structure of the documentation should mirror the structure of the product."

Organise reference so a reader can navigate the code and the docs in parallel — one reference entry per module, class, endpoint, or command, in the product's own order. Don't impose a narrative or thematic structure the product doesn't have; consistency of placement is what makes reference fast to consult.

### Brevity Over Explanation

- State facts, not rationale
- Avoid "why" - save that for Explanation docs
- Cut unnecessary words

**Do:**
```markdown
Returns the user's display name.
```

**Avoid:**
```markdown
This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.
```

### Scannable Tables, Not Prose

**Do:**
```markdown
| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |
```

**Avoid:**
```markdown
The first parameter is `userId`, which should be a string containing
the unique user identifier. The second parameter is `options`, which
is an Options object containing the configuration.
```

### Consistent Format Across Entries

All reference pages for similar items should follow identical structure:

- Same heading order
- Same table columns
- Same code example format
- Same related links section

### Every Example Must Be Runnable

- Include all imports
- Show complete, working code
- Use realistic values (not "foo", "bar", "test123")
- Include expected output when helpful

## Code Example Patterns

### Show Common Use Case First

```markdown
## Example

### Basic Usage

```typescript
const user = await getUser('user-123');
console.log(user.name);
```

### With Options

```typescript
const user = await getUser('user-123', {
  includeMetadata: true,
  fields: ['name', 'email', 'role']
});
```
```

### Include Setup and Context

```markdown
```typescript
import { Client } from '@example/sdk';

// Initialize client (required once per application)
const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function
const result = await client.users.list();
```
```

### Use Realistic Values

**Do:** `userId: 'usr_a1b2c3d4'`
**Avoid:** `userId: 'foo'`

**Do:** `email: '[email protected]'`
**Avoid:** `email: '[email protected]'`

## Parameter Documentation Patterns

### Required vs Optional

Clearly indicate which parameters are required:

```markdown
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your API key |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retries` | `number` | No | `3` | Number of retry attempts |
```

### Complex Types

For object parameters, document the shape:

```markdown
## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `options` | `UserOptions` | No | Configuration options |

### UserOptions

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `includeDeleted` | `boolean` | No | Include soft-deleted users |
| `fields` | `string[]` | No | Fields to return |
| `limit` | `number` | No | Maximum results (default: 100) |
```

### Enum Values

Document allowed values clearly:

```markdown
| Name | Type | Values | Description |
|------|------|--------|-------------|
| `status` | `string` | `active`, `pending`, `suspended` | User account status |
```

## Return Value Documentation

### Simple Returns

```markdown
## Returns

`User` - The requested user object, or `null` if not found.
```

### Complex Returns

```markdown
## Returns

| Property | Type | Description |
|----------|------|-------------|
| `data` | `User[]` | Array of user objects |
| `pagination` | `Pagination` | Pagination metadata |
| `total` | `number` | Total matching records |
```

### Error Conditions

```markdown
## Errors

| Error | Condition |
|-------|-----------|
| `NotFoundError` | User does not exist |
| `UnauthorizedError` | Invalid or expired API key |
| `RateLimitError` | Too many requests |
```

## API Reference Specifics

### HTTP Endpoints

```markdown
## Endpoint

```http
GET /api/v1/users/{userId}
```

## Path Parameters

| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | The user's unique identifier |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `fields` | `string` | No | Comma-separated list of fields |

## Headers

| Name | Required | Description |
|------|----------|-------------|
| `Authorization` | Yes | Bearer token |
| `X-Request-ID` | No | Request tracking ID |

## Response

```json
{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",
  "email": "[email protected]"
}
```
```

## Component/Props Reference

For UI components:

```markdown
## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary'` | `'primary'` | Visual style |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
| `disabled` | `boolean` | `false` | Disable interactions |
| `onClick` | `() => void` | - | Click handler |

## Slots

| Name | Description |
|------|-------------|
| `default` | Button content |
| `icon` | Icon to display before text |
```

## Related Links Section

Always include links to related content:

```markdown
## Related

- [createUser](/reference/create-user) - Create a new user
- [updateUser](/reference/update-user) - Modify user properties
- [deleteUser](/reference/delete-user) - Remove a user
- [User Authentication Guide](/guides/authentication) - How authentication works
```

## Gates (completion order)

Use this **sequenced** workflow before treating a reference page as complete. Finish step *n* before *n+1*; each step has a **Pass** you can check on the written page alone (no “I verified internally”).

1. **Structure** — Sections match your project template (typically Parameters, Returns, Example, Related; HTTP docs add Endpoint, Path/Query, Headers, Response). **Pass:** every required section exists, or a one-line omission note appears under **Related** (e.g. “No query parameters”).
2. **Tables** — Parameters/returns/errors use tables with consistent columns per **Consistent Format Across Entries** and **Required vs Optional**. **Pass:** no blank Description cells; no `TBD` / `???` for shipped APIs.
3. **Runnable example** — At least one example meets **Every Example Must Be Runnable** and **Use Realistic Values**. **Pass:** imports included; user-visible strings are realistic (not generic `foo`/`bar` unless the API is illustrative-only).
4. **Related** — **Pass:** `## Related` contains ≥1 Markdown link to another reference or guide, or one explicit sentence that there are no related symbols.

## Checklist for Reference Pages

After the **Gates (completion order)** above, confirm:

- [ ] Title matches the symbol/API name exactly
- [ ] Description is one clear sentence
- [ ] All parameters documented with types
- [ ] Required vs optional clearly marked
- [ ] Default values specified for optional parameters
- [ ] Return type and structure documented
- [ ] At least one complete, runnable example
- [ ] Example uses realistic values
- [ ] Related pages linked
- [ ] Format matches other reference pages in the docs

## When to Use Reference vs Other Doc Types

| User's mindset | Doc type | Example |
|---------------|----------|---------|
| "I want to learn" | Tutorial | "Build your first integration" |
| "I want to do X" | How-To | "How to configure SSO" |
| "I want to understand" | Explanation | "How our caching works" |
| "I need to look up Y" | **Reference** | "API endpoint reference" |

Reference and Explanation are the two cognition-oriented types and are easily confused: Reference *states* neutral facts to consult while working; Explanation *discusses* reasoning to read while reflecting. For the full compass procedure and distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

## Related Skills

- **[docs-style](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[tutorial-docs](../tutorial-docs/SKILL.md)**: Tutorial patterns for learning-oriented content
- **[howto-docs](../howto-docs/SKILL.md)**: How-To guide patterns for task-oriented content
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns

© existential-birds · Apache-2.0 · existential-birds/beagle

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
docs-writer tech-leads-club Скилл docs-writer для Claude Code пишет, редактирует и проверяет документацию в проекте. Работает с README, Markdown-файлами и страницами docs/. CX Codex +1 ★ 7 191звёзд репо google-dev-docs surendranb Скилл google-dev-docs для Claude Code задаёт стиль Google для техдокументации: заголовки-действия, обращение на «вы», настоящее время, активный залог. Применяется при написании README, туториалов и справок по API. CX Codex +1 ★ 57звёзд репо code-documentation-docs-architect Seth Hobson Субагент code-documentation-docs-architect для Claude Code, Codex и Cursor, который анализирует кодовую базу и генерирует развёрнутую техническую документацию. Строит структуру от Executive Summary до схем безопасности и приложений. CX Codex ★ 42 780звёзд репо tech-docs-writer jarrodwatts Субагент tech-docs-writer исследует кодовую базу, пишет и обновляет README, архитектурные гайды и спецификации API с обязательной проверкой примеров кода. CX Codex ★ 1 064звёзд репо backend-to-frontend-handoff-docs davila7 Скилл backend-to-frontend-handoff-docs собирает API-хендофф-документ для фронтенд-разработчиков: эндпоинты, DTO, валидация и граничные случаи в одном markdown-файле. CX Codex +1 164установок absolute-docs dhruvjainin Скилл absolute-docs для Claude Code структурирует техническую документацию по методологии Diátaxis. Помогает писать руководства, справочники, README и проводить аудит существующих страниц. CX Codex +1 171установок

Из того же набора68

Весь набор →
app-intents-code-review Скилл app-intents-code-review проводит ревью кода Swift с фреймворком App Intents, проверяя таймауты, локализацию фраз и совместимость версий iOS. CX Codex +1 124установок review-feedback-schema Скилл review-feedback-schema для Claude Code задаёт CSV-схему результатов код-ревью и помогает оценивать качество проверок. Ведёт журнал решений по найденным проблемам. CX Codex +1 124установок combine-code-review Скилл combine-code-review проверяет код на Combine на ошибки в подписках, операторах, управлении памятью и обработке ошибок. Пригодится перед ревью Swift-кода с Combine. CX Codex +1 123установок receive-feedback Скилл receive-feedback разбирает замечания из код-ревью по фактам, а не из вежливости: каждый пункт проверяется по коду, получает вердикт с доказательством и только потом правится. CX Codex +1 123установок widgetkit-code-review Скилл widgetkit-code-review проверяет код виджетов на WidgetKit по чек-листу: таймлайн, вёрстка, настраиваемые интенты, память. Пригодится перед релизом виджета и после переезда на iOS 17. CX Codex +1 121установок pydantic-ai-model-integration Скилл pydantic-ai-model-integration помогает настроить провайдеров LLM, цепочки fallback, стриминг и лимиты токенов в библиотеке PydanticAI. CX Codex +1 120установок review-ai-writing Скилл review-ai-writing находит следы текстов нейросетей в документации, комментариях к коду, текстах коммитов и описаниях пулреквестов. Пригодится при проверке репозитория на канцелярский слог и роботизированные фразы. CX Codex +1 119установок wish-ssh-code-review Скилл wish-ssh-code-review проверяет код SSH-серверов на базе Go-библиотеки Charmbracelet Wish: порядок middleware, работу с PTY, ключи хоста и корректное завершение работы. CX Codex +1 119установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой