Skip to content

Skill sections render as subsections of injected guidance #1252

Description

@williamthorsen

Problem

Three skills place an injection directive where a ### follows within the same parent ##. Injected content brings its own headings, so the following section renders as a subsection of the injection rather than of the skill: respond-to-review's ### Writing code after a review, revise-comments's ### File-level carve-outs, and testing-conventions's ### Test files all land under the inlined ## Comment discipline.

A guidance hook makes the shape worse, because its content varies per binding: the parent becomes whichever rulebook the local codeassembly.yaml supplied. respond-to-review escapes that today only because its include follows its hook and re-establishes a ##.

Nothing guards the shape, and the placement rule is stated nowhere.

Context

The nesting was authored deliberately: #973 replaced each skill's own ## Comment discipline section with the partial and demoted the residual prose to a ### beneath it.

#1176 adds a second hook to respond-to-review. Placed below the include, it reparents ### Writing code after a review under a user-bound rulebook.

Proposed solution

Injected content never adopts a host section: a host heading following a directive sits at or above the injected content's shallowest heading level, which is ## for a hook and the partial's own shallowest for an include. Promote the three sections, state the rule where content authors meet it, and guard it with a content-convention test that exempts nothing.

Acceptance criteria

Must have

  • No section of a skill or subagent renders as a subsection of injected content.
  • A content-convention test reports the shape in any body under content/, for includes and guidance hooks alike, with no allowlist.
  • The placement rule is stated in the content specification and the partial-system reference.

Should have

  • respond-to-review places its include before its hook, matching implement-plan and review-criteria.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions