Addresses the clarity nit in #236 review: a single supporting doc stays a
loose file, and the skill-local references/ subdir is for grouping several
related docs that travel with the skill. Ties the new bullet back to the
existing Supporting files entry so the framings read as one.
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.
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.
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.
In Codex CLI 0.122 the marketplace subcommand moved from
`codex marketplace` to `codex plugin marketplace`. Update README and
docs/codex-setup.md so install snippets work on current Codex (verified
on 0.128.0). Keep one historical reference in the v0.122 callout.
Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills`
installs it in a single step. The plugin reads the existing `skills/` directory via
a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single
source of truth shared with Claude Code.
- codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/"
- codex/skills → ../skills — symlink so the plugin dir stays self-contained
while git tracks a single canonical skills/ at the repo root
- .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex
- docs/codex-setup.md — install and usage guide
Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's
Skills list after install.
Resolve AGENTS.md conflict: keep this PR's pointer to docs/skill-anatomy.md
(the section main patched via #307 is the one this PR removes, so the
line-level fix is moot once the section is gone).
Also fix a stale path the port reintroduced: skill-anatomy.md referenced
/mnt/skills/user/... for scripts; correct it to the repo-relative
skills/<skill-name>/scripts/<script>.sh, matching #307.
Addy flagged that the AGENTS.md cleanup in #313 dropped two still-accurate subsections with no home elsewhere. Port them into docs/skill-anatomy.md, the canonical home for skill structure, so the dedup cleanup keeps the real guidance it was never meant to remove.
When agent-skills is installed as a Claude Code plugin, the plugin loader emits
a cosmetic warning about the root commands/ folder being ignored in favour of
.claude/commands/. The root commands/ directory is intentional (Antigravity CLI),
so the warning confuses installers into thinking something is broken.
Add a Note callout under 'Using Commands' in getting-started.md clarifying that
the warning is expected and all Claude Code commands load correctly.
Fixes#298
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Per review feedback: clarify that cherry-picking individual skills works,
but running two frameworks as active routers at once causes command-name
conflicts, competing routing, and clashing TDD philosophies. Recommend
one primary router + à la carte borrowing.
The slash-command reference table in docs/getting-started.md lists every
lifecycle command except /code-simplify, even though it is documented in
the README, has command files for all platforms (.claude/.gemini/commands),
and the table already includes the more specialized /webperf. Add the
missing row mapping /code-simplify to the code-simplification skill.
Tools that scan agents/*.md as custom agent definitions (e.g. GitHub Copilot CLI) parse every Markdown file in agents/ and require YAML frontmatter. agents/README.md was docs, not an agent, so it triggered "malformed custom agent" warnings on every session start.
Moving the docs to docs/agents.md keeps agents/ containing only real agent definitions. Updates internal links in the moved file, in the four persona files, AGENTS.md, and adds a pointer from the root README.
Fixes#258
Follow-up after the #222 merge left the new persona/command only half-wired:
- Register web-performance-auditor in the README agents table, the
getting-started "Using Agents" table, and CLAUDE.md (3 -> 4 personas).
- Document /webperf in CLAUDE.md and the getting-started command table.
- Add .gemini/commands/webperf.toml so Gemini users get /webperf too
(mirrors the Claude command; persona invoked inline rather than spawned).
Adds an autonomous mode to the build command: once a spec exists,
`/build auto` (also `all`/`fast`) generates the plan if missing, takes a
single plan approval, then implements every task in dependency order with
full TDD and a commit per task.
Removes the manual stepping between tasks without removing verification —
each task still earns a passing test and its own commit, so any point is a
clean rollback. Auto-pauses for human input on failures, spec ambiguity,
or high-risk/irreversible tasks (auth, destructive migrations, payments,
deletes, deploys, secrets).
- .claude/commands/build.md: two-mode definition (default vs auto)
- .gemini/commands/build.toml: mirrored for Gemini CLI
- README.md, docs/getting-started.md: document the new mode
GitHub Copilot requires custom agent files to be named *.agent.md.
The previous instructions copied them as *.md, which Copilot silently
ignores, so agents would never be available in Copilot Chat.
Changes:
- Rename all three cp commands to use the .agent.md suffix
- Add mkdir -p .github/agents (was missing, cp would have failed)
- Add a callout block explaining the naming requirement with a link
to the VS Code custom agents docs
- Update section heading from "(agents.md)" to "(*.agent.md)"
Fixes#179
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Introduces .gemini/commands/ with TOML definitions for 7 slash commands
(build, spec, planning, review, test, ship, code-simplify), enabling
Gemini CLI to auto-discover them from the project root.
The planning command is named /planning rather than /plan to avoid
conflicting with a Gemini CLI internal command name.
Updates README.md project structure tree and adds a Slash Commands
section with a reference table to docs/gemini-cli-setup.md.
