docs: address Copilot review round 9 on #2203

Restrict the truncation guard to PLAIN scalars. `yaml` attaches a legitimate
trailing comment to quoted and block scalars too, so keying on `.comment` alone
rejected valid frontmatter — `description: "Complete value" # note` was reported
as truncated, telling the author to quote a value that was already quoted. The
regex this replaced tested the same thing by reading the first character; moving
to the node dropped the check rather than encoding it. Verified all three
shapes (double-quoted, single-quoted, block) against the parser, and added the
regression cases.

Also correct the `--max-turns 1` bullet in docs/skill-authoring.md, which
claimed the skill must be the model's first tool CALL. `collectSkillInvocations`
scans every tool_use block in the assistant event without regard to order, so a
turn calling Read and Skill together scores a hit. What actually loses the
sample is needing a tool RESULT first — that decision lands in turn two, which
never runs. The practical advice is unchanged; the mechanism now matches the
collector.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SyBPs7caoMcyvnp9ArMBhV
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-09-01 13:02:14 -04:00
commit afca8faaea

View file

@ -176,6 +176,13 @@ export function parseSkill(dirName, text) {
// `typeof node.value !== "string"` also covers the non-scalar cases: a map
// or list node has no `.value`, and its own checks above already report it.
if (!node || typeof node.value !== "string") continue;
// Only on a PLAIN scalar is a comment evidence of loss. A quoted or block
// scalar can carry a perfectly legitimate trailing one — `description:
// "Complete value" # note` keeps its whole value — and flagging that told
// the author to quote a value they had already quoted (Copilot). The regex
// this replaced tested the same thing by reading the first character; the
// node states it outright.
if (node.type !== "PLAIN") continue;
const dropped = node.comment;
if (typeof dropped !== "string") continue;
errors.push(