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.
Add anti-duplication guardrails so agents working in this repo follow the CONTRIBUTING.md pre-flight checklist before adding a skill, keeping CONTRIBUTING.md as the single source of truth instead of duplicating it.
- CLAUDE.md: add a Contributing pointer plus a pre-flight Boundaries rule
- AGENTS.md: replace the stale "Creating a New Skill" section (the repo has no per-skill zips and scripts are optional) with a pointer to CONTRIBUTING.md and docs/skill-anatomy.md
- .claude/rules/skills-contributing.md: path-scoped rule (skills/**) that loads the dedup guardrail only when editing skills
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
Verify the orchestration design against the official Claude Code docs and
make the platform mapping explicit:
- /ship now names the Agent tool and the subagent_type field directly,
with a fallback note for harnesses that lack an Agent tool.
- AGENTS.md notes that personas work as both subagents and Agent Teams
teammates, and lists the unsupported plugin frontmatter fields.
- agents/README.md gains a Claude Code interop section and notes that
rule #2 is also a hard platform constraint.
- references/orchestration-patterns.md gains a Claude Code compatibility
appendix covering plugin paths, the subagents-vs-teams comparison, the
built-in Explore/Plan/general-purpose subagents, and the parallel
Agent tool call requirement. Pattern 5 now points at Explore first.
No behavior changes; documentation only.
Document the three composable layers (skills, personas, slash commands),
the rule that personas do not invoke other personas, and that parallel
fan-out via /ship is the only multi-persona pattern this repo endorses.
Points contributors at agents/README.md and references/orchestration-patterns.md
for the full guidance.
Joan Leon