Unquoted ${CLAUDE_PROJECT_DIR} in SDD-CACHE and SIMPLIFY-IGNORE setup
examples breaks when the project path contains spaces, the same class
of failure fixed for SessionStart in #214.
Co-authored-by: Cursor <cursoragent@cursor.com>
- 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
Gives contributors a short intake path when a skill assumes the wrong
ecosystem or outdated steps, so gaps like #404 reach maintainers via
the repo instead of external channels. Closes the intake-only scope
from #412.
Co-authored-by: Cursor <cursoragent@cursor.com>
The References table pointed orchestration-patterns.md at
context-engineering, but that skill never mentions it. The reference
is actually cited by doubt-driven-development (SKILL.md lines 46 and
229), which documents the "personas don't invoke personas" rule from
references/orchestration-patterns.md.
Test 10 pipes malformed JSON through the real hook, but the hook's jq
guard exits with 'error: missing jq' before parsing on machines without
jq (default Git for Windows, minimal Linux). The suite then reports a
failure unrelated to the contributor's change; tests 1-9 only exercise
the extracted filter_file and keep passing.
Mirror session-start-test.sh, which CONTRIBUTING documents as validating
both the jq and no-jq branches: with jq on PATH keep the existing
bad-JSON warning assertion, without it assert the documented missing-jq
guard message.
Verified on Windows (Git Bash): 21 passed, 0 failed both with jq 1.8.1
on PATH and without jq.
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>
Two heuristic bugs in the section and trigger checks, surfaced in
addyosmani#387 and triaged by @addyosmani and @nucliweb:
Section check: content.includes('## Overview') matches headings inside
fenced code blocks and sub-headings (### Overview) because substring
matching can't distinguish prose from examples. Replace with a
line-anchored regex match against content that has had fenced code
blocks stripped, so only real top-level headings satisfy the check.
Trigger check: 'Do not use when testing' satisfied the DESCRIPTION_TRIGGER
regex because it contains 'use … when'. Add a negation pattern and reject
descriptions where the only trigger match is negated.
Verified: all 24 skills pass (output unchanged — no current skill has
either bug pattern). Crafted edge cases confirm the fixes catch both
issues. Eval suite green, rank-1 rate unchanged at 86%.
Co-authored-by: Cursor <cursoragent@cursor.com>
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>
Issue addyosmani#329 asked why shared checklists live in repo-root
references/ instead of being colocated per skill directory as the
Agent Skills spec suggests. The rationale existed only in a comment:
several skills point at the same checklists, and colocating means
either duplication or a single "owner" skill, both of which drift.
Fold that rationale into skill-anatomy.md as a Shared References
section, including the per-skill install portability tradeoff
(addyosmani#361) and a rule of thumb for supporting file vs shared
reference. Cross-link from Naming Conventions.
Co-authored-by: Cursor <cursoragent@cursor.com>
Per review: the new-skill 'ships as a set' block restated CONTRIBUTING's
frontmatter, anatomy, and eval-count rules instead of pointing at them,
which is the 'don't duplicate, reference' rule this guide champions. Keep
the shape (SKILL.md + eval case + optional scripts) and defer the exact
requirements to CONTRIBUTING.md and skill-anatomy.md so they can't drift.
Per review: the severity-label taxonomy's point is the labels that gate a
merge (Critical and Required), with Nit/Optional/FYI being the don't-block
side. In a doc about protecting a legacy codebase, name the blocking half
instead of only the optional one; let the skill remain the source of the
full taxonomy.
Add docs/developer-onboarding.md: a guided tour for people working on the
repo itself (the five layers, local setup, the verification loop, the
contribution paths, and a suggested reading order), complementing the
authoritative rules in CONTRIBUTING.md, skill-anatomy.md, and evals/README.md.
Link it from the top of CONTRIBUTING.md as the map to its rulebook.
Add docs/adoption-guide.md covering two rollout paths: full lifecycle
from day one for a greenfield project, and an incremental,
verification-first path for an established codebase. Link it from the
README (new Adoption section) and from getting-started.md's Recommended
Setup as the in-depth companion to the quick setup.
Per review: the policy collections (REQUIRED_SECTIONS, SECTION_EXEMPT_SKILLS,
SKILL_REF_PATTERNS, regexes) were exported by reference, so a consumer could
mutate shared state and change lint results process-wide. Export only the
linting functions; keep the policy collections private. No behavior change
(validator output byte-identical).
Bring docs/comparison.md up to date and make it more useful for people
choosing between the packs:
- agent-skills: add the three-tier eval framework as the current point of
difference, plus current tooling (Codex, Kiro, the npx skills CLI),
/build auto, and the 24-skill / 7-checklist / Definition-of-Done facts.
- Superpowers: correct to ~14 inner-loop skills, the consolidated single
task reviewer, the worst-case-executor plan standard, and its main
unmet ask (agent teams); drop the stale Gemini reference.
- Matt Pocock's skills: reframe around the grilling primitive and the
grown ~30-skill toolkit (in-progress/deprecated dirs, wayfinder,
seam-based TDD), not a "tight set".
- Add a much fuller "How to decide what to use" section after the table:
by shape of work, by what you optimize for, concrete scenarios, solo
vs team, and an honest shared-frontier note on cross-session memory.
Keeps the fair-not-flattering stance and the Om Mishra head-to-head.
Split the skill validation rules out of the validate-skills.js CLI into a
shared, importable scripts/lib/skill-lint.js: a pure lintSkillContent() with
no I/O plus a thin lintSkill() file wrapper. validate-skills.js becomes a thin
CLI over the lib. No behavior change to the validator's output or exit codes;
this only makes the rules unit-testable for a follow-up test battery.
State in CONTRIBUTING.md that translations of docs and skills are not
accepted: translated copies drift as content evolves and can't be
maintained long-term without leaning on agent translations plus
community corrections, for limited value.
Add a Scope banner to AGENTS.md and CLAUDE.md stating they configure
agents working on the addyosmani/agent-skills repository itself, not
users' own projects, referencing the repo by its canonical GitHub URL
so the scope is unambiguous when the file is read out of context. Add a
matching "Repo-scoped files" note to CONTRIBUTING.md so setup-guide
authors don't instruct users to copy these files.
Addy Osmani