agentsclimarketplace

Update docs

Skill RubenGlez/harness/skills/update-docs

Update all project documentation to reflect the current state of the codebase. Use after finishing a feature, refactor, or any meaningful change — or whenever docs feel stale.From its SKILL.md

Install
npx -y skills add RubenGlez/harness --skill update-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 3 commands, including `git log --oneline -20` and 2 more.

SKILL.md

4.0 KB, 937 tokens by cl100k_base, as published. Nobody here has run it

Update Docs

Step 1: Build a current-state summary

Before writing anything, read everything.

Git history: git log --oneline -20, note which areas were touched.

Existing docs: read all files under .harness/ and any root docs (README.md, DESIGN.md, CHANGELOG.md).

Codebase: scan key directories, check package manifests, note what's implemented, removed, or changed. Verify the project sync standard: CLAUDE.md should contain only @AGENTS.md, and AGENTS.md should contain only durable, agent-facing facts that are not reliably inferable from the repo itself.

Reconcile phase status. This skill is the owner of status consistency — no other skill cross-checks it. Phase state lives in three sources that drift independently: per-feature Status: lines in .harness/engineering/features/, phase markers in .harness/product/roadmap.md, and the latest .harness/qa/report.md. Compare them against each other and against the actual code:

  • A feature marked done whose code isn't there (or vice versa) → fix the spec to match reality.
  • A roadmap phase whose features are all done but is still marked planned → advance the roadmap marker.
  • A qa/report.md listing outstanding failures for a feature still marked done → the spec is lying; reflect the failure. Record each disagreement in the summary's "Stale docs" section so Subagent A corrects it.

Synthesize a current-state summary (subagents receive this verbatim):

## What the product is now
[One paragraph: what it does, who it's for, current state]

## Recent changes not yet in docs
- [change] — [which docs this affects]

## Stale docs
- [file path] — [what's outdated and why]

## Accurate docs (do not touch)
- [file path] — [why it's still current]

## Missing docs
- [file path that should exist but doesn't, and why]

Step 2: Spawn two subagents in parallel

Runtime note: subagents are Claude-specific. Without them (e.g. Codex), see ../_shared/runtime-parallelism.md and write the two doc sets sequentially — you remain the single writer either way.

Pass the full current-state summary to each — they cannot read the conversation or codebase themselves.

Subagents A and B write different files — two subagents must never edit the same .harness/ file (one writer per doc — concurrent edits merge byte-wise but conflict semantically).

Subagent A updates internal docs under .harness/: product.md, roadmap.md, competitors.md, ux.md, CONTEXT.md, architecture.md, implementation-plan.md, adr/, features/[slug].md, qa/report.md.

Only update a file if the summary shows it's stale. Do not touch accurate files. Never link to .harness/ from public docs.

Subagent B updates public docs: README.md, DESIGN.md, CHANGELOG.md, AGENTS.md.

Keep public docs strictly separated from internal content — no .harness/ links, no internal strategy, no implementation details.

See REFERENCE.md for the detailed rules and content guidelines for each file.

Step 3: Refresh the doc index and commit

After both subagents finish, run doctier agents --write to refresh the managed doc index in AGENTS.md (the block between <!-- doctier:begin --> and <!-- doctier:end -->). Then commit everything — worktrees and future sessions only see committed .harness/ content:

for f in .harness AGENTS.md README.md DESIGN.md CHANGELOG.md CLAUDE.md; do
  [ -e "$f" ] && git add "$f"
done
git commit -m "docs: sync with current state"

Step 4: Confirm

Report:

  • Every file updated, with one line on what changed
  • Every file left untouched and why
  • Confirmation that the doc index refresh and the commit landed
  • Any doc gaps this run couldn't fill

Recommend next step: release the phase with /ship if it's user-ready, or start the next phase with /implement.

What ships with it: 1 file

4.6 KB alongside SKILL.md

Gives 0 of the 12 instructions most docs writing skills give in 937 tokens

Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06

  • Use third-person for skill descriptionsin 54 of 1951, across 35 files
  • Start descriptions with Use whenin 43 of 1951, across 29 files
  • Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
  • Use active voicein 40 of 1951, across 36 files
  • Map file responsibilities before defining tasksin 36 of 1951, across 29 files
  • Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
  • Ask one question at a timein 35 of 1951
  • Offer execution options after saving the planin 33 of 1951, across 24 files
  • Include complete code in every stepin 33 of 1951, across 27 files
  • Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
  • Announce the skill usage at the startin 30 of 1951
  • Verify agent compliance after adding the skillin 29 of 1951, across 17 files

Said here and by no other author read

  • Read git history and existing documentation
  • Reconcile status across all documentation sources
  • Synthesize a current-state summary
  • Spawn two subagents to update documentation
  • Update internal docs only if stale
  • Keep public docs separated from internal content

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 611,811. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.