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.
Applies the review suggestions on #580, which carry nucliweb's three points:
the condensed index bullet lost the partial, trigram/full-text and expression
index qualifiers, it no longer said a bad rows= estimate means ANALYZE, and
the caching bullet dropped the staleness window the Red Flags still audit.
Co-authored-by: Joan León <nucliweb@users.noreply.github.com>
SKILL.md loaded ~4.3k tokens on every activation at 496 lines, just
under the 500-line budget in docs/skill-anatomy.md, with Step 3 ("Fix
Common Anti-Patterns") alone at ~1,800 words of worked TypeScript, SQL,
HTML, and TSX that an agent only needs once Step 2 has named the
bottleneck.
Move Step 3's body verbatim into references/optimization-patterns.md
(same convention as constraint-driven-development/references/floor-guard.md
and #579), promoting its #### headings to ## so the file stands alone.
SKILL.md keeps the workflow and replaces Step 3 with a condensed list:
each anti-pattern's rule and recognizable signature, with a deep link to
its worked fix. Every rule the Red Flags, Rationalizations, and
Verification sections rely on (read the plan before indexing, cache key
includes the viewer, bigger pool is not faster, neutral is a revert) is
still stated in SKILL.md.
Lines 1-120 (frontmatter through the Step 2 tables) and Step 4 onward
are byte-identical to before, so the two hunks in #492 still apply.
SKILL.md: 496 -> 267 lines, 3314 -> 2488 words (~-25% 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>
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
Every SKILL.md linked the shared checklists as `references/<file>.md`, a
path relative to the skill's own directory. Those files live in the repo
root `references/`, two levels up, so all 18 links across 11 skills
resolved to paths that do not exist -- in the repo and in every
plugin-install layout (~/.claude/plugins/cache/..., ~/.codex/...).
An agent following the guidance -- using-agent-skills pointing at the
Definition of Done, for example -- hit a file-not-found on every one.
Rewrite the 18 links to `../../references/<file>.md`, which resolves
correctly from `skills/<name>/`. Text-only; no structure or tone changed.
Verified: all 18 links resolve; hooks/session-start-test.sh passes
(required by CONTRIBUTING.md when touching using-agent-skills/SKILL.md);
validate-skills, validate-versions, validate-commands and
validate-artifact-paths all pass.
Refs #468
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The optimization workflow lists five steps but only documents three;
VERIFY has no section of its own. Add it: re-measure under baseline
conditions, change one thing at a time, beat run-to-run variance, and
keep only what pays for itself. Neutral and test-breaking results revert.
Also log every attempt, including the reverted ones, so a discarded idea
does not get re-run later.
Add the corresponding Common Rationalizations, Red Flags, and
Verification entries.
- 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.
Helps determine what to measure first based on the symptom: slow first
load, sluggish interactions, navigation delays, or backend issues. Each
branch points to a specific profiling action.
Review phase skills covering OWASP Top 10 prevention, input
validation, Core Web Vitals, and measure-before-optimize discipline.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ayobamiseun