| name | aiwg-utils-quickref |
| description | AUTO-INVOKE for ANY AIWG capability question, framework/addon/extension query, steward routing, MCP profile, or when unsure where to start. ALWAYS consult before filesystem search on .claude/.factory/.codex/.warp/etc. AIWG core utilities quick reference — always-on framing, steward, index, meta operations. |
| platforms | ["codex"] |
AIWG Core Utilities — Quick Reference
This is your always-loaded core directory for AIWG. It does not list every utility skill. Instead, it teaches the cross-cutting domains and gives you curated search phrases that map to aiwg discover lookups, plus a list of which framework-specific quickrefs are loaded.
How to use this quickref
Walk the action hierarchy in order. The agent always prefers a skill over a raw CLI invocation:
- Priority 1 — Local skill or agent: check if a skill already in your context handles the need (kernel skills listed below, framework quickrefs, deployed agents like
aiwg-steward / aiwg-finder). These cost nothing to invoke.
- Priority 2 — Discovered skill: if no local match, pick a curated phrase from a capability domain (or paraphrase the user's words), run
aiwg discover "<phrase>", surface the top match, and fetch its body with aiwg show <type> <name> — never find / ls / Read.
- Priority 3 — Raw CLI: only when no skill exists at priorities 1 or 2, OR the command is on the discovery surface (
aiwg discover, aiwg show, aiwg list, aiwg version, aiwg runtime-info), OR you are inside a skill that's calling the CLI as its step.
Do not enumerate skills from memory. AIWG ships hundreds of skills; you only see the kernel set in your context. See the cli-secondary rule for the full hierarchy and per-command pairings.
The canonical pipeline: discover → show
Most AIWG skills (~385 of 400) are not in your context and are not in <provider>/skills/ either — they stay at $AIWG_ROOT (no per-project copy by default, #1217). Two commands close the loop:
aiwg discover "<the user's need, paraphrased>"
aiwg show skill <name>
discover and show are designed to compose. You should never need to navigate the filesystem to read AIWG content. That's the whole point of the CLI.
When the platform Skill tool errors
Most AIWG skills aren't kernel-listed, so the platform's Skill tool will reject them. This is expected behavior, not a bug. The fallback hierarchy:
aiwg show <type> <name> — primary fetch. Always works regardless of kernel status.aiwg show <type> <name> --json — same fetch with { path, content } envelope, useful for forwarding to a sub-agent.- Read directly from
$AIWG_ROOT/agentic/code/ — last-resort fallback. Only if the aiwg CLI itself is broken. The corpus at $AIWG_ROOT/agentic/code/frameworks/<name>/skills/<skill>/SKILL.md and $AIWG_ROOT/agentic/code/addons/<name>/skills/<skill>/SKILL.md is the canonical source — it is always present at the install root and survives any deploy-state corruption.
Forbidden after discover returns a path: running find, ls, Glob, or Read on a <provider>/skills/ directory. Those reflect the kernel-pivot deploy state, not the full surface. Use aiwg show.
This is mandated by the skill-discovery HIGH rule. Surface the top match (or top-3) to the user — the search is auditable.
Framework quickrefs (loaded if framework is installed)
If a user asks about a specific framework's surface, the corresponding quickref is your first stop. These are kernel-resident, so they're already in your context:
sdlc-quickref — software-development-lifecycle workflowsforensics-quickref — incident response and digital forensicsresearch-quickref — research corpus and citation workflowsmedia-curator-quickref — media archive managementmarketing-quickref — marketing operations and campaignsops-quickref — operational infrastructure and runbookssecurity-engineering-quickref — applied security and crypto decisionsknowledge-base-quickref — wiki and documentation workflows
If a quickref isn't loaded, the framework isn't installed in this project. Use aiwg list to confirm.
Addons & extensions (separate kernel quickref)
For everything outside the framework set — the ~270 skills across 28 addons (loops, voice, memory, color, testing, NLP, etc.) and 7 ops extensions (sys/net/sec/dev/it/stream/api-adapter) — load aiwg-language-map. It's also kernel-resident and acts as the orientation layer for the addon/extension surface, with curated discover phrases per capability domain.
aiwg-language-map → addon capability domains + extension domains + cheat sheet
Self-maintenance kernel (always loaded)
These ops skills are kernel-resident — already in your context regardless of aiwg discover. They are your primary surface for self-maintenance. Each skill carries the priming the bare CLI cannot — pre-flight checks, dry-run preview, preservation logic, recovery patterns.
Skills first, CLI second. Each row below shows what the skill is for and the CLI command it calls under the hood. Invoke the skill — let it call the CLI. Direct CLI invocation skips the priming and is acceptable only on the discovery surface (Rule 2 of cli-secondary). See cli-secondary rule for the full policy.
| Skill (preferred) | Purpose | CLI it wraps |
|---|
steward | Provider capability awareness + command routing | (no single CLI — orchestrates several) |
aiwg-doctor | Installation health check + remediation | aiwg doctor |
aiwg-refresh | Update CLI + redeploy frameworks with dry-run preview | aiwg refresh (alias: aiwg sync) |
aiwg-regenerate | Regenerate AIWG.md + AGENTS.md preserving team directives | aiwg regenerate |
aiwg-status | Workspace status dashboard | aiwg status |
aiwg-help | List CLI commands, args, examples | aiwg help |
aiwg-issue | Filing AIWG project issues (template, env, duplicate detection) | (no single CLI) |
aiwg-pr | Opening high-quality PRs (delivery-policy, no-attribution, CI gate) | (no single CLI) |
use | Deploy a framework or addon with validation gates | aiwg use <name> |
Pair with the aiwg-steward agent (always-deployed) for orchestrated repair: health check → refresh → re-doctor.
Discovery commands stay direct — aiwg discover, aiwg show, aiwg list, aiwg version, aiwg runtime-info, status/info subcommands. They have no paired "priming skill" because they ARE the priming entry points.
Status intent disambiguation
Route these phrases carefully:
| User intent | Use |
|---|
| Workspace inventory, installed frameworks, deployed provider files | aiwg-status / aiwg status |
| Cross-framework project progress, "project-status", "where are we?", "what is next?" | aiwg discover "project status" → aiwg show skill project-status --first |
| SDLC-specific project health or lifecycle gate status | aiwg discover "SDLC project health check" and prefer project-health-check or orchestrate-project when those rank above generic workspace inventory |
Do not answer project-status by running only aiwg status; that command reports workspace install/deployment inventory, not project progress.
When a user wants to file an issue or open a PR, route them through aiwg-issue / aiwg-pr first. Both are kernel skills (in context) and reference steward-prep-delivery (which provides a runnable duplicate-detection helper).
aiwg-* skills are AIWG-specific product/workspace capabilities. Do not route general tracker processing through aiwg-issue: use issue-audit / audit-issues for backlog audits and address-issues for implementation loops.
Capability domains
| Domain | Covers |
|---|
| Workspace status & health | Workspace inventory, project status, doctor, version, runtime info |
| Lookup & query | Capability discovery, KB query, artifact lookup, AIWG help |
| Maintenance | Refresh, deploy, hooks, regenerate context files |
| Mentions & traceability | @-mention validation, lint, wiring across files |
| Activity & provenance | Activity log, provenance records |
| Steward & policy | Provider capability awareness, delivery policy |
Curated discovery phrases
Workspace status & health
aiwg discover "aiwg status"
aiwg discover "aiwg doctor"
aiwg discover "version"
aiwg discover "runtime info"
aiwg discover "project status"
aiwg discover "SDLC project health check"
aiwg discover "workspace health"
Lookup & query
aiwg discover "<capability phrase>"
aiwg discover "aiwg help"
aiwg discover "search aiwg knowledge base"
aiwg discover "artifact lookup"
aiwg discover "intake wizard"
Maintenance
aiwg discover "aiwg refresh"
aiwg discover "deploy framework"
aiwg discover "regenerate claude.md"
aiwg discover "regenerate AGENTS.md"
aiwg discover "hook enable"
aiwg discover "hook disable"
aiwg discover "hook status"
Mentions & traceability
aiwg discover "mention validate"
aiwg discover "mention lint"
aiwg discover "mention wire traceability"
aiwg discover "mention conventions"
aiwg discover "mention report"
Activity & provenance
aiwg discover "activity log"
aiwg discover "create provenance record"
aiwg discover "auto provenance"
Steward & policy
aiwg discover "aiwg steward"
aiwg discover "delivery policy"
Project-local extensions (pilot → promote)
AIWG supports authoring rules/skills/agents per-project under .aiwg/{extensions,addons,frameworks,plugins}/<name>/ — pilot here, promote upstream when mature.
aiwg new-bundle <name>
aiwg new-extension <name> --starter rule
aiwg new-bundle <name> --dry-run
aiwg list --project-local
aiwg doctor --project-local
aiwg use <name>
aiwg promote <name>
aiwg promote <name> --dry-run
After scaffolding, the new bundle is immediately discoverable via aiwg discover "<name>". The framework graph and the project graph search by default; no --graph flag needed.
On-disk layout
agentic/code/ ← framework + addon source (NOT deployed; read-only reference)
.aiwg/ ← project artifacts (use cases, ADRs, test plans, etc.)
.claude/skills/ ← always-loaded "kernel" skills (this skill is here)
.claude/.aiwg/skills/ ← bulk AIWG skills (index-discoverable, not flat-listed)
.claude/agents/ ← AIWG agents (platform-native)
.claude/commands/ ← Generated command stubs for tab completion
.claude/rules/ ← AIWG rules
Same shape on every supported provider — see docs/discovery-and-kernel-skills.md for the full per-provider table.
When to query the index versus answer from kernel
| Situation | Action |
|---|
| User asks "what can AIWG do?" generically | Skim the framework quickrefs above; offer the top 3 most-relevant. |
| User asks "find me a skill that does X" | aiwg discover "X" — return ranked candidates. |
| User asks "is there a skill for Y?" and it's not in any quickref | aiwg discover "Y" — don't say "no" without checking. |
| User asks about a specific framework's catalog | Direct them to that framework's quickref + invite a discover query. |
| User asks for AIWG version / config / status | aiwg version, aiwg-status, aiwg doctor. |
When the curated phrases don't fit
aiwg discover "<your need, paraphrased>" --limit 5
If the top-3 results all score below ~0.20, the framework genuinely may not have a curated skill. Then improvise — but always check first.
Anti-patterns
- Do not enumerate skills from memory. Query the index.
- Do not deploy or modify framework source. Files under
agentic/code/ are read-only references; project work happens in .aiwg/ and any src/ directories the project owns.
- Do not bypass the steward for cross-provider questions. If the user asks "does this work on Codex?" or "deploy to Cursor", invoke the AIWG Steward — it has the provider-capability matrix you don't.
- Do not fabricate skill names. If
aiwg discover doesn't return a match, the skill genuinely may not exist — say so.
When you don't know what to do
aiwg help
aiwg discover "<your need>"
aiwg-kb "<question>"
If still stuck, ask the user — but ask narrowly, with options drawn from the index, not blank.
