playbooks

home / skills / gtmagents / gtm-agents / api-style-guide

api-style-guide skill

/plugins/technical-writing/skills/api-style-guide

This skill helps ensure API documentation meets a consistent style and structure across references, tutorials, and SDK samples.

npx playbooks add skill gtmagents/gtm-agents --skill api-style-guide

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.3 KB
---
name: api-style-guide
description: Style and formatting rules for API/SDK documentation, samples, and tutorials.
---

# API Style Guide Skill

## When to Use
- Authoring or updating API references, tutorials, and SDK docs.
- Reviewing contributions from engineers, DevRel, or partners.
- Auditing docs for consistency before releases.

## Framework
1. **Language & Tone** – audience-specific tone, terminology list, and banned phrases.
2. **Structure** – endpoint/order conventions, table layouts, code block formatting, error doc patterns.
3. **Code Samples** – naming standards, authentication handling, pagination patterns, inline comments.
4. **Metadata & Tags** – version labels, availability notes, beta flags, locale indicators.
5. **Accessibility & Localization** – heading hierarchy, alt-text, snippet annotations, translation guidance.

## Templates
- Reference entry template (description, parameters, responses, examples, notes).
- Tutorial skeleton with prerequisites, steps, troubleshooting, next steps.
- Code sample checklist ensuring env vars, comments, and error handling are included.

## Tips
- Keep examples runnable; provide curl equivalents even when primary sample is in another language.
- Link to glossary for shared terminology across teams.
- Pair with `update-api-reference` command to enforce consistent output.

---

Overview

This skill captures style and formatting rules for API and SDK documentation, samples, and tutorials. It standardizes tone, structure, code samples, metadata, and accessibility to produce consistent, production-ready docs. Use it to audit, author, or review API materials across teams and releases.

How this skill works

The skill defines a framework covering language and tone, structural conventions for reference entries and tutorials, and a checklist for code samples. It inspects docs for required sections, naming patterns, auth handling, pagination examples, metadata tags, and accessibility cues like alt text and heading hierarchy. Outputs flag deviations and provide templates and remediation steps to restore consistency.

When to use it

  • Authoring or updating API references, SDK docs, or tutorials
  • Reviewing contributions from engineers, DevRel, or external partners
  • Auditing documentation before a release or public launch
  • Creating code samples that must be runnable and secure
  • Standardizing metadata, beta flags, and localization readiness

Best practices

  • Adopt audience-specific tone and a short banned-phrases list
  • Follow a reference template: description, parameters, responses, examples, notes
  • Provide runnable samples with curl equivalents and clear env var handling
  • Include version labels, availability notes, and beta flags in metadata
  • Ensure accessibility: proper headings, alt text, and snippet annotations

Example use cases

  • Convert an internal API spec into a public reference with consistent endpoint order
  • Review a partner-provided tutorial and enforce naming and auth patterns
  • Generate SDK samples that handle errors and pagination uniformly
  • Audit docs to add localization markers and translation guidance
  • Prepare a release checklist to ensure metadata and accessibility requirements are met

FAQ

What sections must every reference entry include?

Each entry should include a short description, parameter list, response examples, error codes, at least one runnable example, and notes about availability or versioning.

Should code samples always show authentication?

Yes—samples must demonstrate secure auth handling, reference env vars rather than hard-coded secrets, and include a curl equivalent.