# Arch Skills Guide

> Explain the arch skill suite, distinguish the live subskills, and recommend the right one for a user's task. Use when a request asks which arch skill to use, what the difference is between `arch-step`, `miniarch-step`, `arch-docs`, `arch-mini-plan`, `lilarch`, `bugs-flow`, `audit-loop`, `comment-loop`, `audit-loop-sim`, `north-star-investigation`, `arch-flow`, or wants a quick tour of the arch suite. Not for actually running the underlying workflow.

- Skill: `aelaguiz/arch-skills-guide` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aelaguiz/arch-skills-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aelaguiz/arch-skills-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: aelaguiz (https://skillmd.com/u/aelaguiz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aelaguiz/arch-skills-guide

---


# Arch Skills Guide

Use this skill when the user needs help choosing or understanding the arch suite, not when they are ready to run the underlying workflow.

## When to use

- The user asks which arch skill to use.
- The user asks for the difference between the arch subskills.
- The user wants a quick arch-suite tour before choosing a workflow.
- The user describes a task and wants the best-fit subskill recommendation.

## When not to use

- The user already knows the right subskill and wants the work done. Switch to that skill instead.
- The ask is generic architecture advice unrelated to this repo's arch suite.
- The user is asking for flow status inside an existing doc. Use `arch-flow`.

## Non-negotiables

- Recommend one primary skill whenever possible.
- If the task is ambiguous, name the top 2 candidates and explain the boundary between them.
- Tie the recommendation to the user’s actual ask, not to generic descriptions.
- Do not keep the guide skill loaded once the user wants execution; hand off to the recommended skill.
- Stay current with the installed suite only. Do not route to removed umbrellas or archived surfaces.

## First move

1. Read `references/skill-map.md`.
2. Classify the ask into one of these families:
   - broad full arch
   - faster full arch
   - docs cleanup
   - mini-plan
   - lilarch
   - bug flow
   - audit loop
   - comment loop
   - audit loop sim
   - goal loop
   - north-star investigation
   - flow-status / "what's next?"
3. Read `references/boundary-examples.md` when a nearby lookalike needs sharper comparison.
4. Recommend the best-fit skill and explain why nearby skills are worse fits.

## Workflow

1. Decide what the user needs:
   - quick tour
   - compare two or more subskills
   - recommend the best-fit skill for a concrete task
2. Map the task to the suite:
   - broad full arch planning, implementation, or implementation audit -> `arch-step`
   - faster full arch planning, implementation, or implementation audit for smaller well-defined features -> `miniarch-step`
   - docs cleanup, stale-doc consolidation, or post-arch plan/worklog retirement -> `arch-docs`
   - one-pass canonical mini plan -> `arch-mini-plan`
   - small 1-3 phase feature -> `lilarch`
   - bug, regression, crash, or Sentry issue -> `bugs-flow`
   - repo-wide explanation hardening, high-value code comments, or map-first convention/gotcha comments -> `comment-loop`
   - repo-wide audit pass, systematic defect hunt, or leave-it-running cleanup loop -> `audit-loop`
   - repo-wide real-app automation audit loop with a simulator ledger -> `audit-loop-sim`
   - open-ended goal where the path is unknown -> native goal mode
   - quant-heavy investigation with ranked hypotheses -> `north-star-investigation`
   - read-only checklist or next-step routing on an arch doc -> `arch-flow`
3. Answer with:
   - the primary recommendation
   - a short why
   - the nearest lookalike and why it is not the default
4. If the user says to proceed, stop guiding and switch to the recommended workflow.

## Output expectations

- Keep the explanation short and decision-oriented.
- Prefer:
  - one recommended skill
  - one alternate when ambiguity is real
  - a one-line "use this when / not that" distinction
- If the user asked for a tour, summarize the suite without dumping the whole repo history.

## Reference map

- `references/skill-map.md` - the arch suite decision map, comparison table, and example asks
- `references/boundary-examples.md` - near-lookalike examples and the exact line between them