sugatoray/aiskills

create-lib-docs

Writes top-grade, verified user documentation for a library, CLI or framework as a folder of Markdown pages plus SVG diagrams, structured the way FastAPI, Pydantic, DuckDB and Effect structure theirs: a landing page with a 30-second example, Getting Started…

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/sugatoray/aiskills --skill create-lib-docs

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

Creating library documentation

Good library docs answer four different questions, and the best projects keep them on separate pages instead of mixing them: teach me (tutorial), help me do X (how-to guide), explain why (concepts), tell me exactly (reference). FastAPI, Pydantic, DuckDB and Effect all follow that split, each with its own strengths. This skill reproduces it for any library, adds what AI agents need (stable anchors, exact schemas, llms.txt), and refuses to publish anything unverified: a plausible-looking snippet that doesn't run is worse than no snippet.

references/patterns.md lists what to borrow from each reference project, and references/templates.md has the page skeletons. Read both before planning the docs.

Options

Read the invocation text for these, in any order:

  • `--lib <path>`: the library's root folder (where its code, tests and pyproject.toml /

package.json / Cargo.toml live). Default: the current project.

  • `--out <dir>`: where the docs go. Default: <lib>/docs/<lib-name>/. If the user names a

folder in plain words ("inside docs/callai/"), that wins.

  • `--update`: the docs already exist. Refresh them against the current code instead of

starting over. Keep page paths and heading anchors stable, because people and agents link to them.

  • `--sections a,b,...`: write only these sections (e.g. reference,guides).

Steps

1. Learn the library from primary sources only

Docs written from memory drift into fiction. Build an inventory from what the code does:

  • Public surface. Every CLI flag (run --help, and read the parser), every public function and

class (exports, __all__, index.ts), every config key, environment variable, output field, exit code and error message. Write the inventory to a scratch file. The Reference pages are built from it, and step 6 checks against it.

  • Behaviour. Tests, conformance or fixture suites, the design doc, the changelog, and the

project's own notes (e.g. docs/.scrolls/). Tests show real inputs and outputs. Changelogs show which behaviour is deliberate.

  • Limits. Known gaps, refusals and platform caveats. Good docs say what the library does not

do, and what happens if you try.

  • Run the library. Capture real output for the examples. If it needs network access or

credentials you don't have, use the project's own fakes or stubs and say so in the example. Don't invent output.

2. Plan the information architecture

Map the inventory onto the sections in references/patterns.md → "Information architecture". The default tree, with an index per section:

docs/<lib>/
├── README.md            landing: what/why in 3 lines, 30-second example, features, map of the docs
├── getting-started/     why-<lib>, installation, quickstart (first success in < 5 minutes)
├── tutorial/            numbered, progressive; each step builds on the last; ends with "Recap"
├── guides/              task recipes ("How to …"), self-contained, any order
├── concepts/            explanations and mental models, with diagrams
├── reference/           exhaustive and dry: CLI, API, config, schemas, errors (one anchor each)
├── faq.md               troubleshooting + questions people actually ask
├── license.md           the library's license, and a table of what each bundled part uses
├── images/              SVG diagrams (text-based, diffable)
├── llms.txt             index for AI agents (generated)
└── llms-full.txt        every page in reading order, one file (generated)

Drop a section only if the library really has nothing for it, e.g. a one-function library needs no tutorial. Size the tutorial to the learning path, not to the feature count. FastAPI's has ~50 short steps; a small CLI needs 5–10. Write the plan (page list, one line each) before writing pages.

Always write license.md, and link it from the landing page under its own ### License section, so a site built from those sections gets a License tab. It says, in its first sentence, what license the library itself uses (the SPDX id, linked to the LICENSE file), then gives a table. When the library bundles or vendors parts with their own licenses (plugins, skills, templates, fonts, data), the table has one row per part: its name, its license, and where that license is declared. Take every value from the files themselves (package.json/pyproject.toml, LICENSE, each part's own metadata), never from memory, and say plainly when parts differ from the library. Generate the table if the parts can change, so it can't go stale.

3. Write the pages

Use the skeletons in references/templates.md. Rules that apply everywhere:

  • One job per page. Never mix tutorial, how-to, explanation and reference on one page. Link

between them instead: a tutorial step ends with "Reference: `--flag`", and a reference entry links to the guide that uses it.

  • Lead with the answer. Each page opens with a one-sentence summary (it becomes the page's

llms.txt description), then the shortest working example, then detail.

  • Complete, copy-pasteable snippets. Include imports and setup. Don't add $ prompts inside

copyable blocks; put output in its own block labelled as output. Always label the fence language (bash, python, json, toml, text).

  • Show the output of every example: the real output from step 1, trimmed with … only where

noise doesn't matter.

  • Admonitions use GitHub alert syntax so they render on GitHub and stay plain Markdown:

> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]. Keep them rare: more than two per screen and readers skip them all.

  • Name things one way. Pick one term per concept, use it everywhere, and define it once (a

glossary entry in Concepts or the FAQ).

  • Navigation. Every page ends with Next: / Previous: links (tutorial) or See also:

(everything else). Every page is reachable from README.md.

  • Write for agents too. Agents read the Markdown source and can't see images, so:
  • give every diagram a text equivalent next to it (a list, a table or the steps);
  • give every reference entry a stable heading anchor (#--resume, #harnessnotfound);
  • show exact schemas as JSON with field types;
  • add a guide on using the library from an agent (non-interactive use, machine-readable

output, exit codes, failure modes).

  • Plain language. Second person, present tense, short sentences, no marketing ("blazing",

"seamless", "powerful"). Say what happens, including what can go wrong.

4. Draw the diagrams

Diagrams are hand-written SVG in images/, so they diff, review and render everywhere:

  • Explain the shape of the system: architecture, a run's lifecycle, data flow, precedence order,

concurrency. Don't draw decoration.

  • Use an opaque light background and dark text (a <rect> filling the canvas), so the diagram stays

legible on GitHub's dark theme. Use system sans-serif and monospace font stacks, with text at least 13px.

  • Embed with meaningful alt text: ![Architecture: CLI and Python API share one run path …](images/architecture.svg).
  • Render each SVG to PNG (Playwright or a headless browser) and look at it before publishing:

check for clipped text, overlaps and arrows pointing nowhere.

5. Generate the agent indexes

Run scripts/build_llms_txt.py <docs-dir>. It reads README.md's sections and links in order, and writes:

  • `llms.txt`: title, summary, and one - [Title](path): description line per page, grouped by

section (llms.txt convention, as Pydantic and Effect publish).

  • `llms-full.txt`: every page's Markdown in reading order, each preceded by its path.

Re-run it whenever a page changes. Both files are generated, so never edit them by hand.

6. Verify everything before calling it done

  • python3 scripts/check_docs.py <docs-dir> must pass. It checks:
  • relative links and #anchors resolve;
  • images exist and have alt text;
  • every code fence has a language;
  • every page is reachable from README.md;
  • llms.txt lists every page;
  • license.md exists and has a table.
  • Run every snippet. Shell commands and code examples run, and their output matches what the

page shows (allowing for timestamps, ids and durations). Where the real dependency is unavailable, run against the project's fakes or stubs and say so on the page.

  • Check the reference against the inventory from step 1. Every flag, function, config key, env

var, output field and error appears, and nothing documented doesn't exist. A quick check is to diff the flags in reference/cli.md against --help.

  • Read each page once as a newcomer (is anything used before it's explained?) and once as an agent

(could you call the library correctly from this page alone?).

7. Report

Tell the user:

  • where the docs are, and the page count per section;
  • what was verified and how: snippets run, against what, and any stubs used;
  • anything left unverified or undocumented, and why.

Link the landing page. If the project keeps a changelog or project notes, add an entry there too.

del mismo repositorio

Más Skills

Todos los Skills
sugatoray
Comunidad

dynamic-promo-video

Build a short narrated promo/intro video (HTML scenes, zoom/tilt, voiceover, music) for a library, app or product. Use for explainer or launch videos made from code, real screenshots and TTS.

Instalaciones / 1h
2
GitHub Stars
4
Actualizado
18 nov
sugatoray
Comunidad

meeting-agenda

Turn a meeting agenda into a self-contained HTML slide deck with a countdown timer per item: one slide per item (large 01, 02… number, title, optional sub-points), a ring timer that turns amber in the last 20% and red with a +M:SS count-up past zero, a footer with clickable progress dots and a per-item meeting progress bar, and a built-in editor (gear button) that saves to localStorage or downloads an updated copy. Use when the user invokes /meeting-agenda, or asks for agenda slides, a timed age

Instalaciones / 1h
2
GitHub Stars
4
Actualizado
18 nov
sugatoray
Comunidad

scrolls-compact

Compacts the history in a docs/.scrolls/ (or docs/scrolls/) project-memory system at a point in time, and saves a git checkpoint of everything it condenses. Condenses the parts of SPEC.md, PLAN.md, HANDOFF.md, GAPANALYSIS.md and GAPCONTEXT.md that git blame shows are older than a compaction base — by default the newer of 7 days ago and the 20th-latest first-parent commit on main/master — while open tickets, open gaps and HANDOFF's open threads always stay word for word. Records ONE commit whose

Instalaciones / 1h
2
GitHub Stars
4
Actualizado
18 nov
sugatoray
Comunidad

scrolls-explainer

Shows, copies or rebuilds scrolls-explainer.html: an interactive, offline page that explains how the scrolls skill family works (/scrolls-setup, /scrolls-update, /scrolls-hide, /scrolls-unhide, /scrolls-remove, /scrolls-restore, /scrolls-help) — one tab per command that animates, step by step, what the command does to docs/.scrolls/, SCROLLS.md, CLAUDE.md, AGENTS.md and git, with a callout explaining each step, a tab for how a new agent session reads the memory, and full keyboard navigation (arr

Instalaciones / 1h
2
GitHub Stars
4
Actualizado
18 nov