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>
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
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.
Federico Bartoli