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.
SKILL.md loaded ~5.3k tokens on every activation, 30% of it inline
TypeScript examples that an agent only needs when it reaches that code.
docs/skill-anatomy.md already asks for SKILL.md under 500 lines with
reference material in supporting files; this skill was at 524.
Move the OWASP prevention patterns, input-validation and upload code,
SSRF check, destructive-path discussion, dependency-audit decision tree,
rate-limiting and secrets snippets, data-classification table, and LLM
output example verbatim into references/hardening-patterns.md (same
convention as constraint-driven-development/references/floor-guard.md).
SKILL.md keeps the workflow: threat model, three-tier boundaries, and a
condensed "Hardening Controls" section stating each rule with a deep link
to its pattern. Frontmatter, Process, Rationalizations, Red Flags, and
Verification are byte-identical to before.
The skill's own review checklist duplicated references/security-checklist.md;
replace it with a pointer and add its three privacy items to the shared
checklist so nothing is lost.
SKILL.md: 524 -> 216 lines, 4096 -> 2449 words (~-40% tokens per load).
Routing unchanged: run-evals rank-1 stays 100%, no description edits.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
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
'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
Address review feedback on #317:
- Wire the Definition of Done into incremental-implementation as a final
per-task gate, so the doc's intro list and the See Also links agree.
- Cross-link the Quality and Ship-readiness items to the skills that own
their depth (code-review-and-quality, code-simplification,
security-and-hardening, observability-and-instrumentation,
shipping-and-launch).
Introduce a project-wide Definition of Done as a standing bar every change clears before it counts as done, distinct from the per-task acceptance criteria the project already covers.
The concept existed implicitly across the project (per-task acceptance criteria, per-skill Verification sections, the pre-launch checklist) but was never named or unified. This adds a single reusable checklist and wires it in without duplicating existing content:
- references/definition-of-done.md: the standing checklist, grouped into Correctness, Quality, Integration, Documentation, and Ship-readiness, plus a table contrasting Definition of Done with acceptance criteria.
- using-agent-skills: linked from Core Operating Behavior #6 (Verify, Don't Assume), the bar that applies across all skills.
- planning-and-task-breakdown: See Also note clarifying acceptance criteria sit on top of the standing bar.
- shipping-and-launch: See Also pointer as the floor beneath the deploy-specific gates.
- README: entry in the Reference Checklists table.
Follow-up suggested in #223 review: folds in the useful half of #61
(the observability checklist) as this skill's quick-reference
companion, mirroring the security-and-hardening / security-checklist
pairing.
Aligned with the merged skill's framing: on-call questions first,
RED/USE metrics, cardinality rules, symptom-based alerting with the
page/ticket two-severity rule, telemetry verification, and a
pre-launch gate. Linked from the skill's Verification section and
registered in the README references table and CLAUDE.md.
Per federicobartoli's note on #219: the table was headed "Top 10" but
listed only 8. Add the two missing entries (LLM04 Data and Model Poisoning,
LLM09 Misinformation) so the heading matches the contents.
Per nucliweb's review:
- Resolve OWASP numbering inconsistency: rename the prevention section to
"OWASP Top 10 Prevention Patterns" and drop the per-item numbers so it no
longer implies a ranking that conflicts with the 2021 quick-reference table.
- Harden the SSRF example against DNS rebinding/TOCTOU: resolve all records
and reject if any is non-unicast, plus a caveat that fetch re-resolves and
pointers to request-filtering-agent / ssrf-req-filter for high-risk surfaces.
- Add LLM08 (Vector and Embedding Weaknesses) to the LLM section and the
reference table, covering per-tenant embedding isolation and poisoned docs.
- Promote "Threat Model First" to a "## Process" header per the repo's skill
anatomy convention.
- Make the LLM "GOOD" example parse defensively (JSON.parse + schema in a
try/catch) so it models handling untrusted output end to end.
The previous text implied personas behave identically as subagents and
teammates. Per the Agent Teams docs, the skills and mcpServers
frontmatter fields in a subagent definition are not applied when the
definition runs as a teammate — teammates load those from project and
user settings instead.
Adds a qualifier so persona authors don't assume a skills: [...] block
will load in both modes. Flagged in review.
Per the Agent Teams docs, a persona body is appended to the teammate's
system prompt as additional instructions — not a replacement. The prior
wording implied the persona owned the whole prompt, which would mislead
a persona author about what coordination instructions they inherit from
the lead (SendMessage, task-list tools, etc.).
Fixes the same inaccuracy in two locations (agents/README.md and
references/orchestration-patterns.md). Flagged in review.
Walk through a realistic scenario (intermittent 30-second checkout hang
with four plausible root causes) where Agent Teams beats /ship's subagent
fan-out: teammates can challenge each other's hypotheses directly via
inter-teammate messaging, which subagents cannot do.
Includes the one-time CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 setup, a
copy-paste trigger prompt that reuses the existing personas as teammate
types, an explicit anti-pattern warning against wrapping the workflow as
a /debug slash command (which would lose the inter-teammate messaging),
and a 'when not to use Agent Teams' decision rule.
Verify the orchestration design against the official Claude Code docs and
make the platform mapping explicit:
- /ship now names the Agent tool and the subagent_type field directly,
with a fallback note for harnesses that lack an Agent tool.
- AGENTS.md notes that personas work as both subagents and Agent Teams
teammates, and lists the unsupported plugin frontmatter fields.
- agents/README.md gains a Claude Code interop section and notes that
rule #2 is also a hard platform constraint.
- references/orchestration-patterns.md gains a Claude Code compatibility
appendix covering plugin paths, the subagents-vs-teams comparison, the
built-in Explore/Plan/general-purpose subagents, and the parallel
Agent tool call requirement. Pattern 5 now points at Explore first.
No behavior changes; documentation only.
Catalog the five endorsed patterns (direct invocation, single-persona
slash command, parallel fan-out with merge, user-driven sequential
pipeline, research isolation) and four anti-patterns (router persona,
persona-calls-persona, sequential paraphrasing orchestrator, deep
persona trees). Includes a decision flow and a gate for when to add
new patterns to the catalog.
Add an INP-specific measurement workflow covering field data via CrUX Vis,
DevTools interaction tracing, and mid-range Android device testing. Extend
the web-vitals snippet with the attribution build to surface inputDelay,
processingDuration, and presentationDelay. Add a checklist item for
deferring non-critical work out of event handlers to avoid delaying
interaction response.
Clarified the requirement for the skip-to-content link to be visible on keyboard focus - as it is mostly beneficial to users that can see the screen (but also others)
- Add width/height to <source> elements for correct aspect-ratio in art direction.
- Use realistic 'sizes' attributes in hero image examples.
- Remove 'decoding=sync' from hero images to avoid blocking the main thread.
- Align TTFB 'good' threshold with web.dev standards (800ms).
- Distinguish synthetic (Lighthouse) vs RUM (web-vitals) measurement approaches,
clarifying when each is appropriate: synthetic for CI regression detection,
RUM to validate real user impact.
- Expand TTFB diagnosis from a single vague hint into a decision tree that breaks
down each component (DNS, TCP/TLS, server processing) with specific next steps.
Mirrors the tree in the skill and adds a dedicated checklist section.
- Fix image optimization example: the previous "GOOD" example applied loading="lazy"
without distinguishing the LCP hero image from below-the-fold images. Hero images
must never be lazy-loaded. New example separates both cases explicitly.
- Add art direction + resolution switching to the hero image example using <picture>
with media queries for mobile/desktop crops and srcset for density variants.
Mobile-first: <img src> fallback points to the mobile version.
Covers AVIF → WebP → JPG format cascade and fetchpriority="high" for LCP.
- Correct the date-fns tree-shaking example: modern bundlers (Vite, webpack 5+)
handle named imports automatically. The "BAD" pattern was not actually bad,
and following it could lead to unnecessary micro-optimizations. Real gains
come from dynamic imports and route-level code splitting, which the example
now illustrates instead.
Update all SKILL.md descriptions to lead with what the skill does
(third person) followed by trigger conditions, per Anthropic's
skill authoring docs. All original trigger conditions preserved.
Update description max chars to match Anthropic spec (1024).
Retain workflow-summary warning in skill-anatomy.md to prevent
agents from following descriptions instead of reading full skills.
Add Table of Contents to reference files longer than 100 lines so
Claude can see the full scope of available information even when
previewing with partial reads.
ayobamiseun