From fc80d8d3a249bc4fa22d5fc91bf00f15282dadfa Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Sun, 14 Jun 2026 16:24:05 -0700 Subject: [PATCH] docs(skill-authoring): drop inaccurate Codex/Gemini claim from skill prose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three skill files claimed that on non-Claude targets the `:-.` fallback 'yields the bare relative path those harnesses expect.' A Codex investigation (converter source + live runtime) disproved this: the converter preserves ${CLAUDE_SKILL_DIR:-.} verbatim and the var is unset at runtime, so it expands to a project-CWD-relative ./scripts/... that does NOT resolve to the bundled script (it lives in the platform's skill store). The claim is the same overclaim corrected in the repo-root AGENTS.md. Per the plugin's Rationale Discipline (portability meta-commentary belongs in commits/docs, not the runtime skill body), remove the false clause rather than expand it. The `:-.` form is kept — it is correct on Claude Code and harmless elsewhere — with a short, accurate note that it only keeps the command syntactically valid where the var is unset. ce-compound and ce-compound-refresh carry the duplicated validate- frontmatter step, so both copies are edited in the same commit per the plugin's duplicate-reference sync rule. --- .../skills/ce-compound-refresh/references/per-action-flows.md | 2 +- plugins/compound-engineering/skills/ce-compound/SKILL.md | 2 +- plugins/compound-engineering/skills/ce-worktree/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md b/plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md index fbd20072..95994068 100644 --- a/plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md +++ b/plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md @@ -62,7 +62,7 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect - The target path and category (same category as the old learning unless the category itself changed) - The relevant contents of the three support files listed above 2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping and YAML-safety rules for array items, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed. -3. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" `** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); on other targets it is unset and the `:-.` fallback yields the bare relative path those harnesses expect. +3. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" `** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); the `:-.` fallback keeps the command valid where it is unset. 4. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information. **When evidence is insufficient:** diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index 87af0560..be5daca4 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -251,7 +251,7 @@ The orchestrating agent (main conversation) performs these steps: 5. Validate YAML frontmatter against `references/schema.yaml`, including the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules) 6. Create directory if needed: `mkdir -p docs/solutions/[category]/` 7. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md` -8. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" `** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); on other targets it is unset and the `:-.` fallback yields the bare relative path those harnesses expect. +8. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" `** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); the `:-.` fallback keeps the command valid where it is unset. When creating a new doc, preserve the section order from `assets/resolution-template.md` unless the user explicitly asks for a different structure. diff --git a/plugins/compound-engineering/skills/ce-worktree/SKILL.md b/plugins/compound-engineering/skills/ce-worktree/SKILL.md index 8c4bf5fe..ff65572c 100644 --- a/plugins/compound-engineering/skills/ce-worktree/SKILL.md +++ b/plugins/compound-engineering/skills/ce-worktree/SKILL.md @@ -15,7 +15,7 @@ Create a worktree under `.worktrees/` with branch-specific setup that `g ## Creating a worktree -Invoke the bundled script via the runtime Bash tool. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory across both marketplace-cached installs and `claude --plugin-dir` local development; the runtime Bash tool's CWD is the user's project, not the skill directory, so a bare `bash scripts/worktree-manager.sh` fails. On other targets (Codex, Gemini, Pi, etc.) `${CLAUDE_SKILL_DIR}` is unset and the `:-.` fallback yields the bare relative path those harnesses expect. +Invoke the bundled script via the runtime Bash tool. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory across both marketplace-cached installs and `claude --plugin-dir` local development; the runtime Bash tool's CWD is the user's project, not the skill directory, so a bare `bash scripts/worktree-manager.sh` fails. The `:-.` fallback keeps the command syntactically valid where `${CLAUDE_SKILL_DIR}` is unset. ```bash bash "${CLAUDE_SKILL_DIR:-.}/scripts/worktree-manager.sh" create [from-branch]