using-ecosystem

Using Ecosystem

Discover the right skill, agent, or team for the situation at hand. This skill teaches a discovery PROCESS - it does not maintain a hardcoded inventory. Every recommendation comes from scanning what is actually installed.

Core Principles

Principle	Meaning
Scan, don't guess	Always scan installed skills/agents/teams before recommending. Never assume something is available.
Match situation, not topic	Pick the skill whose description triggers match what the user is doing, not the skill whose title loosely matches.
Agents act, skills inform	Skills are reference material. Agents are actors. Delegate work to an agent; consult a skill.
Teams for multi-role work	If the work needs 3+ agents coordinating, check for a pre-composed team before assembling ad-hoc.
Narrower wins	If two skills overlap, pick the one with the tighter trigger match.
Chain when work crosses domains	Multi-step tasks often need two or three agents in sequence.

---

Step 1: Scan What Is Installed

Run the discovery commands from discovery-commands to build a live index of installed skills, agents, and teams. Read each frontmatter name and description field.

Do NOT skip this step. Do NOT recommend from memory. The installed set varies per user and per project.

---

Step 2: Classify the User's Situation

Determine what the user needs:

Signal	Category
Needs reference material, patterns, or principles	Knowledge skill
Needs to generate a specific output (ticket, PR message, report, rules file)	Tool skill
Needs to follow a step-by-step operational procedure	Playbook skill
Needs framework-specific component reference	Framework skill
Needs a single focused task done (investigate, review, implement)	Specialist agent
Needs ongoing domain ownership (requirements, architecture, QA)	Role agent
Needs coordinated multi-agent delivery (feature, release, review cycle)	Team

---

Step 3: Match and Recommend

Decision Tree

User request
   |
   v
Does it need multiple agents coordinating?
   +-- Yes --> Scan bundled and project teams for a match
   |            +-- Found --> Recommend the team
   |            +-- None  --> Assemble ad-hoc from agents (see chaining below)
   |
   +-- No --> Is it a well-scoped actionable task?
               +-- Yes --> Scan agents/ for a matching specialist or role
               +-- No  --> Scan skills/ for a matching skill
                            Use the category signals from Step 2

Matching Rules

1. Read the description field of each candidate. Match on trigger phrases, not the name.
2. Prefer the narrower skill. database-design beats clean-architecture for a schema question.
3. Check user-invocable - if the user wants to run something interactively, only recommend user-invocable skills.
4. Skills stack. You can recommend multiple knowledge skills for one task (e.g., security + solid for a security review).
5. Never recommend what is not installed. If a skill would fit but is not present, suggest installing it with npx skills add.

---

Step 4: Chain When Needed

When a single skill or agent is not enough, chain them. Common patterns:

Pattern	Shape
Investigation flow	Read-only agent --> Design agent --> Implementation agent --> Review agent
Feature flow	Requirements role --> Architecture role --> Dev roles (parallel) --> QA role
Review flow	Smell scanner --> Reviewer --> (optional) Implementer for fixes
Coverage flow	Test gap analyzer --> Implementer --> Reviewer

These are guidelines, not rituals. Skip steps that do not apply. Add steps that do. If a pre-composed team matches the chain, use the team instead.

---

Step 5: Compass - What Next?

When the user has just finished work with an agent, skill, or team and asks "what next?" or "where do I go from here?":

1. Ask what they just completed (which agent/skill/team, what output they have)
2. Consult compass for the recommended next step
3. Verify the recommended agent/skill/team is installed (scan first - do not recommend from memory)
4. Present the recommendation with one-line reasoning
5. If multiple paths exist, present 2-3 options and let the user choose
6. If nothing chains naturally, say so - not every task needs a follow-up

Compass mode is conversational. Ask the user, do not scan the filesystem to infer what happened.

---

Ecosystem Structure

The ecosystem has five layers. The structure is stable - it does not change when skills are added.

Layer	Location	Format	Purpose
Skills	skills/{category}/{name}/SKILL.md	Markdown + YAML frontmatter	Reference material, tools, playbooks, roles, frameworks
Agents	agents/{name}.md	Markdown + YAML frontmatter	Specialist and role sub-agents
Teams	Bundled inside dispatching skill or at project teams/{name}.md	Markdown + YAML frontmatter	Pre-composed agent teams with coordination protocols
Specs	spec/*.md	Markdown	Format specifications for skills, agents, teams, plugins
Plugins	.claude-plugin/marketplace.json	JSON	Distribution bundles grouping skills and agents

Skill Categories

Category	Path	Invocation
Knowledge	skills/knowledge/	Auto-loaded when relevant
Tools	skills/tools/	User-invocable slash commands
Playbooks	skills/playbooks/	User-invocable slash commands
Roles	skills/roles/	Auto-loaded by matching role agents
Frameworks	skills/frameworks/{name}/	Loaded when the framework is in play

Agent Tiers

Tier	Scope	Examples
Specialist	Single repeatable task (stateless)	investigator, reviewer, refactor-scout
Role	Domain of responsibility (some carry memory)	architect, backend-dev, qa-engineer

Team Spawning Modes

Mode	When	How
Peer	Platform supports agent-to-agent messaging	Lead creates team, teammates claim tasks and message each other
Sequential	All other platforms	Lead dispatches one sub-agent per phase, passes outputs forward

---

Quality Checklist

Before answering a "which skill/agent/team" question:

• Did I scan installed skills/agents/teams rather than recommending from memory?
• Did I match on the description's trigger phrases, not just the name?
• Did I consider whether a narrower, more specific skill exists?
• Did I recommend an agent when the work is actionable, not just reference material?
• Did I check for a pre-composed team when the work needs 3+ agents?
• Did I mention chaining when the work crosses domains?
• Did I avoid recommending something that is not installed?

---

Critical Rules

1. Scan first. Every recommendation starts with a live scan of what is installed. No hardcoded lists.
2. Situation over title. Match what the user is doing, not what the skill is called.
3. Specialist for scoped tasks, role for domain work, team for multi-role delivery.
4. Chain over stretch. If a single skill does not cover the work, combine two. Do not force one skill beyond its fit.
5. Never recommend uninstalled skills as available. Suggest installing with a hint, not as a next step.
6. Respect agent boundaries. Read-only agents do not edit files. Dev agents run in worktrees.
7. Category is a signal. Tools for interactive output, playbooks for procedures, knowledge for reference.

---

Reference Files

Reference	Contents
discovery-commands	Shell commands to scan installed skills, agents, and teams at runtime
chaining-patterns	Multi-agent chain templates with when-to-use guidance
compass	"What next?" recommendation map for post-task navigation