agents-root-orchestrator

name	agents-root-orchestrator
description	Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly.
skillMetadata	{"author":"skilly-hand","last-edit":"2026-04-03","license":"Apache-2.0","version":"1.0.0","changelog":"Added root AGENTS orchestration guidance around Where/What/When structure; improves AI task routing clarity and trigger recognition; affects root AGENTS authoring workflow","auto-invoke":"Creating or updating root AGENTS.md orchestration guidance","allowed-tools":["Read","Edit","Write","Glob","Grep","Bash","Task","SubAgent"]}

AGENTS Root Orchestrator Guide

When to Use

Use this skill when:

• Creating a new root AGENTS.md for a repository.
• Refactoring root AI instructions that have grown inconsistent.
• Converting scattered guidance into a single routing guide.
• Defining explicit trigger-based skill invocation behavior.

Do not use this skill for:

• Subfolder-only guides that inherit from parent AGENTS files.
• One-off prompt notes with no reusable routing value.
• Agent-specific mirror files (CLAUDE.md, GEMINI.md) as primary source.

---

Core Structure: Where / What / When

Where (Context and Boundaries)

Define where the guide applies and where to escalate:

• Repository scope and ownership boundaries.
• Folder map and key domains.
• Escalation path when a task exceeds local scope.

What (Capabilities and Routing)

Define what AI should use:

• Installed skill registry with concise purpose.
• Role-oriented routing tables (task -> skill chain).
• Non-negotiable rules and default conventions.

When (Triggers and Sequencing)

Define when skills must be invoked:

• Auto-invoke trigger table by action.
• Ordered workflow chains for recurring tasks.
• Prerequisite rules so downstream skills are never invoked first.

Chaining Notations (Workflow Composition)

Define integrated multi-skill chains using explicit notation:

• Use -> to document prerequisite order.
• Keep each chain named and scoped to one repeated workflow.
• Add a one-line "when to use" note after each chain.
• Treat earlier steps as mandatory unless explicitly marked optional.

---

Decision Tree

Is this the repository-wide instruction entry point?
  YES -> Create/update root AGENTS.md with Where/What/When
  NO  -> Use subfolder AGENTS conventions and inherit parent rules

Does the task require routing across multiple skill types?
  YES -> Add Task -> Skill chain table in What
  NO  -> Keep concise capability list and direct triggers

Are trigger conditions currently implicit or ambiguous?
  YES -> Add explicit action-based trigger rows in When
  NO  -> Keep existing triggers but normalize wording

---

Example Outline

Example 1: Where Section

## Where

- Scope: repository root and all descendant folders unless overridden.
- Primary map: app code in `src/`, automation in `scripts/`, tests in `tests/`.
- Escalate to maintainers when task changes CI, security, or release flows.

Example 2: When Section

## When

| Action | Skill |
| ------ | ----- |
| Planning multi-step feature work | `spec-driven-development` |
| Creating new reusable skill instructions | `forge-me-a-skill` |
| Updating root AGENTS orchestration map | `agents-root-orchestrator` |

Example 3: Chaining Notations Section

## Chaining Notations

Chaining notations document integrated workflows where multiple skills are sequentially invoked for complex tasks. Always invoke skills in documented order.

### Skill Creation Workflow

```text
Asking for a new skill
  -> forge-me-a-skill
  -> spec-driven-development
  -> agents-root-orchestrator
```

When to use: creating and registering a new reusable skill workflow.

---

Commands

mkdir -p .skilly-hand/catalog/agents-root-orchestrator/assets
cp .skilly-hand/catalog/agents-root-orchestrator/assets/AGENTS-ROOT-TEMPLATE.md AGENTS.md
npx skilly-hand install --dry-run

---

Resources

• Template: assets/AGENTS-ROOT-TEMPLATE.md
• Companion skills:
  • ../forge-me-a-skill/SKILL.md
  • ../spec-driven-development/SKILL.md