Three fenced blocks were labelled bash but hold JavaScript: the Frontend
and Backend measurement examples in performance-optimization (web-vitals
imports, console.time) and the measurement block in the performance
checklist, which mixed npx commands with web-vitals code in one shell
fence. An agent reading a bash block can try to run it in a shell, and
`#` is not a JavaScript comment. Relabel the two skill blocks as
javascript with // comments, and split the checklist block into a bash
fence for the npx commands and a javascript fence for the code. Content
is unchanged line for line.
The Codex manifest's longDescription still said 24 workflows; the pack
has had 25 skills since constraint-driven-development landed. Say 25.
Found by scanning every fenced block in the repo by declared language;
these were the only mislabels.
- Node 24, the version CI pins, not Node 20+.
- Drop "in the order the workflow runs it": the checks are spread across
jobs and run in a different order. Group them by what they cover.
- Drop "this is the full set": name the two jobs that need the Claude
Code CLI (claude plugin validate, and the marketplace install) and say
when to run them.
- Restore the rule that editing skills/using-agent-skills/SKILL.md
requires the session-start hook test, since the script embeds the file.
- List the three hook test commands; `bash hooks/*-test.sh` runs only the
first match and passes the others as arguments.
- Remove the "new validator ships with a test file and a CI step" line;
it is policy, not a doc sync, and goes in its own PR.
docs/developer-onboarding.md promises that everything CI runs can be run
locally, then lists three validators, the eval runner and one hook test.
CI runs six validators, seven unit-test files and three hook suites on
three operating systems, so a contributor following the doc can fail
several steps they never ran. The Tier 1 row in evals/README.md names
two validators where there are five, and Tier 2 omits the rank-1 floor.
List every workflow command in the onboarding block in workflow order,
note the PowerShell glob caveat, state the cross-platform leg, name the
workflow file as the source of truth, and align Path 3 and the pre-PR
checklist. Update both tier rows in evals/README.md. CLAUDE.md's stale
line is left for later because #548 edits that file.
Every command in the new block was run from this branch and passes, and
every command in the workflow appears in the block.
Two open threads, one doc. #652 reads the Cursor guide as wrong because
this repository has no .cursor/ directory; the guide means the user's
project but never says so. #494 reports Cursor failing with "An
unexpected error occurred on our servers" when a skill is attached to a
prompt with /, after which every message in that chat fails; the
maintainer confirmed it is Cursor-side, named referencing the skill by
name as the workaround, and said the setup doc should carry a note.
Add one sentence after the intro saying every .cursor/ path is in the
reader's project and this repo ships none, linking to the install step.
Add a troubleshooting row for the attach error with the workaround and a
pointer to #494, which stays open as a known host issue. Add the
project-not-repo clause to the README's Cursor entry.
Closes#652. Refs #494.
#542 reports following docs/copilot-setup.md and finding no /spec, /plan,
/build or /test. The doc already says the wrappers are Claude Code
commands, but in the middle of a paragraph that a reader scanning for
install steps walks past; the reporter did. The maintainer's answer on
the issue was that the doc should make this explicit.
Add a callout right after the intro that names the commands, says they
are expected to be absent, and points to the skill-name mapping and the
optional aliases. Add a lead-in to the troubleshooting list that rules
out the expected case before the real diagnostics. Add one sentence to
the README's Copilot entry so the expectation is set before the doc is
opened.
Closes#542
The fx setup guide (#507) was closed under the new host-guide bar, which
gives hosts no maintainer has run one line in docs/other-hosts.md. Add
that line with the corrected install command from the guide: copy the
skills into .fx/skills/, fx's native project root, discovered from 0.0.5
on. No affiliation with fx or Vercel Labs.
Refs #504, #507
The smaller version asked for when #610 was closed. docs/agents.md states
three rules for agents/<name>.md — the same frontmatter format as a skill
with name equal to the file stem (the name is the subagent_type commands
spawn) and a description, and a closing Composition block — and no
validator checked them.
Add lintPersonaContent to scripts/lib/skill-lint.js, reusing the existing
frontmatter parsing and YAML-validity rules, and have validate-skills.js
walk agents/*.md after the skills, skipping an index README.md. Headings
are read from fence-stripped content so an example block after
Composition does not count as a later section. No spawn-reference
scanning, no listing-table checks, no new script, no workflow change.
All four personas pass: 25 skills and 4 personas checked, 0 errors.
docs/advanced-per-agent-configuration.md says vendor and runtime fields
such as model, tools, max_turns and context must not appear at the top
level of a SKILL.md: hosts do not promise to ignore unknown keys and a
strict client can reject the file. Nothing enforced it; a skill with
model: at the top level passed CI.
Add SPEC_FRONTMATTER_KEYS (name, description, license, compatibility,
metadata, allowed-tools) and an error for any other column-zero key,
naming the key and pointing at the guide. Nested lines under metadata and
list items are children of a spec key and are left alone. Export
topLevelFrontmatterKeys for direct tests. validate-commands.js shares only
frontmatterYamlErrors, so command frontmatter is unaffected.
All 25 skills use only name and description, so the rule fires on nothing
today and follows the #571 pattern of errors for rules nothing violates.
The self-exemption test now expects two errors, since exempt: is also not
a spec key.
docs/advanced-per-agent-configuration.md calls itself the canonical
reference for keeping SKILL.md frontmatter portable, yet nothing in the
repository links to it. Add the frontmatter rule it states to the anatomy
doc's Frontmatter section, and point at it from the README contributing
paragraph and CONTRIBUTING's frontmatter step, so contributors meet the
rule where they read the format.
validate-artifact-paths.js exists to stop the #93 class of drift, where a
producer moves SPEC.md or tasks/plan.md and a consumer keeps reading the
old path. It guarded only the .claude/commands copies plus two skills and
two docs. The same commands ship twice more — .gemini/commands/*.toml and
the root commands/*.toml — each with its own prompt body that names the
same artifacts, and validate-commands.js deliberately compares only
descriptions, so a drift on either TOML surface merged green while the
Claude Code copy stayed canonical. docs/copilot-setup.md was also unguarded
although its prompt-file aliases spell the artifact paths out for users.
Add the six TOML producers and consumers and the Copilot doc to
GUARDED_FILES, grouped by surface. Rule, allowlist and regex are unchanged.
Four new tests cover a Gemini producer drifting alone, a root TOML consumer
drifting alone, all three surfaces agreeing, and the Copilot doc. All seven
newly guarded files already use canonical paths: 14 files checked, 0 errors.
Add platform coverage for all six Node test suites, validators, and routing checks while preserving existing Ubuntu check names. Require both matrix jobs before plugin validation and retain failures from each platform.
Reuse the skill linter's fence parser so inline backticks cannot hide broken references and trailing text cannot close a code fence. Cover both failures with LF and CRLF regression cases, preserving diagnostic line numbers.
The round-trip test added in this PR failed on ubuntu-latest while passing
on macOS: after Read → Stop, a protected block containing a backslash came
back altered (byte 109, line 3 of the fixture).
expand_file rebuilds each line with `${line//$placeholder/$block_content}`.
Bash 5.2 enables patsub_replacement by default, which makes the replacement
side of that expansion special: an unquoted `&` expands to the matched text
and backslashes are consumed. Block content is raw code and routinely
contains `&&` and backslashes, so on any bash 5.2 host every protected block
with either character was corrupted when it was expanded back. Bash 3.2 on
macOS has no such option, which is why local runs never showed it.
Turn the option off at the top of the hook; older bashes reject the shopt,
so the error is ignored there. Extend the byte-fidelity fixture with `&&`
and `&` so the ampersand case is guarded alongside the backslash one.
Wire the two regression suites into the workflow as a test-hooks job
so the coverage actually guards the hooks, per review. Deliberately
excludes session-start-test.sh: it currently asserts the pre-#474
payload shape and fails against the envelope the hook now emits;
PR #510 updates that test and can wire it in when it lands.
stripFencedCodeBlocks matched fences with a single whole-document regex that
only recognised a column-zero backtick fence closed by a run of exactly the
same length. Three CommonMark-legal forms slipped through and their contents
were linted as prose: tilde fences, fences indented one to three spaces, and
closing fences longer than their opener. This is live on main today —
spec-driven-development's list-nested examples use indented fences, so the
linter has been reading their contents as skill text.
Replace the regex with a line scanner that tracks the opener's marker and
length, closes only on a same-marker run at least as long, treats an
unterminated fence as running to end of file (so sections after it fail
loud), and follows the CommonMark rule that a backtick fence's info string
may not contain backticks. Stripped lines become empty lines so positions
are preserved.
Add unit coverage for each form plus CRLF input, and run
scripts/lib/skill-lint-test.js in CI — it was the only test file the
workflow did not execute.
Revives the approach from #444 by @ujjwalks, which was approved and then
closed after a rebase conflict.
Closes#437
Eleven positive trigger prompts ranked their skill #2-#3 because the
descriptions lacked vocabulary users actually say (follow-up to #351):
- debugging-and-error-recovery: regression vocabulary (worked yesterday,
what broke)
- documentation-and-adrs: 'document an architecture decision', design
reasoning ('documentation' and 'document' don't stem together)
- doubt-driven-development: cross-examining assumptions, stress-testing
a plan for hidden failure modes, high-stakes changes
- git-workflow-and-versioning: splitting a messy working tree into
atomic commits
- incremental-implementation: thin/verifiable slices, next task from a
plan, feature flags
- shipping-and-launch: what needs to be in place before shipping
- spec-driven-development: PRD, objectives and scope
- test-driven-development: red-green-refactor
- using-agent-skills: deciding which workflow applies to the work
- source-driven-development: verify against the official docs
('docs'/'documentation' don't stem together)
Trigger rank-1 rate: 86% -> 100% (76/76), no new collision warnings.
CI floor raised from 80 to 95 per the ratchet policy; README baseline
updated and the stale #351 tracking sentence rephrased as guidance.
A step that exists because one model gets a specific call wrong
constrains agents that would have solved the task directly and spends
turns stronger models need for the actual work — cross-model transfer
measurements (WikiSkill, arXiv:2608.27454) show such skills can leave
a stronger model worse off than no skill at all.
Add 'Write the Procedure, Not the Workaround' to skill-anatomy: the
rule (no step justified only by naming a model, version, or one
agent's private tool name), the two smells (over-specified mechanics,
fragmented diagnostics), a model-neutral writing principle, and a
matching pre-flight line in CONTRIBUTING.
Affected agy 1.1.x releases report the 8 legacy command TOMLs as
converted to skills, but the converted wrappers never appear in the
slash-command or skill catalog — plugin validate passing confirms the
files are well formed, not that /build and the other wrappers exist.
Replace the slash-command table with a wrapper-to-direct-invocation
map (/agent-skills:<skill-name>, /agents for the webperf persona),
note the wrapper-only behaviors that are unavailable (/build auto
orchestration, /ship persona fan-out), warn against the YAML
frontmatter workaround that breaks Gemini CLI's TOML parser, and add
a post-install verification step. Align the README blurb with the
same guidance.
When /plan runs for new work while tasks/plan.md and tasks/todo.md
still hold unchecked tasks, the agent silently replaces them,
destroying the in-flight plan's state (reported in #518).
Add a convention-neutral guard: replanning the same work updates in
place; different work stops and asks the user before touching the
existing files. Mirror the rule for external task list targets (no
bulk-closing another plan's items), and add matching Rationalization,
Red Flag, and Verification entries plus the guard line in the /plan
command.
Deliberately does not introduce a parallel-lane layout — that
convention decision is being held open in #518; this fixes only the
data-loss half.
The task list destination was hardcoded as tasks/todo.md in five places
across planning-and-task-breakdown, plus once more in
spec-driven-development's Phase 2 output convention. Projects tracking
tasks in an external tracker (bd/beads, Jira, Linear, GitHub Issues) had
to hand-edit every reference in a local fork.
Define the target once in a Task List Target section: default remains
the tasks/todo.md markdown checklist (downstream /build behavior is
unchanged), and projects can designate an external tracker via their
agent rules. All other references now defer to that single definition,
and spec-driven-development points at it instead of restating the path.
Implements the v1 scope agreed in #431: when one requirement bundles
several independently testable capabilities, spec-driven-development now
runs a bounded front-step before Specify — detect multi-capability scope,
propose a capability map (stable module ids, one-way dependency direction,
build order), gate it on human approval, then recurse the gated workflow
per module in dependency order.
Kept deliberately small per the maintainer's scoping:
- detection + module map + stable identity only; no per-module artifact
tree — module specs reuse the root-level SPEC-<id>.md naming so the
layout follows the delta-spec direction in #383 rather than leading it
- the simple path is preserved: single-capability requests skip Phase 0
entirely, and the section says so first
- non-goals held: no PM framework, no forced hierarchy on small features
Also:
- description gains the decomposition vocabulary so realistic asks route
here (both new positive triggers rank #1)
- /spec command wrappers (.claude, commands/, .gemini) gain one matching
step, kept in parity
- eval case: +2 positive triggers, +1 owner-negative guarding the
planning-and-task-breakdown boundary, +1 execution eval backed by a new
multi-capability fixture (portal-brief.md)
Verification: validate-skills 24/24, validate-commands 8/8, run-evals
127 checks 0 errors 0 warnings, rank-1 86% (67/78) over floor 80,
behavioral dry-run resolves both spec evals.
The session-start hook emitted {"priority", "message"} JSON on all three
of its output paths. Codex CLI validates SessionStart hook output and
fails the hook on that shape ('hook returned invalid session start JSON
output', #465); the documented contract for both Codex and Claude Code is
{"hookSpecificOutput": {"hookEventName": "SessionStart",
"additionalContext": "..."}}
Switch all three paths (meta-skill injection, jq-missing fallback,
meta-skill-missing fallback) to that envelope. Verified each path emits
valid JSON of the new shape: happy path via jq shape assertion, jq-missing
via PATH='' run, meta-skill-missing via a copy outside the repo.
'Native dependency audit' collides with the established meaning of
native dependencies (compiled modules); use the same unambiguous
phrasing as the shipping-and-launch checkbox in this PR.
Follow-up to #419, addressing the remaining normative npm-family
commands federicobartoli's grep on #404 identified:
- incremental-implementation: the four increment-checklist exit criteria
and the example prompt now use the repository's own test/build/
typecheck/lint commands, pointing at the TDD skill's Discover the
Stack First section
- planning-and-task-breakdown: task-template verification lines use the
template's placeholder style instead of hardcoded npm commands
- shipping-and-launch: the security checkbox names the ecosystem's
dependency audit rather than npm audit alone
- debugging-and-error-recovery: the diagnosis/bisect/verify command
blocks are labeled as npm examples with substitution notes
- references/security-checklist.md: OWASP row 6 generalizes npm audit
to the native dependency audit
- security-and-hardening needed no change: its SKILL.md was already
neutralized (detected-package-manager wording)
Ride-along: pins the below-zero debit behavior (ValueError) in TDD eval
case 3, per nucliweb's non-blocking review note on #419.
- SKILL.md gains a 'Discover the Stack First' step: identify the
language, build system, checked-in wrappers, test framework, and
documented commands before choosing any test command, and run the
repository's own focused/full-suite commands throughout the loop
- verification checklist no longer hardcodes 'npm test'; red flag added
for reaching for a default test command without checking the repo
- references/testing-patterns.md relabeled in place as JavaScript/
TypeScript examples illustrating the universal principles (no
relocation, per the #361/#236 sequencing agreed in the issue)
- new behavioral eval: a Python/unittest fixture verifying the skill
adapts to non-npm repository tooling
ayobamiseun