Index of every page on this site: llms.txt
All skills
tomdale avatar

/inside-mac

@b93b184
by Tom Daletomdale/inside-mac22 stars
2
Run it yourself

Plans, writes, reviews, and renders developer documentation in a modernized Inside Macintosh style, with concepts, tasks, and reference kept separate, reader roadmaps, behavioral contracts, and an optional print-quality PDF book. Use when asked to write, restructure, explain, document, or review an API, SDK, CLI, framework, protocol, or system as a guide, chapter, tutorial, reference, or book; when asked for Inside Macintosh or inside-mac style; or when rendering Markdown documentation as a PDF book.

Use this Skill: https://skilld.dev/gh/tomdale/inside-mac/inside-mac

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈129 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈13k more on demand in 15 files.

Description uses 6.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈518 characters, or 6.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Write documentation in the Inside Macintosh style

Apple's Inside Macintosh (1985–1994) taught each part of the Macintosh system software in the same order: it oriented the reader, explained the model, taught the common tasks, and then specified the contract for lookup. Apply that order to modern systems, written for linked, searchable web documentation with tested TypeScript or JavaScript examples. Render a PDF book when the user wants a printable deliverable.

Load the reference for the task

Task Load
Plan a book, documentation set, or chapter: structure, roadmaps, cross-links, length budgets architecture.md
Decide audience, depth, and what to include; work from code, READMEs, and design documents content.md
Write or repair prose: voice, modal verbs, callouts, readability, text that reads as generated voice-and-tone.md
Explain a concept: mental model, vocabulary, lifecycle, figures concepts.md
Write a task guide, tutorial, or quickstart with examples task-guides.md
Write reference entries for functions, types, commands, events, configuration, and errors api-reference.md
Review a draft or a documentation PR review.md
Render Markdown as a PDF book with the pipeline in assets/ pdf-book.md
Find the original passages behind a technique sources.md

Load every file the deliverable needs. Any drafting task needs content.md and voice-and-tone.md. A full book starts with architecture.md and content.md, uses concepts.md, task-guides.md, and api-reference.md while drafting, finishes with review.md, and uses pdf-book.md to render.

Core rules

  • Write for the builder who uses or extends the system. Internal implementation appears only where it explains a contract, a correctness boundary, or a failure the builder must handle.
  • Teach concepts before the tasks that depend on them, and tasks before the reference. Separate the three per subsystem: inside a chapter when each chapter documents one subsystem, across the book when one system spans many chapters.
  • Open the book and every chapter with a roadmap that tells each reader what to read and what to skip.
  • Make behavior complete: guarantees and non-guarantees, completion states, ownership, errors and recovery, retry safety. Link to the declarations, inventories, and enumerations that source code or generated documentation define; hand-copied lists go stale.
  • Write what stays true as long as the design does. Implementation detail appears through links or a reference table when a reader must act on it, and transient detail stays out.
  • State verified facts in the document's own voice. Project READMEs, design documents, and code comments are sources of facts; the prose neither quotes them nor narrates the research.
  • Meet a length target by removing topics, repetition, and enumerations. Keep sentences whole, connectives explicit, and the reason behind each rule.
  • Put each warning at the point of danger, with the consequence and the safer alternative.
  • End a chapter after its last substantive section. An optional interface summary (names with links, or a generated inventory) may close a chapter or book; a prose recap never does.
  • State each fact once, where a reader would look for it, and link to it from elsewhere.

Drop aged practices

Do not reproduce these features of the originals:

  • print page references, static indexes, and material duplicated across volumes;
  • Pascal-first, assembly-language, register, or trap documentation;
  • hardware addresses, private memory layouts, and internals outside the public contract;
  • global result codes where typed errors, rejected promises, or exit statuses apply;
  • interfaces maintained by hand in several languages;
  • primary examples with omitted error handling, hedges about whether samples were tested, and disclaimers that samples are not for use;
  • compatibility caveats scattered through the prose instead of structured version metadata;
  • paternalistic, gendered, moralizing, or vendor-universal language;
  • long linear prose where numbered steps, tables, links, or progressive disclosure serve the reader better.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts11d3 checks · Risk SAFE
  • Gen Agent Trust Hub11d

    The skill provides a comprehensive framework and build pipeline for creating developer documentation in a modernized Inside Macintosh style. It includes a Node.js build script that uses Puppeteer and Mermaid to render Markdown files into paginated PDFs. The analysis identified standard behaviors such as dependency installation via NPM, local file system management, and browser automation for rendering, all of which are appropriate for the documented purpose. Clear instructional boundaries are provided to the agent to ensure source material is processed objectively.

  • Socket11d

    No alerts

  • Snyk11d

    Risk: LOW · No issues

Signed by skilld at b93b184. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 weeks ago

README badge

README badge for tomdale/inside-mac