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
- Read the
description field of each candidate. Match on trigger phrases, not the name.
- Prefer the narrower skill.
database-design beats clean-architecture for a schema question.
- Check
user-invocable - if the user wants to run something interactively, only recommend user-invocable skills.
- Skills stack. You can recommend multiple knowledge skills for one task (e.g.,
security + solid for a security review).
- 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?":
- Ask what they just completed (which agent/skill/team, what output they have)
- Consult compass for the recommended next step
- Verify the recommended agent/skill/team is installed (scan first - do not recommend from memory)
- Present the recommendation with one-line reasoning
- If multiple paths exist, present 2-3 options and let the user choose
- 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:
Critical Rules
- Scan first. Every recommendation starts with a live scan of what is installed. No hardcoded lists.
- Situation over title. Match what the user is doing, not what the skill is called.
- Specialist for scoped tasks, role for domain work, team for multi-role delivery.
- Chain over stretch. If a single skill does not cover the work, combine two. Do not force one skill beyond its fit.
- Never recommend uninstalled skills as available. Suggest installing with a hint, not as a next step.
- Respect agent boundaries. Read-only agents do not edit files. Dev agents run in worktrees.
- 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 |
1---2name: using-ecosystem3description: Ecosystem discovery advisor. Use when the user asks 'what skill should I use', 'what agent should I delegate to', 'which team fits this task', or when onboarding to available skills, agents, and teams. Scans ALL installed skills at runtime - not limited to any single plugin or vendor. Triggers: 'which skill', 'which agent', 'what do I use for', 'orient me', 'what tools do I have'.4---56# Using Ecosystem78Discover 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.910## Core Principles1112| Principle | Meaning |13|---|---|14| **Scan, don't guess** | Always scan installed skills/agents/teams before recommending. Never assume something is available. |15| **Match situation, not topic** | Pick the skill whose description triggers match what the user is doing, not the skill whose title loosely matches. |16| **Agents act, skills inform** | Skills are reference material. Agents are actors. Delegate work to an agent; consult a skill. |17| **Teams for multi-role work** | If the work needs 3+ agents coordinating, check for a pre-composed team before assembling ad-hoc. |18| **Narrower wins** | If two skills overlap, pick the one with the tighter trigger match. |19| **Chain when work crosses domains** | Multi-step tasks often need two or three agents in sequence. |2021---2223## Step 1: Scan What Is Installed2425Run the discovery commands from [discovery-commands](references/discovery-commands.md) to build a live index of installed skills, agents, and teams. Read each frontmatter `name` and `description` field.2627Do NOT skip this step. Do NOT recommend from memory. The installed set varies per user and per project.2829---3031## Step 2: Classify the User's Situation3233Determine what the user needs:3435| Signal | Category |36|---|---|37| Needs reference material, patterns, or principles | **Knowledge skill** |38| Needs to generate a specific output (ticket, PR message, report, rules file) | **Tool skill** |39| Needs to follow a step-by-step operational procedure | **Playbook skill** |40| Needs framework-specific component reference | **Framework skill** |41| Needs a single focused task done (investigate, review, implement) | **Specialist agent** |42| Needs ongoing domain ownership (requirements, architecture, QA) | **Role agent** |43| Needs coordinated multi-agent delivery (feature, release, review cycle) | **Team** |4445---4647## Step 3: Match and Recommend4849### Decision Tree5051```52User request53 |54 v55Does it need multiple agents coordinating?56 +-- Yes --> Scan bundled and project teams for a match57 | +-- Found --> Recommend the team58 | +-- None --> Assemble ad-hoc from agents (see chaining below)59 |60 +-- No --> Is it a well-scoped actionable task?61 +-- Yes --> Scan agents/ for a matching specialist or role62 +-- No --> Scan skills/ for a matching skill63 Use the category signals from Step 264```6566### Matching Rules67681. **Read the `description` field** of each candidate. Match on trigger phrases, not the name.692. **Prefer the narrower skill.** `database-design` beats `clean-architecture` for a schema question.703. **Check `user-invocable`** - if the user wants to run something interactively, only recommend user-invocable skills.714. **Skills stack.** You can recommend multiple knowledge skills for one task (e.g., `security` + `solid` for a security review).725. **Never recommend what is not installed.** If a skill would fit but is not present, suggest installing it with `npx skills add`.7374---7576## Step 4: Chain When Needed7778When a single skill or agent is not enough, chain them. Common patterns:7980| Pattern | Shape |81|---|---|82| **Investigation flow** | Read-only agent --> Design agent --> Implementation agent --> Review agent |83| **Feature flow** | Requirements role --> Architecture role --> Dev roles (parallel) --> QA role |84| **Review flow** | Smell scanner --> Reviewer --> (optional) Implementer for fixes |85| **Coverage flow** | Test gap analyzer --> Implementer --> Reviewer |8687These 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.8889---9091## Step 5: Compass - What Next?9293When the user has just finished work with an agent, skill, or team and asks "what next?" or "where do I go from here?":94951. Ask what they just completed (which agent/skill/team, what output they have)962. Consult [compass](references/compass.md) for the recommended next step973. Verify the recommended agent/skill/team is installed (scan first - do not recommend from memory)984. Present the recommendation with one-line reasoning995. If multiple paths exist, present 2-3 options and let the user choose1006. If nothing chains naturally, say so - not every task needs a follow-up101102Compass mode is conversational. Ask the user, do not scan the filesystem to infer what happened.103104---105106## Ecosystem Structure107108The ecosystem has five layers. The structure is stable - it does not change when skills are added.109110| Layer | Location | Format | Purpose |111|---|---|---|---|112| **Skills** | `skills/{category}/{name}/SKILL.md` | Markdown + YAML frontmatter | Reference material, tools, playbooks, roles, frameworks |113| **Agents** | `agents/{name}.md` | Markdown + YAML frontmatter | Specialist and role sub-agents |114| **Teams** | Bundled inside dispatching skill or at project `teams/{name}.md` | Markdown + YAML frontmatter | Pre-composed agent teams with coordination protocols |115| **Specs** | `spec/*.md` | Markdown | Format specifications for skills, agents, teams, plugins |116| **Plugins** | `.claude-plugin/marketplace.json` | JSON | Distribution bundles grouping skills and agents |117118### Skill Categories119120| Category | Path | Invocation |121|---|---|---|122| Knowledge | `skills/knowledge/` | Auto-loaded when relevant |123| Tools | `skills/tools/` | User-invocable slash commands |124| Playbooks | `skills/playbooks/` | User-invocable slash commands |125| Roles | `skills/roles/` | Auto-loaded by matching role agents |126| Frameworks | `skills/frameworks/{name}/` | Loaded when the framework is in play |127128### Agent Tiers129130| Tier | Scope | Examples |131|---|---|---|132| Specialist | Single repeatable task (stateless) | investigator, reviewer, refactor-scout |133| Role | Domain of responsibility (some carry memory) | architect, backend-dev, qa-engineer |134135### Team Spawning Modes136137| Mode | When | How |138|---|---|---|139| Peer | Platform supports agent-to-agent messaging | Lead creates team, teammates claim tasks and message each other |140| Sequential | All other platforms | Lead dispatches one sub-agent per phase, passes outputs forward |141142---143144## Quality Checklist145146Before answering a "which skill/agent/team" question:147148- [ ] Did I scan installed skills/agents/teams rather than recommending from memory?149- [ ] Did I match on the description's trigger phrases, not just the name?150- [ ] Did I consider whether a narrower, more specific skill exists?151- [ ] Did I recommend an agent when the work is actionable, not just reference material?152- [ ] Did I check for a pre-composed team when the work needs 3+ agents?153- [ ] Did I mention chaining when the work crosses domains?154- [ ] Did I avoid recommending something that is not installed?155156---157158## Critical Rules1591601. **Scan first.** Every recommendation starts with a live scan of what is installed. No hardcoded lists.1612. **Situation over title.** Match what the user is doing, not what the skill is called.1623. **Specialist for scoped tasks, role for domain work, team for multi-role delivery.**1634. **Chain over stretch.** If a single skill does not cover the work, combine two. Do not force one skill beyond its fit.1645. **Never recommend uninstalled skills as available.** Suggest installing with a hint, not as a next step.1656. **Respect agent boundaries.** Read-only agents do not edit files. Dev agents run in worktrees.1667. **Category is a signal.** Tools for interactive output, playbooks for procedures, knowledge for reference.167168---169170## Reference Files171172| Reference | Contents |173|---|---|174| [discovery-commands](references/discovery-commands.md) | Shell commands to scan installed skills, agents, and teams at runtime |175| [chaining-patterns](references/chaining-patterns.md) | Multi-agent chain templates with when-to-use guidance |176| [compass](references/compass.md) | "What next?" recommendation map for post-task navigation |
krzysztofsurdy