- 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
Drop the GitHub-org .github repo and open-PR scanning: a reusable
skill must not require network access or assume a particular forge,
and unmerged PRs are proposals, not established conventions. Detect
the convention from repository context only (existing ADRs, project
instructions, ADR tooling config) and surface conflicting evidence
instead of silently adding another scheme.
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
The ADR Template section hard-codes docs/decisions/ Markdown with its
own numbering. Real projects often already have a convention in a
different location or format (e.g. Documentation/Decisions/*.rst, MADR,
adr-tools) — sometimes introduced in a not-yet-merged PR or the org
.github repo. Adds a 'Match the existing convention first' step:
detect location/format, numbering, and headings (scanning open PRs and
the org .github repo) and continue them; fall back to the default only
when none exists.
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Extends the existing adopt gate with the missing upgrade workflow: read the
changelog over the version number, one package per change, verify via tests,
review the lockfile/transitive diff. Cross-links security-and-hardening for
npm audit and supply-chain rather than duplicating it.
Adds a Database Schema Migrations section to deprecation-and-migration covering
expand/contract, dual-write + batched backfill, additive-first/destructive-last,
tested down paths, and non-blocking index builds. References incremental-implementation
for slicing; reuses the skill's existing Feature Flag Migration pattern.
The /plan command specifies saving the plan to tasks/plan.md and
tasks/todo.md, but the planning-and-task-breakdown skill (the canonical
source) had no file path instructions. When spec-driven-development
transitions to Plan phase, it references the skill directly, bypassing
the /plan command, causing plans to be written to the wrong location.
- Add Output Files section to planning-and-task-breakdown with explicit
tasks/plan.md and tasks/todo.md paths
- Add path instruction to Step 1 (Enter Plan Mode)
- Add Output convention note to spec-driven-development Phase 2
git-workflow-and-versioning had versioning in its name but no versioning content.
Adds a Release & Versioning section: semver as a consumer contract, tag-as-source-
of-truth, and human-readable changelogs written with the change. Cross-links
api-and-interface-design, deprecation-and-migration, and shipping-and-launch.
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.
Address review feedback on the Plan and Tasks delegation pointers. Both
pointers now state that planning-and-task-breakdown takes precedence if
the inline summaries ever diverge, removing the drift ambiguity. Unify
both pointers to the blockquote form for consistency.
Test Plugin Installation / Validate skill content (push) Has been cancelled
Test Plugin Installation / Validate command parity and description sync (push) Has been cancelled
Test Plugin Installation / Validate plugin structure (push) Has been cancelled
Test Plugin Installation / Test plugin installation (push) Has been cancelled
The file-size paragraph used "1000 total lines" adjacent to the "~1000
lines changed" diff threshold, which let readers conflate "diff too
large" with "file too large". Spell out the distinction inline and
reframe total file length as an inspection signal rather than a hard cap.
Addresses @federicobartoli's review feedback on #304.
The /mnt/skills/user/ prefix was an artefact of the Anthropic workbench
environment where skills were originally developed. These paths do not
exist in a standard git clone.
Replace all three occurrences with the correct repo-relative path:
/mnt/skills/user/{name}/scripts/{script}.sh -> skills/{name}/scripts/{script}.sh
The script referenced in idea-refine/SKILL.md (idea-refine.sh) already
exists at skills/idea-refine/scripts/idea-refine.sh.
Fixes#136
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Per review: the paragraph said both "Required-by-default" and "flag and
suggest by default", which are opposite stances. Collapse to a single
stance — propose the simpler design for each signal, escalate to Required
only when the change actively makes structure worse.
Our five-axis review is broad but treats structural maintainability passively
("could this be fewer lines?"). This adds the depth a great reviewer brings to
structure, folded into the existing axes/process rather than a separate mode:
- Architecture axis: "reduce, don't relocate" (does the refactor delete
complexity or just move it?), canonical-layer/helper-reuse discipline, and
explicit type-boundary checks.
- Readability axis: treat new conditionals bolted onto unrelated flows and
repeated same-shape conditionals as missing-abstraction signals, not nits.
- New "Structural Remedies" section: name the restructuring move, not just the
problem (typed dispatcher, collapse duplicate branches, separate orchestration
from logic, reuse canonical helper, etc.).
- Change Sizing: gate total file size, not just diff size (~1000-line smell).
- Step 4: "lead with what matters" finding-prioritization rule.
- Verification: presumptive blockers, calibrated to our approval philosophy
(surface and propose the simpler design; block only when structure gets worse).
- Matching Common Rationalizations and Red Flags.
Purely additive; validator passes (24 skills, 0 errors).
The Plan and Tasks phases of spec-driven-development restated planning
mechanics that the dedicated planning-and-task-breakdown skill already owns.
Add a one-line delegation pointer to each phase naming that skill as the
canonical source for dependency-graph mapping, vertical slicing, task sizing,
and ordering, mirroring how the Implement phase already delegates to
incremental-implementation and test-driven-development. The inline bullets and
task template stay as a lightweight quick reference.
The "Categorize Findings" table defines Critical, Required (no prefix),
Optional/Consider, Nit, and FYI. Two other spots used labels outside that
set: the Multi-Model Review prompt said "Critical, Important, or Suggestion"
and the Verification checklist referenced "All Important issues". "Important"
and "Suggestion" are never defined, so an agent following the skill can't map
them to a severity. Align both to the taxonomy.
Resolve README.md Reference Checklists table conflict by keeping both new
rows: observability-checklist (this PR) and orchestration-patterns (#290,
already on main).
The Stop-the-Line Rule and Triage Checklist each have exactly 6 steps
(1-6). "Steps 4-10" referenced steps that never existed — this was an
original error present since the file's first commit, not a leftover
from a previous 10-step structure. Correct the range to match the
actual 6-step content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Every other shell script in the repo is 100755 (all six hooks/*.sh),
but skills/idea-refine/scripts/idea-refine.sh was committed 100644.
It has a #!/bin/bash shebang and is invoked as a runnable helper from
its SKILL.md. AGENTS.md also documents scripts/ as 'Required:
executable scripts'. Set the exec bit for consistency.
The recommended config attached the agent to the user's running Chrome
via --autoConnect ('recommended for most users'), giving it every open
window of the default profile: logged-in email, banking, GitHub
sessions. Combined with a page containing injected instructions, the
agent effectively holds the user's authenticated browser. The skill's
own Security Boundaries section treats browser content as untrusted,
but profile isolation is the layer that bounds the damage when those
rules fail.
Changes:
- Recommended config now uses --isolated (temporary profile, wiped on
close); documents that the server's default is already a dedicated
profile separate from the user's browser
- --autoConnect described accurately (Chrome 144+, requires enabling
remote debugging) and demoted to the logged-in-state use case
- New 'Profile Isolation' subsection in Security Boundaries with
escalation rules: dedicated profile -> test-only profile -> real
profile only with unrelated tabs closed
- Red flag added for attaching to the daily profile for localhost tests
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.
Rename Core Process to Process, and move observability next to
implementation in the lifecycle sequence so it no longer contradicts
the skill's own instrument-as-you-build rule.
Fills the gap between debugging-and-error-recovery (dev-time) and
shipping-and-launch (launch-day monitoring): how to instrument code
as it's built so production behavior is visible and diagnosable.
Covers structured logging with correlation IDs, RED/USE metrics with
cardinality guidance, OpenTelemetry tracing, and symptom-based
alerting with runbooks. Follows the standard skill anatomy (Overview,
When to Use, Process, Rationalizations, Red Flags, Verification).
Registered in README tables/structure, CLAUDE.md phases, and the
using-agent-skills discovery tree (hooks/session-start-test.sh passes).
Package name was wrong (@anthropic/chrome-devtools-mcp does not exist).
Adds -y to skip npx confirmation prompt and --autoConnect as the
recommended default to connect automatically to a running Chrome instance.
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.
Strengthen the security-and-hardening skill with the highest-value gaps
without changing its secure-coding-for-builders scope:
- Threat Model First: a STRIDE/trust-boundary process step up front, so the
skill drives proactive design (OWASP A04) instead of only listing controls
- SSRF prevention (§7): allowlist + private-IP-block pattern; the one OWASP
Top 10 item previously listed but never exemplified
- Supply-chain hygiene: lockfile/npm ci, postinstall and typosquat risks (A06)
- Securing AI/LLM features: prompt injection, untrusted model output, secrets
in prompts, excessive agency, unbounded consumption (OWASP LLM Top 10 2025)
- Secret-leak response: rotate, don't just rewrite history
- Threaded the new areas into the review checklist, rationalizations,
red flags, and verification
Skill grows 349 -> 448 lines (+28%). Validator passes.
A bare confidence percentage gives no signal about what's blocking clarity.
When confidence is below ~70%, the skill now requires a one-line reason on
the same CONFIDENCE line so the user knows exactly what the interview still
needs to surface.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Test Plugin Installation / Validate plugin structure (push) Has been cancelled
Test Plugin Installation / Test plugin installation (push) Has been cancelled
- Disambiguate the using-agent-skills flowchart so interview-me and
idea-refine no longer match the same condition top-to-bottom
("Don't know what you want yet?" vs "Have a rough concept, need
variants?").
- Add "grill me" to interview-me's frontmatter description and the
When to Use trigger list (it was already mentioned in README).
- Reorder sections: Example and Interaction with Other Skills now
precede Common Rationalizations and Red Flags, so the persuasive
example lands before the rationalization table.
Per review by @nucliweb on #164.
idea-refine: rewrite the description to follow the repository's
documented "Use when..." trigger convention (AGENTS.md). The previous
description was 135 characters, redundant, and used the skill name
itself as the only trigger phrase, making it the only skill not aligned
with how the other 21 skills self-describe.
browser-testing-with-devtools: surface the Chrome DevTools MCP
dependency at the top of the description and explicitly note the
requirement, so agents that route by MCP availability can detect it
without parsing the body.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds interview-me, a skill that sits upstream of every other
Define-phase skill. Trigger: an underspecified ask, or the user
explicitly invoking the skill ("interview me", "are we sure?",
"stress-test my thinking").
The gap it fills: idea-refine generates variations from a raw idea,
spec-driven-development writes requirements down once you know them,
and doubt-driven-development stress-tests a plan after you've drafted
one. None of those cover the moment before — when the user has said
"build me X" and X is the conventional answer rather than what they
actually want. This skill is the structured interview that surfaces
the gap before any plan, spec, or code exists.
Distinctive mechanics:
- Confidence numbers as forcing function (Step 1 commits to 0-100%)
- Q + GUESS format: every question carries the agent's hypothesis
- One question at a time, never batched
- Checkable stop condition: "Can I predict the user's reaction to the
next three questions I would ask?"
- Six-line restate template ending in explicit yes
- Names the four bad yeses ("whatever you think", "sounds good",
"sure let's go", silence) with specific re-prompts
Registers the skill in:
- CLAUDE.md (Define phase, also adding idea-refine which was missing)
- README.md (skills table, count, project tree)
- skills/using-agent-skills/SKILL.md (flowchart, lifecycle sequence,
quick reference table)
Folds in the safety and consistency findings surfaced by running
the skill against itself in two cycles (single-model adversarial
review + cross-model verification via Codex).
Cross-model escalation is now offered in every interactive cycle,
and the CLI invocation path uses a read-only sandbox with prompts
piped through stdin to neutralize shell-escaping and prompt-injection
risks (verified against Codex 0.128.0 and Gemini 0.41.2 locally).
Internal consistency fixes from the adversarial self-review: the
adversarial prompt explicitly overrides persona templates; the
persona roster is referenced rather than duplicated; the Step 2
'Claim' bullet is renamed Assertion to disambiguate from the Step 1
CLAIM block; the manual fallback in Loading Constraints is labeled
as a degraded last-resort path; the forward reference to Step 3 is
anchored; the Verification checklist no longer contains an item not
derivable from the Process; and using-agent-skills's Lifecycle
Sequence now includes the skill at position 7.
Codifies adversarial fresh-context review as an in-flight development
posture, distinct from /review (post-hoc PR-level verdict). Every
non-trivial decision passes through a 5-step cycle (CLAIM → EXTRACT →
DOUBT → RECONCILE → STOP) before standing.
Cross-model escalation is described as a contract, not as hardcoded
CLI invocations — the skill instructs the agent to ask the user which
external tool to use and how, since CLI syntax (Gemini, Codex, etc.)
changes and varies by environment.
Updates README skill listing (count, Build table, project tree),
CLAUDE.md Skills by Phase, and using-agent-skills flowchart + Quick
Reference for discoverability parity with the existing skills.
ayobamiseun