skills.rest
samber
samberCOMMUNITY
Explore all skills by this author →
Website𝕏@samuelbertheGitHub

docs-code-sample-standards

Defines code sample policy and audits documentation sample corpora against it.

2|Updated Sep 6, 2026
Search Tags:#documentation#audit#policy#code samples#ci testing#developer docs#language parity
One-click install
npx skills add https://github.com/samber/developer-relations-skills --skill docs-code-sample-standards-samber
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-code-sample-standards
Source: https://github.com/samber/developer-relations-skills/tree/main/skills/docs-code-sample-standards
Command: npx skills add https://github.com/samber/developer-relations-skills --skill docs-code-sample-standards-samber

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Code samples in developer documentation silently rot: they stop compiling after API changes, leak credentials, break copy-paste, and drift out of sync across SDK languages, with nobody owning the fixes. This Skill defines the policy every published sample must meet and audits an existing corpus against it, returning a ranked fix queue. ## Core Features & Use Cases - Sample policy authoring: Produces a complete policy document covering the six decisions - coverage, anatomy, copy-paste and security safety, language parity, verification tiers, and ownership with freshness windows. - Corpus audit with ranked fix queue: Runs a mechanical census over every fenced code block (via scripts/sample-audit.py), applies ROT triage and rubric scoring on a stratified sample, then ranks findings by harm and a readers-times-severity-over-effort ratio. - Execution tiering and CI design: Classifies each sample as Run, Compile-only, or Illustrative, and designs the verification pipeline including single-sourcing from tested code, fixture teardown, and blocking gates. - Use Case: A docs team with 400 samples across five SDK languages runs the audit script, discovers leaked keys and untested quickstart samples, and receives a P0-first fix queue plus a parity matrix showing 71% cross-language coverage. ## Quick Start Ask the assistant to audit the code samples in your docs directory and produce a ranked fix queue with severity ratings.

Frequently Asked Questions about docs-code-sample-standards

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit code samples in my documentation?▼

Run scripts/sample-audit.py against your docs directory to mechanically census every fenced code block, flagging missing language identifiers, prompt characters, credential-shaped literals, and insecure switches. Then apply the audit checklist and rubric to a stratified sample for judgement-based checks.

What are execution tiers for documentation code samples?▼

Execution tiers classify each sample as Run (executed with asserted output in CI), Compile-only (type-checked but never executed), or Illustrative (labelled as not runnable). The tier decides what CI must enforce and what claim the sample makes to readers.

How do I test documentation code samples in CI?▼

Single-source samples from real compilable files using snippet tags and transclusion, then run hermetic tests per pull request and integration tests on a schedule against the published artefact. Fail the docs build on sample failures so red results cannot be ignored.

How do I keep code samples consistent across multiple SDK languages?▼

Build a parity matrix with scenarios as rows and languages as columns, tracking tested, present, missing, and stale cells. Parity means identical scenario, step order, and testing approach per language - not line-for-line transliteration, which fails idiomaticity.

Why do documentation samples pass CI but fail for readers?▼

This happens when CI installs from the working tree instead of the published artefact readers actually receive. Install the released package or deployed endpoint in the sample pipeline, and split hermetic per-PR runs from scheduled integration runs.

When should I not use this code sample audit skill?▼

Do not use it for writing a single quickstart page, authoring teaching tutorials, auditing endpoint-level API reference completeness, or reviewing the product's own source code. Those tasks route to the quickstart, tutorial, API reference, or code review skills respectively.

Related Skills

Explore More Content & Communication Skills→
loriensleafsloriensleafs

fix-markdown-fences

Repair malformed Markdown code fence closings across repository directories or files using Python's regex and pathlib libraries.

Community
Basic
Godhand-ArnavGodhand-Arnav

env-secrets-manager

Audit environment-variable hygiene and detect leaked secrets in codebases.

Community
Intermediate
musher-devmusher-dev

analyzing-docs-benchmarks

Benchmark developer documentation sites against industry leaders using structured pattern extraction and scorecard templates.

Official
Advanced
GoldziherGoldziher
115

Documentation Standards & Language Parity

Enforce documentation standards and language parity across seven programming languages.

Community
Advanced