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.
The trust-boundary list names only remote channels, so local values that the
OS hands you — another process's command line or environment, a filename on a
shared volume, a path in a job payload — read as internal. The one rule about
destructive actions (LLM06) governs who may act, not what gets hit: a
confirmed call with a wrongly derived target deletes the root just the same.
A shape check ("absolute, at least one directory deep") proves well-formedness
and gets mistaken for authorization.
SKILL.md gets the extended trust-boundary item, a prose-only "Destructive
Operations on Derived Paths" next to File Upload Safety, and one line each in
the Input checklist, Red Flags and Verification. The worked example lives in
references/security-checklist.md, per skill-anatomy's rule to move detailed
material out of SKILL.md — the file is already over the 500-line budget, so
this keeps the per-activation cost to +11 lines.
Two limits are stated where the snippet is copied from, rather than implied
away: a marker inside the tree is self-attestation until its integrity is
protected and the expected owner comes from authenticated state, and
resolving a path and then operating on the name is a check/use race wherever
an untrusted process can swap an ancestor.
No new directory, frontmatter unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A correlation ID identifies a run, not the code path that started it. When a
scheduler, a replay endpoint and a manual CLI run all reach the same job and
write into one sink, the lines are interchangeable — attributing one falls
back to elimination against external records (scheduler history, process
table, deploy log) that only happen to still exist.
Adds a paragraph plus a short example to "3. Structured logging" — stamp the
entry point where the run starts, next to the correlation ID, and propagate
both across queue metadata and outbound calls — and one line each to Red
Flags, Verification, and references/observability-checklist.md.
The field is `entryPoint` rather than `source`: Elastic Common Schema reserves
`source.*` for network fields (source.ip, source.port, …), so a scalar
`source` collides with that mapping and can get documents rejected.
No new heading, no new directory, frontmatter unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two skills carry core body content whose vocabulary never reached their
descriptions, so Tier-2 trigger routing cannot see it:
- deprecation-and-migration: Expand/Contract database schema migrations
(added in #345) - description now mentions database schema migration,
renaming/dropping a column, expand/contract.
- security-and-hardening: dependency-audit triage and supply-chain hygiene
(hardened in #392, delegated to by code-review-and-quality) - description
now mentions dependency audits, audit-finding triage, supply-chain risk.
Adds four positive trigger cases so the suite can see these gaps.
Measured: baseline 86% (72/84); cases-only 82% (4 hard misses, 'shares no
vocabulary'); cases+fix 86% (76/88), 140 checks, 0 errors, no existing case
loses rank 1.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
Federico's review on #472 noted the floor is the one thing with no de facto
tool, so agents reinvent a check-floor each run. Add references/floor-guard.md
(the Step 6 checks as a diff-scoped reference implementation, exit 0/1/2, with
patterns adaptable per ecosystem) and point Step 6 and the escalation path at
it. Also mark CONSTRAINTS.md as the canonical source of commands over the
package.json wrappers, and document a floor-only first run plus a CI-only
option for machine-wide security tools.
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.
Review feedback from @federicobartoli on #316.
allowed-tools was described as restricting the tool set. Per the Claude
Code docs it is a permission pre-approval: listed tools run without a
prompt for the turn that invokes the skill, the grant clears on the next
message, and nothing leaves the tool pool.
disallowed-tools is the field that actually restricts, so it now carries
the least-privilege guidance. Added the portability caveat that it is a
Claude Code field rather than one of the specification's six, so it fails
packaging if placed in a published SKILL.md.
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
Link the Agent Skills spec, document the optional `agent` companion to
`context: fork`, clarify that commands and skills share frontmatter, and
add #35 to the consolidated Status list.
Address review feedback on #316:
- State explicitly that this supersedes the inline top-level frontmatter approach, so kind/model/temperature/max_turns/tools/context must not appear at the top level of a skill.
- Add a copy-pasteable .gemini/agents/*.md example using thinking_level instead of hardcoded temperature for Gemini 3.x.
- Update Status: #272 and #36 are closed in favor of this approach.
Add a draft reference for per-agent runtime configuration that keeps shared SKILL.md files portable while documenting the vendor-specific controls each agent offers (Claude Code, Gemini CLI, Antigravity) as an opt-in.
Review feedback from @federicobartoli on #521.
The low-selectivity rows read as if indexing a skewed column never
helps. That holds only when querying the dominant value; filtering on
the rare value is exactly the case a partial index serves. Scoped both
the SKILL.md table row and the checklist item.
loadOnce referenced an undeclared Row type. Made it generic so it
typechecks when pasted as-is.
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
#358 broadened the performance-optimization description to cover
"frontend, backend, queries, and databases", but the body's backend
coverage was a single N+1 example, against the full Core Web Vitals
and art-direction treatment on the frontend side. Routing a "slow
query" or "connection pool" prompt here landed on a snippet.
Adds three measure-first patterns inline, each with a "when NOT to":
- Query plans: read EXPLAIN ANALYZE before indexing; composite column
order (equality first, then range/sort); the four cases where an
index does not help; revert an index that did not change the plan.
- Connection pool exhaustion: the distinctive symptom, one pool per
process, why a bigger pool relocates the queue instead of removing
it, and the proxy answer for serverless.
- Caching: layer choice (in-process, shared, edge), key design as a
correctness concern, one invalidation strategy rather than an
accidental mix, and stampede protection.
Deeper material goes to references/performance-checklist.md to keep
SKILL.md readable: read/write patterns, negative caching, request
coalescing, and query-plan, index, pooling and cache checklists.
Closes#378
Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
The persona used Critical/Important/Suggestion while code-review-and-quality
uses Critical/Required/Optional/Nit, so the same finding got labeled differently
depending on which entry point ran the review. Align the persona to the skill's
four-level scheme (the skill is the source of truth) and note the shared
vocabulary to prevent future drift.
Addy Osmani