SIGN IN SIGN UP

docs(coding-agents): generate the companion skill from the README (#3735) (#3753)

The skill and the README documented the same configuration in two hand-
maintained files, and they drifted in both directions.

The skill never named `bankIdTemplate`, `dynamicBankId`, `optInOnly`,
`optInPaths`, `retainTags`, `retainMetadata`, `resolveWorktrees`,
`maxParallelRetains` or any daemon setting, and it stated outright that
the package reads "no environment variables" — there are 35
(core/config.ts ENV_KEYS). That is the half #3735 reported. The README
had lost the other half: `autoReflect` and `surveyRefreshCommits` were
documented only in the skill, and neither file mentioned that
`HINDSIGHT_CONFIG` relocates the config file, that the layering chain
ends at `banks.<resolvedBankId>`, or that `optInPaths` takes a
comma-separated env value like its sibling `retainTags`.

The README is now the single source. scripts/build-skill.mjs copies the
regions it marks with `skill:begin` / `skill:end` into skill/SKILL.md,
normalising heading levels per region; only the agent-facing half — which
tools to call, crediting memory, correcting a stale memory — stays
separate, in skill-src/preamble.md. The docs page was already generated
from the README; its generator now strips the markers, which MDX cannot
parse.

The skill's operative debugging knowledge (sync-status readiness,
resetting a bank, the survey-baseline/gitlog marker documents, the
session_start/deepen_started triage rule) moved into the README, so it
reaches users and the docs site too.

src/docs-freshness.test.ts fails when the skill is stale, when a field of
`RawConfig` is readable from a config file but named nowhere in the
README — the check that makes this class of drift impossible to
reintroduce — and when a documented claim about the env layer stops
holding (every key really is `HINDSIGHT_<FIELD_IN_CAPS>`; the four
map-valued settings really are file-only). It also unit-tests the marker
parser. prepublishOnly regenerates the skill so a publish cannot ship a
stale copy.
N
Nicolò Boschi committed
1b74e3efa8a28ec564c5b04b617596f07f09d8c0
Parent: 8667598
Committed by GitHub <noreply@github.com> on 8/24/2026, 9:06:28 AM