---
name: inside-mac
description: 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.
title: inside-mac
canonical_url: https://skilld.dev/gh/tomdale/inside-mac
last_updated: 2026-10-31T05:23:01.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [assets/book.json](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/book.json), [assets/build.mjs](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/build.mjs), [assets/package.json](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/package.json), [assets/src/00-front.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/src/00-front.md), [assets/src/01-widgets.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/src/01-widgets.md), [assets/src/02-reference.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/src/02-reference.md), [assets/src/90-appendix.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/src/90-appendix.md), [assets/style.css](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets/style.css), [references/api-reference.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/api-reference.md), [references/architecture.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/architecture.md), [references/concepts.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/concepts.md), [references/content.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/content.md), [references/pdf-book.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/pdf-book.md), [references/review.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/review.md), [references/sources.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/sources.md), [references/task-guides.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/task-guides.md), [references/voice-and-tone.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/voice-and-tone.md).
>
> If the user asked to install this Skill, run `npx skilld install tomdale/inside-mac/inside-mac`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/inside-mac`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/tomdale/inside-mac/inside-mac) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/inside-mac`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/inside-mac --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/inside-mac --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/architecture.md) |
| Decide audience, depth, and what to include; work from code, READMEs, and design documents | [content.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/content.md) |
| Write or repair prose: voice, modal verbs, callouts, readability, text that reads as generated | [voice-and-tone.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/voice-and-tone.md) |
| Explain a concept: mental model, vocabulary, lifecycle, figures | [concepts.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/concepts.md) |
| Write a task guide, tutorial, or quickstart with examples | [task-guides.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/task-guides.md) |
| Write reference entries for functions, types, commands, events, configuration, and errors | [api-reference.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/api-reference.md) |
| Review a draft or a documentation PR | [review.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/review.md) |
| Render Markdown as a PDF book with the pipeline in [assets/](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/assets) | [pdf-book.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/pdf-book.md) |
| Find the original passages behind a technique | [sources.md](https://skilld.dev/api/skills-raw/tomdale/inside-mac/inside-mac/references/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.
