Commit Graph
88 Commits
Author SHA1 Message Date
Addy Osmani be4e44a9fb Merge #553: clarify setup for existing projects
docs: clarify setup for existing projects
2026-09-11 20:14:58 -07:00
Addy Osmani fd00a70f8a Merge #559: define restartable task boundaries
docs: define restartable task boundaries
2026-09-11 20:14:49 -07:00
Addy Osmani 4e94bb5912 Merge #560: map shared core to native adapters
docs: map shared core to native adapters
2026-09-11 20:14:41 -07:00
Addy Osmani 17cbf4b720 Merge #557: avoid double routing on native skill hosts
docs: avoid double routing on native skill hosts
2026-09-11 20:14:31 -07:00
Addy Osmani 57c0196ff2 Merge #552: clarify stable browser skill name
docs(skills): clarify stable browser skill name
2026-09-11 20:14:16 -07:00
vam 17d8e52b7c docs: map shared core to native adapters 2026-09-05 11:54:33 +08:00
vam a1c9bd627c docs: define restartable task boundaries 2026-09-05 11:51:37 +08:00
vam a71eb51e05 docs: avoid double skill routing on native hosts 2026-09-05 11:45:31 +08:00
vam 5b98a0b17b docs: link runnable workflow tutorials 2026-09-05 11:42:49 +08:00
vam 4fd76c6f00 docs: clarify setup for existing projects 2026-09-05 11:39:33 +08:00
vam 674921ca8d docs(skills): clarify stable browser skill name 2026-09-05 11:38:44 +08:00
Addy Osmani 858c1aea80 Merge #550: clarify Copilot CLI vs VS Code installation
docs(copilot): clarify CLI installation and VS Code commands
2026-09-04 20:21:31 -07:00
DEOWL-kan f7fe1a447d docs(copilot): clarify CLI installation and VS Code commands 2026-09-05 11:13:50 +08:00
DEOWL-kan 878d5d4789 docs: explain lifecycle session handoffs (#513) 2026-09-05 11:13:50 +08:00
Federico Bartoli 1c760d6434 Merge pull request #316 from nucliweb/docs/advanced-per-agent-configuration
docs: add advanced per-agent configuration guide
2026-09-04 08:45:55 +02:00
ayobamiseun cd8922b617 docs(antigravity): document the command-wrapper discoverability limitation (#445)
Affected agy 1.1.x releases report the 8 legacy command TOMLs as
converted to skills, but the converted wrappers never appear in the
slash-command or skill catalog — plugin validate passing confirms the
files are well formed, not that /build and the other wrappers exist.

Replace the slash-command table with a wrapper-to-direct-invocation
map (/agent-skills:<skill-name>, /agents for the webperf persona),
note the wrapper-only behaviors that are unavailable (/build auto
orchestration, /ship persona fan-out), warn against the YAML
frontmatter workaround that breaks Gemini CLI's TOML parser, and add
a post-install verification step. Align the README blurb with the
same guidance.
2026-08-30 00:17:37 +01:00
Addy Osmani 2ce8d47a16 Merge pull request #472 from addyosmani/feat/constraint-driven-development
feat(skills): add constraint-driven-development
2026-08-28 16:23:03 -07:00
Joan Leon 485cd8ee86 docs: correct allowed-tools semantics, document disallowed-tools
Review feedback from @federicobartoli on #316.

allowed-tools was described as restricting the tool set. Per the Claude
Code docs it is a permission pre-approval: listed tools run without a
prompt for the turn that invokes the skill, the grant clears on the next
message, and nothing leaves the tool pool.

disallowed-tools is the field that actually restricts, so it now carries
the least-privilege guidance. Added the portability caveat that it is a
Claude Code field rather than one of the specification's six, so it fails
packaging if placed in a published SKILL.md.

Claude-Session: https://claude.ai/code/session_01TuWNaEV9RFXpTxqeBRTRg8
2026-08-27 23:08:46 +02:00
Joan Leon 58a37a0a55 docs: refine per-agent config guide (agent field, spec link, #35)
Link the Agent Skills spec, document the optional `agent` companion to
`context: fork`, clarify that commands and skills share frontmatter, and
add #35 to the consolidated Status list.
2026-08-27 23:08:46 +02:00
Joan Leon 34da7eb97e docs: mark per-agent config as canonical and add thinking_level example
Address review feedback on #316:
- State explicitly that this supersedes the inline top-level frontmatter approach, so kind/model/temperature/max_turns/tools/context must not appear at the top level of a skill.
- Add a copy-pasteable .gemini/agents/*.md example using thinking_level instead of hardcoded temperature for Gemini 3.x.
- Update Status: #272 and #36 are closed in favor of this approach.
2026-08-27 23:08:46 +02:00
Joan Leon aca2f9e06a docs: add advanced per-agent configuration guide
Add a draft reference for per-agent runtime configuration that keeps shared SKILL.md files portable while documenting the vendor-specific controls each agent offers (Claude Code, Gemini CLI, Antigravity) as an opt-in.
2026-08-27 23:08:46 +02:00
alexsyntonize 75af8bc50e docs(opencode): clarify skill installation and AGENTS.md scope
Rewrite docs/opencode-setup.md so it no longer instructs users to copy
the repo-scoped root AGENTS.md. Instead, document how to install skills
into .opencode/skills/ (project), ~/.config/opencode/skills/ (global),
and cross-compatible Claude/agent paths. Provide a project-local
AGENTS.md template and keep the intent mapping and lifecycle guidance.

Update the README summary to match the new installation model.

Refs #99
Refs #119
2026-08-25 13:02:22 +02:00
Yunare Maia 4acb9bb799 docs(antigravity): correct plugin install path per Issue #445
The setup doc claimed plugins install to ~/.gemini/antigravity-cli/plugins/
but on current agy releases they land in ~/.gemini/config/plugins/. Issue
#445 reporter confirmed the plugin lives under config/ on disk. Update the
path and add a note so users check the right location first.

Signed-off-by: Yunare Maia <yunare@gmail.com>
2026-08-11 19:58:38 +00:00
Addy Osmani 217feb229f docs: route to constraint-driven-development and refresh skill counts 2026-08-08 09:57:00 -07:00
Addy Osmani 6ff936ac3d Merge #452: complete Codex install flow and manifest metadata
fix(codex): complete plugin install flow and manifest metadata
2026-08-06 15:44:07 -07:00
Addy Osmani 471b6f1da6 Merge #450: add Command Code as a native skills provider
docs: add Command Code as a native skills provider
2026-08-06 15:44:03 -07:00
mksong 6a52513fe3 fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:57:09 +09:00
Vipul GuptaandCopilot Autofix powered by AI 75dfcb3348 Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-08-03 20:31:18 +05:30
Vipul Gupta (@vipulgupta2048)andCommandCodeBot e8089ebe61 docs: add Command Code as a native skills provider
Command Code has a native skills CLI (cmd skills add <owner/repo>) that
clones the repo, discovers every SKILL.md, and installs into
.commandcode/skills/ — no plugin manifest or copied files needed.

- README: add Command Code install block
- docs/commandcode-setup.md: setup guide (install/manage/usage, paths)
- docs/comparison.md: add Command Code to tooling reach

Verified end-to-end against addyosmani/agent-skills: add (all / -s / @branch /
path / --global / --force), list (+ -d), and remove (project / --global) via
the CLI, plus skill discovery in the TUI slash menu.

Signed-off-by: Vipul Gupta (@vipulgupta2048) <vipulgupta2048@gmail.com>
Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
Signed-off-by: Vipul Gupta (@vipulgupta2048) <vipulgupta2048@gmail.com>
2026-08-02 23:54:39 +05:30
ayobamiseun b70fbe910e docs: explain per-skill reference limitation 2026-08-01 10:28:06 +01:00
Joan Leon 4df5698502 docs: distinguish loose supporting file from skill-local references/ subdir
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.
2026-07-24 10:31:39 +02:00
Joan Leon 8fd208160c docs: document skill-local references/ directory in skill anatomy 2026-07-20 18:44:55 +02:00
Federico Bartoli 2fbfa004a0 Merge pull request #401 from kevglynn/contrib/329-shared-references-rationale
docs(skill-anatomy): explain the shared references/ design
2026-07-18 15:19:55 +02:00
Quantum22 825a01b308 docs: fix orchestration-patterns.md reference mapping in getting-started
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.
2026-07-17 16:23:41 -07:00
Kevin Glynn aca5326aba docs(skill-anatomy): reword rule of thumb to current convention per review 2026-07-15 01:46:16 -04:00
Kevin GlynnandCursor b7e7c9587d docs(skill-anatomy): explain the shared references/ design (closes addyosmani#329)
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>
2026-07-14 13:00:52 -04:00
Addy Osmani 98967c45a4 Merge pull request #396 from nucliweb/docs/adoption-guide
docs: add adoption guide for greenfield vs brownfield rollout
2026-07-12 10:58:04 -07:00
Joan Leon 7209bd12d8 docs(developer-onboarding): point to CONTRIBUTING for new-skill rules
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.
2026-07-12 19:48:34 +02:00
Joan Leon 27dcc32b83 docs(adoption-guide): name the merge-blocking review labels
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.
2026-07-12 19:47:07 +02:00
Joan Leon 695505ddac docs: add developer onboarding guide for repo contributors
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.
2026-07-12 15:50:11 +02:00
Joan Leon ffd7db67e3 docs: add adoption guide (greenfield vs brownfield rollout)
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.
2026-07-12 14:16:49 +02:00
Addy Osmani 7ce442de03 docs(comparison): refresh and expand the three-way comparison
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.
2026-07-10 10:01:07 -07:00
Addy Osmani 6bcfeb9dae Merge pull request #218 from nguyenducthaonguyen/docs/update-cursor-setup
docs: update Cursor setup guide for rules and skills layout
2026-07-09 19:59:20 -07:00
ShiroKSH df8eda8fbe fix: harden eval and command validation 2026-07-09 18:03:46 +03:00
Federico Bartoli 9c0edb07df fix: prevent Codex from loading Claude hooks 2026-07-09 00:03:10 +02:00
Federico Bartoli 97522bb69b fix: use root Codex plugin layout 2026-07-08 15:57:32 +02:00
Federico Bartoli 41f6a03a59 docs(codex): update install command for Codex CLI v0.122+
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.
2026-07-08 15:39:36 +02:00
Federico Bartoli 1afa9ef325 feat: add codex cli reference in codex-setup 2026-07-08 15:39:36 +02:00
Federico Bartoli 3a76ead2ef feat: add Codex plugin support without duplicating skills
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.
2026-07-08 15:39:36 +02:00
Addy Osmani da05b987c6 Merge origin/main into docs/skill-contributing-guardrails
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.
2026-06-28 01:20:50 -07:00