agent-orchestrator

## Overview

A meta-skill that orchestrates all ecosystem agents. Automatic skill scanning, capability-based matching, multi-skill workflow coordination and registry management.

## When to Use This Skill

- When you need specialized assistance with this domain

## Do Not Use This Skill When

- The task is unrelated to agent orchestrator
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

A meta-skill that acts as the central decision and coordination layer for the entire
skill ecosystem. It scans automatically, identifies relevant agents,
and orchestrates multiple skills for complex tasks.

## Principle: Zero Manual Intervention

- **ALWAYS scans** before processing any request
- New skills are **auto-detected and included** when you create SKILL.md in any subfolder
- Removed skills are **auto-excluded** from the registry
- No manual command is needed to register new skills

---

## Mandatory Workflow (Every Request)

Run these steps BEFORE processing any user request.
The scripts use relative paths automatically — they work from any directory.

## Step 1: Auto-Discovery (Scan)

```bash
python agent-orchestrator/scripts/scan_registry.py
```

Ultra-fast (<100ms) via an MD5-hash cache. It only re-processes changed files.
Returns a JSON with a summary of all skills found.

## Step 2: Skill Match

```bash
python agent-orchestrator/scripts/match_skills.py "<user's request>"
```

Returns a JSON with skills ranked by relevance. Interpret the result:

| Result                 | Action                                                  |
|:-----------------------|:--------------------------------------------------------|
| `matched: 0`          | No relevant skill. Operate normally without skills.     |
| `matched: 1`          | One relevant skill. Load its SKILL.md and follow it.    |
| `matched: 2+`         | Multiple skills. Run Step 3 (orchestration).            |

## Step 3: Orchestration (If Matched >= 2)

```bash
python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<request>"
```

Returns an execution plan with the pattern, the order of steps and the data flow between skills.

## Fast Step (Shortcut)

For simple queries, steps 1+2 can be combined in sequence:
```bash
python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<request>"
```

---

## Skill Registry

The registry lives in:
```
agent-orchestrator/data/registry.json
```

## Search Locations

The scanner looks for SKILL.md in:
1. `.claude/skills/*/` (skills registered in Claude Code)
2. `*/` (standalone top-level skills)
3. `*/*\` (skills in subfolders, up to depth 3)

## Metadata Per Skill

Each registry entry contains:

| Field          | Description                                        |
|:---------------|:---------------------------------------------------|
| name           | Skill name (from the YAML frontmatter)             |
| description    | Full description (triggers included)               |
| location       | Absolute path of the directory                     |
| skill_md       | Absolute path of the SKILL.md                      |
| registered     | Whether it's in .claude/skills/ (true/false)       |
| capabilities   | Capability tags (auto-extracted + explicit)        |
| triggers       | Activation keywords extracted from the description |
| language       | Main language (python/nodejs/bash/none)            |
| status         | active / incomplete / missing                      |

## Registry Commands

```bash

## Quick Scan (Uses The Hash Cache)

python agent-orchestrator/scripts/scan_registry.py

## Detailed Status Table

python agent-orchestrator/scripts/scan_registry.py --status

## Full Re-Scan (Ignores The Cache)

python agent-orchestrator/scripts/scan_registry.py --force
```

---

## Matching Algorithm

For each request, the matcher scores skills using:

| Criterion                    | Points | Example                               |
|:-----------------------------|:-------|:--------------------------------------|
| Skill name in the query      | +15    | "use web-scraper" -> web-scraper      |
| Exact keyword trigger        | +10    | "scrape" -> web-scraper               |
| Capability category          | +5     | data-extraction -> web-scraper        |
| Word overlap                 | +1     | Query words in the description        |
| Project boost                | +20    | Skill assigned to the active project  |

Minimum threshold: 5 points. Skills below that are ignored.

## Project Match

```bash
python agent-orchestrator/scripts/match_skills.py --project my-project "query here"
```

Skills assigned to the project receive an automatic +20 boost.

---

## Orchestration Patterns

When multiple skills are relevant, the orchestrator classifies the pattern:

## 1. Sequential Pipeline

Skills form a chain where one's output feeds the next.

**When:** A mix of "producer" skills (data-extraction, government-data) and "consumer" skills (messaging, social-media).

**Example:** web-scraper collects prices -> whatsapp-cloud-api sends an alert

```
user_query -> web-scraper -> whatsapp-cloud-api -> result
```

## 2. Parallel Execution

Skills work independently on different aspects of the request.

**When:** All skills have the same role (all producers or all consumers).

**Example:** instagram publishes a post + whatsapp sends a notification (both receive the same content)

```
user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result
```

## 3. Primary + Support

One main skill leads; others provide supporting data.

**When:** One skill scores much higher than the others (>= 2x).

**Example:** whatsapp-cloud-api sends a message (primary) + web-scraper provides data (support)

```
user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result
```

## Details In `References/Orchestration-Patterns.Md`

---

## Project Management

Assigning skills to projects enables a relevance boost and persistent context.

## Projects File

```
agent-orchestrator/data/projects.json
```

## Operations

**Create a project:**
Add an entry to projects.json:
```json
{
  "name": "project-name",
  "created_at": "2026-02-25T12:00:00",
  "skills": ["web-scraper", "whatsapp-cloud-api"],
  "description": "Project description"
}
```

**Add a skill to a project:** Update the project's `skills` array.

**Remove a skill from a project:** Remove it from the `skills` array.

**List a project's skills:** Read projects.json and list the assigned skills.

---

## Adding New Skills

To add a new skill to the ecosystem:

1. Create a folder anywhere under `skills root:`
2. Create a `SKILL.md` with YAML frontmatter:
```yaml
---
name: my-new-skill
description: "Description with activation keywords..."
---

## Skill Documentation

```
3. **Done!** Auto-discovery detects it automatically on the next request.

Optionally, for native Claude Code discovery:
4. Copy the SKILL.md to `.claude/skills/<name>/SKILL.md`

## Explicit Capability Tags (Optional)

Add to the frontmatter for more precise matching:
```yaml
capabilities: [data-extraction, web-automation]
```

---

## View The Status Of All Skills

```bash
python agent-orchestrator/scripts/scan_registry.py --status
```

## Interpret The Status

| Status     | Meaning                                            |
|:-----------|:---------------------------------------------------|
| active     | SKILL.md with name + description present           |
| incomplete | SKILL.md exists but is missing name or description |
| missing    | Directory exists but has no SKILL.md               |

---

## Current Ecosystem Skills

| Skill              | Capabilities                          | Status  |
|:-------------------|:--------------------------------------|:--------|
| web-scraper        | data-extraction, web-automation       | active  |
| junta-leiloeiros   | government-data, data-extraction      | active  |
| whatsapp-cloud-api | messaging, api-integration            | active  |
| instagram          | social-media, api-integration         | partial |

*This table is updated automatically via `scan_registry.py --status`.*

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `multi-advisor` - Complementary skill for enhanced analysis
- `task-intelligence` - Complementary skill for enhanced analysis