krzysztofsurdy/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 |