build-with-me

The problem it solves

Most generated documentation explains finished code. The finished code cannot tell you that the build failed twice because a file was locked, that the obvious approach was wrong, that three attempts were tried before one worked. That information exists only in the history of the work.

This skill keeps the mistakes. A step looks like this:

What comes out

• an opening that says what is being built and why, before any detail;
• a contents listing of volumes, chapters and elements;
• every element answered three times: what it is, why it exists, what breaks without it — concretely, not “it is required”;
• code written out live in prose, not tabulated;
• two kinds of errors kept apart: the ones that actually happened, quoted verbatim, and the ones a reader starting from a different machine is about to hit;
• abandoned approaches, recorded so the reader does not spend the same hour.

Structure

Volume      a major part of the program: a platform, a runtime, a subsystem
  Chapter   a phase with a checkable outcome: "the build produces a signed APK"
    Element a file, an asset, an object, a layer — what breaks without it
      Step  the action, written out, with its reason and its consequence

Install

npx skills add fworkslab/build-with-me@build-with-me -a opencode -g -y

Or copy it yourself — a skill is one file with a YAML header:

~/.config/opencode/skills/build-with-me/SKILL.md

It is not only for code

The structure survives when the project is not a program. Only the vocabulary changes: the element is whatever the reader will come back to when something is broken, and a step is any action named exactly enough to repeat.

Project	An element is	A step is
Program	a file	code
Game on an engine	an asset, an actor, a Blueprint, a level	a tool call, a console command
Blender	a collection, a modifier, a bone, a keyframe	an exact operation with its setting
Maya, Houdini, ZBrush	a node, a subtool, an anchor point	an exact parameter change
Spreadsheet, analysis	a sheet, a named range, a formula	the formula, with its cell addresses
Document	a heading level, a section, a style	applying the named style
Drawing	a layer, a pass, a palette	a stroke with tool, size, angle

What it will not do

• Pad a small project. Elements are counted from the machine before any chapter is planned, so a folder holding one file gets one chapter — not two volumes, a contents tree, and eight hundred lines.
• Invent a past error. If a step went cleanly, it says so. A tutorial with manufactured problems teaches the reader to expect failures that never occur.
• Invent a history of troubles it never saw. Given a repository someone else built, the structure and reasoning still work because they are deduced from the files. What actually went wrong does not — and the tutorial says plainly which parts are reconstructed from the code rather than from the build.

License