Skip to content

docs: fix the SKILLS.md heading hierarchy - #32

Merged
gregoryfoster merged 1 commit into
mainfrom
docs-skills-structure
Aug 7, 2026
Merged

docs: fix the SKILLS.md heading hierarchy#32
gregoryfoster merged 1 commit into
mainfrom
docs-skills-structure

Conversation

@gregoryfoster

Copy link
Copy Markdown
Contributor

Structural only — no fact in this doc changes.

The break

## The write-guard hook dangles on a submodule-less checkout sat between
### From gregoryfoster-skills and ### From obra-superpowers. An H2 in that position
terminates ## Available skills halfway through its own inventory, which makes the
obra-superpowers skill table a child of the write-guard section instead of the skills list.

Second, smaller: the v1.2 hold prose lived under ### From gregoryfoster-skills, a section whose
job is listing what that submodule provides. The hold is about submodule pinning and the suspended
refresh — adjacent, but not that.

After

# Agent Skills
## Vendor submodules
## Available skills
   ### Local overrides
   ### From gregoryfoster-skills
   ### From obra-superpowers
## Plans directory
## The curating-context v1.2 hold      <- lifted out of the table section
## Maintenance
## The write-guard hook dangles ...    <- moved down
## Submodules in CI

Reading order is now normal path first, exceptions after: maintenance, the hold that suspends part
of it, the hook that dangles without it, and CI.

The one substantive addition

The Maintenance block's git submodule update --remote --merge sat two lines above prose the
hold forbids, with nothing marking it. It now carries # SUSPENDED during the v1.2 hold — it would bump gregoryfoster-skills past the pin. Everything else is a cross-reference: the gregoryfoster
section points at the hold, and the CI section's "the v1.2 hold above" became a link now that it is
no longer directly above.

Verification

  • Content-preservation check: sorted line-diff against HEAD shows only the intended additions —
    the new H2, two cross-reference lines, the SUSPENDED comment, and one bullet reflow. No prose lost.
  • Anchors: all three intra-doc links resolve against the GitHub slug rules (#submodules-in-ci,
    #the-curating-context-v12-hold ×2). No inbound anchor links exist elsewhere in the repo — checked.
  • codebase_context_index re-run; skills-doc re-chunked. Its manifest description still describes
    the file accurately, so it is unchanged.
  • uv run ruff check . clean, ruff format --check clean, uv run pytest — 444 passed, 99.77%.

🤖 Generated with Claude Code

`## The write-guard hook dangles on a submodule-less checkout` sat between
`### From gregoryfoster-skills` and `### From obra-superpowers`, so an H2
terminated `## Available skills` mid-inventory and the obra table became a
child of the write-guard section rather than of the skills list.

Moves that section down beside the other two submodule-operational
sections, and lifts the v1.2 hold prose out of the gregoryfoster skills
table into its own `## The curating-context v1.2 hold` — it is about
submodule pinning and the suspended refresh, not about what that table
lists. The gregoryfoster section keeps a pointer to it.

Reading order is now normal path then exceptions: Maintenance, the hold,
the dangling write-guard hook, submodules in CI. The Maintenance block's
`git submodule update --remote --merge` gains the note that it is
suspended for the duration of the hold — it was directly above advice the
hold forbids.

Prose is unchanged except for those cross-references. Anchors verified to
resolve; codebase_context_index re-run for the moved chunks.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@gregoryfoster
gregoryfoster merged commit 7588c9b into main Aug 7, 2026
2 checks passed
@gregoryfoster
gregoryfoster deleted the docs-skills-structure branch August 7, 2026 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant