Agent-Skill-Stack

# Build an Agent Skill Stack

Build the smallest useful stack for the user's actual outcome. Never force a domain example or a fixed lifecycle onto a different request.

1. Choose the user-facing depth

Default to **plain-language mode**. Assume the user does not need to understand paths, revisions, hashes, manifests, static analysis, or runtime details.

In plain-language mode, show:

- what the user is trying to accomplish;

- the steps in everyday language;

- which capabilities are already available;

- which Skills are recommended, optional, overlapping, or unsuitable;

- how widely each candidate is used;

- whether it passed an installation safety check and a safe trial;

- what account access or external actions it may require.

Keep source paths, revisions, file fingerprints, raw scores, audit evidence, and dependency details in the internal record. Show them only when the user asks for technical details or when a specific technical fact is necessary for informed consent.

2. Derive the workflow dynamically

Read [references/workflow-model.md](references/workflow-model.md). Begin with the final result the user wants, not the domain words in the request.

Ask only questions whose answers materially change the result, access boundary, cost, or stack. Derive the workflow backward from success, then validate it forward from the available starting point.

Do not reuse a previous numbered flow. Do not assume that every request needs research, content creation, publishing, analytics, storage, or automation. Add a step only when the user's outcome requires it.

Stop decomposing when a step has one understandable action, one main result, one access boundary, and one observable success condition. Keep the technical capability cards internal; show the user a short plain-language flow.

3. Search the local index first

Read [references/local-index-and-profiles.md](references/local-index-and-profiles.md).

If a current local Skill index exists, search it before the filesystem or internet. If it is missing or stale, rebuild it from the relevant Skill roots:

python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json

The index stores names, summaries, aliases, scope, capability terms, update time, and internal file fingerprints. It never executes a Skill and stores no usage history.

If the current project has `.codex/skill-stack.json`, treat its active Skills and routing rules as the first-choice stack. Search outside the profile only for an uncovered capability or when the user asks for alternatives. Treat same-name entries from different local roots as a review item; do not silently merge them.

4. Map capabilities, including indirect helpers

For every necessary step, record internally:

- required input, action, and output;

- constraints, frequency, and scale;

- local/read-external/write-external boundary;

- account, permission, and approval needs;

- success condition and fallback;

- predecessor and successor steps.

Then consider cross-cutting needs only where relevant: quality/style, accuracy, compliance, privacy, localization, data quality, orchestration, and observability.

Match Skills by `input -> operation -> output`, not by title similarity. This allows a Humanizer to match a natural-writing requirement even when the user's domain never appears in its name.

Do not force one Skill per step. A Skill may cover several steps; a step may need a tool, MCP, connector, or general agent capability rather than another Skill.

5. Search with four lenses

Read [references/discovery-ranking.md](references/discovery-ranking.md). Search each uncovered capability through:

1. **Direct need**: the user's domain and action.

2. **Underlying operation**: the actual transformation or data task.

3. **Supporting outcome**: quality, safety, style, compliance, evalu