Skip to content
Skills Library
Programming · Writing

explain

/explain

Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong: \"document this\", \"write docs for our library\", onboarding someone onto an internal API, or handing a package to another team.

Repository
mastermind ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong: \"document this\", \"write docs for our library\", onboarding someone onto an internal API, or handing a package to another team.

Triggers from the description

document this\write docs for our library\
Original author description

Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong: \"document this\", \"write docs for our library\", onboarding someone onto an internal API, or handing a package to another team.

How it works

  1. Ask first: always
  2. Method
  3. Guardrails
Original SKILL.md headings · 60 lines, 641 words
SKILL.md preview
---
name: explain
description: "Use when an internal package, module, or shared component has little or no usage documentation and people (or future AI sessions) keep using it wrong: \"document this\", \"write docs for our library\", onboarding someone onto an internal API, or handing a package to another team."
---

# Document Package: make an internal package self-explaining to any model

Most internal packages ship with **no usage docs**, so every consumer: a teammate, *or an AI*: reads the
source, guesses the intended usage, and gets the gotchas wrong. This skill fixes that: **one colocated
usage doc per public unit**, capturing the API *and* the non-obvious rules, so the next reader is correct
on the first try. It applies to **any** package: a UI component kit, a utils library, a services/API
layer, a hooks package, an internal SDK.

> **Why it matters for portability:** these docs are the layer that makes your package understandable to
> *any* model. If you move from one AI tool to another, the new model still
> understands your package immediately: the knowledge lives in the repo, not in one model's head.

Their own words stay theirs: propose, never rewrite unasked (`~/.mastermind/engineering/core/rigor.md` → Stay in scope).

## Ask first: always
This writes files into the user's repo. **Confirm before doing anything:** *"I can generate AI-friendly
usage docs for `<package>` so any model (and teammate) understands it correctly: one doc per public unit,
with the gotchas. Want me to? (I'll show one sample first.)"* Show a **sample doc** for one unit and get a
thumbs-up before fanning out across the package.

## Method

1. **Discover the public units.** Read the package's public entry (`index.ts`/exports) for the real list,
   components, exported functions, hooks, services, classes. Note any existing docs' style and **match it**.
2. **Never write a line you have not read the source for.** For each unit: the implementation, its types, its
   variants/options, its tests/stories, and **one real usage** in the codebase. Verify every claim against
   the code (never document a guess; mark "unverified" or omit).
3. **Write a colocated doc** (a `README.md`/doc beside the unit) with a consistent template:
   - **Title + one-line purpose + what it's built on.**
   - **Signature / API**: a table: params/props/args · type · default · description; what it returns.
   - **Quick start**: the minimal correct usage (real import path).
   - **Variants / options / states** (where applicable), with a code example each.
   - **Composition**: how it combines with siblings.
   - **Examples**: the handful of real scenarios people actually need.
   - **Gotchas**: the highest-signal section: rules the API *doesn't* enforce but people get wrong
     (default values, which state hides what, reserved-but-unimplemented options, ordering constraints).
   - **Errors / accessibility / TypeScript**: as relevant to the unit's kind.
4. **Prioritize the gotchas.** The API table can be inferred from types; the gotchas cannot. That's the value.
5. **Stamp it so drift is detectable.** The code is the SSOT; the doc is derived: so record *what* it
   was derived from, the way `engineering/ROUTER.md` records a hash per node. End each doc with a
   footer naming the source file(s), the repo commit SHA at generation time, and a short content hash
   of each source (`git rev-parse --short HEAD`, `git hash-object <file>`):

   ```html
   <!-- generated-from: src/Button.tsx@a1b2c3d (hash 9f4e21bc) · regenerate if the hash differs -->
   ```

   **Detecting drift** is then a one-liner anyone (or any model) can run: re-hash the source and
   compare to the footer, `git hash-object src/Button.tsx`, or `git log a1b2c3d..HEAD -- src/Button.tsx`
   to see whether the unit changed since. Mismatch → treat the doc as **stale**: re-read the source and
   regenerate that unit before trusting it. No build script required; if the repo already has a docs
   check or pre-commit hook, wire the same comparison into it rather than inventing a second mechanism.

## Guardrails
- **Derive from source, never invent.** Unconfirmable behavior → "unverified" or omit.
- **One doc per unit, colocated**: found next to the thing it describes, travels with it.
- **Match the package's existing doc style** if any exists; consistency beats your template.
- **Confirm scope + a sample before mass-generating**: the template must fit before you fan out.
Files in this package (2)
  • ABOUT.md 4 KB
  • SKILL.md 4 KB

Versions

RepositoryScoreLicence
This page · mehrad-dm/mastermind100MIT
crbnos/carbon100AGPL-3.0
PerilloAI/flowtrace-plugin100Apache-2.0
mickeyyaya/evolve-loop100Apache-2.0
zenobi-us/dotfiles100MIT
imgly/agent-skills100MIT
marcel-bich/marcel-bich-claude-marketplace100MIT
nicodiansk/draw-it-out100MIT
ramboz/jig100MIT

Database snapshot: 13.11.2026 · package version c1de8e5583e0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-docs
    Document a module or public API surface (functions, classes, CLI commands, endpoints) from the code itself. Use when the user asks for API reference, to document a module, or to write usage docs for a public interface.
  • 100write-docs
    Generate documentation for custom elements based on their manifest data. Use when the user asks to "write docs", "generate documentation", "document this element", "create API docs", or mentions "usage examples" or "component documentation".
  • 100migrate-internal-package
    Move a package from another TryGhost repository into Ghost as an internal-only workspace package while preserving its Git history. Use for package migrations from repositories such as TryGhost/SDK or TryGhost/framework, including the history import PR, exceptional merge-commit…
  • 100doc-component
    Document a Svelte component using @component JSDoc. Auto-invoke when asked to document a .svelte component. Reads the component, analyzes its interface, and writes a structured @component comment block.
  • 100yii3-package
    Develop, review, test, or document a Yii3 package while preserving its public contract, package classification, dependency boundaries, repository toolchain, and Yii contribution conventions. Use for package or library work; not application assembly, runtime wiring, or a…
  • 100find-examples
    Find usage examples of an API, library, or code pattern across internal repositories — use when looking for how other teams use an internal API, library, or pattern before implementing something new.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.