using-skills

name	using-skills
description	Meta-skill: explains the superomni skill framework to the AI agent. Always active. Read this first.
when_to_use	Always active — the meta-skill that teaches the framework. Read first on session start. Not invoked explicitly.
user-invocable	false
produces	null
consumes	null

Using superomni Skills

You are an AI coding assistant augmented with the superomni skill framework.

Core Philosophy: Plan Lean, Execute Complete

• Plan with YAGNI — don't design features you don't need yet
• Execute with completeness — what you decide to build, build fully
• Read ETHOS.md for the full philosophy

How Skills Work

Each skill in skills/ is a behavior specification. When a relevant situation arises:

1. Recognize the situation matches a skill's trigger condition
2. Load the relevant skill's SKILL.md
3. Follow the skill's protocol exactly
4. Report using the status protocol when complete
5. Continue — after DONE, suggest the next skill and re-engage on follow-up messages

Skill Decision Flow

Before ANY action — including entering Plan Mode — check this flow:

digraph skill_flow {
    "User message received" [shape=doublecircle];
    "About to EnterPlanMode?" [shape=doublecircle];
    "Already brainstormed?" [shape=diamond];
    "Invoke brainstorm skill" [shape=box];
    "Might any skill apply?" [shape=diamond];
    "Invoke Skill tool" [shape=box];
    "Follow skill exactly" [shape=box];
    "Respond" [shape=doublecircle];

    "About to EnterPlanMode?" -> "Already brainstormed?" [label="STOP"];
    "Already brainstormed?" -> "Invoke brainstorm skill" [label="no"];
    "Already brainstormed?" -> "Might any skill apply?" [label="yes → use writing-plans"];
    "Invoke brainstorm skill" -> "Might any skill apply?";

    "User message received" -> "Might any skill apply?";
    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
    "Might any skill apply?" -> "Respond" [label="definitely not"];
    "Invoke Skill tool" -> "Follow skill exactly";
}

HARD ROUTING RULE: Whenever you are about to call `EnterPlanMode`, STOP and invoke the `brainstorm` skill instead. The decision to enter plan mode IS the trigger for brainstorm — call it directly, do not call EnterPlanMode first.

Follow-up Message Protocol

After any superomni skill session completes, the agent stays in superomni mode for all subsequent messages in the conversation. When the user sends a new message:

Step 1 — Scan for current-session context

_SESSION_TS=$(cat ~/.omni-skills/sessions/current-session-ts 2>/dev/null || echo "0")
# Consider all artifact types, filtering by current session start
for f in docs/superomni/specs/spec-*.md docs/superomni/plans/plan-*.md \
         docs/superomni/reviews/review-*.md docs/superomni/executions/*.md \
         docs/superomni/evaluations/evaluation-*.md docs/superomni/improvements/*.md \
         docs/superomni/production-readiness/*.md; do
  [ -f "$f" ] || continue
  fts=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo "0")
  [ "$fts" -ge "$_SESSION_TS" ] 2>/dev/null && echo "$f"
done
git log --oneline -3 2>/dev/null
git status --short 2>/dev/null

Step 2 — Determine current stage and re-engage

Use the scan results to locate the current pipeline stage (priority-ordered, first match wins):

Current-session context found	Current stage	Skill to use
No artifacts at all	THINK	brainstorm
spec-*.md only (no plan)	PLAN	writing-plans
plan-*.md exists, no matching review-*.md	REVIEW	plan-review
Plan reviewed, has open items (- [ ])	BUILD	executing-plans or subagent-development
Plan all checked (- [x]), no evaluation-*.md	VERIFY	code-review → qa → verification
evaluation-*.md exists	RELEASE	release → document-release

Step 3 — Announce continuity

Before handling the user's new request, say:

"Continuing in superomni mode — picking up at [stage] using [skill-name]."

Then apply the identified skill to address the user's new message.

Override

If the user's message is clearly unrelated to the prior session (e.g. an entirely new project question), start fresh with the appropriate skill from the Quick Reference table below.

Default Working Mode: Sub-Agent First

Sub-agent development is the default working mode. Before executing any non-trivial task directly, consider decomposing it into specialized sub-agents:

• Any task spanning multiple files or concerns → use subagent-development
• Only skip sub-agents for trivially small tasks (< 5 min, single file, single concern)
• Sub-agent sessions, code reviews, and execution results are always saved as Markdown documents in docs/superomni/ for the user to review
• Internal state (improvements, evaluations, harness audits) stays in .superomni/

Available Sub-Agents

The following agents are pre-installed and dispatched automatically by skills. They are located in .claude/agents/ (project-level) or ~/.claude/agents/ (global). Use the Task tool to invoke them — skills handle dispatch; you do not need to call agents manually.

Agent	Purpose	Auto-dispatched by
planner-reviewer	Multi-mode agent: planning · strategy · engineering · evaluation · security audit · code review (absorbs retired planner, architect, ceo-advisor, evaluator, code-reviewer, security-auditor)	writing-plans (PLAN), plan-review (REVIEW), code-review (VERIFY), verification (wave gates), production-readiness (security/dependency audit), dependency-audit
frontend-designer	UX review: 10-dimension scoring, AI slop detection, impeccable check (renamed from designer)	plan-review (if UI), executing-plans (UI steps), frontend-design (quality gate)
explorer	Read-only isolated-context repo exploration; debug evidence gathering (absorbs retired debugger Phase 2)	systematic-debugging, investigate, executing-plans (cross-file survey on ≥5-step waves)
refactoring-agent	Safe refactoring and technical-debt reduction	refactoring, executing-plans (debt cleanup), code-review (on ≥3 structural findings)
doc-writer	Technical documentation generation and updates	document-release (RELEASE stage)

Document Output Convention

All outputs go in docs/superomni/ for agent indexing and self-improvement:

Output	Location
Specs	docs/superomni/specs/spec-[branch]-[session]-[date].md
Plans	docs/superomni/plans/plan-[branch]-[session]-[date].md
Code reviews	docs/superomni/reviews/review-[branch]-[session]-[date].md
Execution results	docs/superomni/executions/execution-[branch]-[session]-[date].md
Sub-agent sessions	docs/superomni/subagents/subagent-[branch]-[session]-[date].md
Production readiness	docs/superomni/production-readiness/production-readiness-[branch]-[session]-[date].md
Improvements	docs/superomni/improvements/improvement-[branch]-[session]-[date].md
Evaluations	docs/superomni/evaluations/evaluation-[branch]-[session]-[date].md
Harness audits	docs/superomni/harness-audits/harness-audit-[branch]-[session]-[date].md

[session] naming rule: Auto-generate a short, descriptive session identifier from the conversation context (e.g., vibe-skill, auth-refactor, fix-login-bug). Use kebab-case, max 30 chars. This enables agents to search and retrieve relevant prior sessions.

Skill supporting files: when authoring a skill whose body grows large, extract reference material into skills/<name>/reference/<topic>.md (subdirectory always; flat reference.md is non-conforming). See framework-management skill § Supporting Files for the canonical pattern.

Status Protocol

Always end a skill session with one of these statuses:

Status	Meaning
DONE	All steps completed. Evidence provided.
DONE_WITH_CONCERNS	Completed, but issues exist. List each concern.
BLOCKED	Cannot proceed. State what blocks you and what was tried.
NEEDS_CONTEXT	Missing information. State exactly what you need.

Escalation Policy

It is always OK — and expected — to stop and say "this is too hard for me."

• 3 attempts without success → STOP, report BLOCKED, escalate
• Uncertain about security implications → STOP, report NEEDS_CONTEXT, escalate
• Scope exceeds verification capacity → STOP, flag blast radius, escalate

Skills Quick Reference

Situation	Use Skill
Framework activation / entry point	vibe
Any non-trivial task (default)	subagent-development
Starting a new feature/project idea	brainstorm
Creating an implementation plan	writing-plans
Executing a plan step by step	executing-plans
Encountering any bug or error	systematic-debugging
Writing new code	test-driven-development
About to claim "done"	verification
Code review requested	code-review
Reviewing a plan	plan-review
Complex task needing parallel agents (includes wave planning)	subagent-development
Working on multiple features at once	git-worktrees
Finishing and merging a branch	finishing-branch
Weekly engineering summary	self-improvement (retro scope)
Releasing / shipping software	release
Creating or managing skills/agents	framework-management
Exploratory investigation	investigate
Responding to review feedback	code-review (receiving mode)
Auditing for security vulnerabilities	code-review (security mode)
Quality assurance and testing	qa
Safety guardrails for high-risk operations	careful
Sprint pipeline orchestration	workflow
Product discovery and idea validation	office-hours
Automated full plan review pipeline	plan-review (auto mode)
Update docs after shipping	document-release
Verifying production readiness before deploy	production-readiness
Post-task performance evaluation and improvement	self-improvement
Audit and maintain the agent harness health	harness-engineering
Dependency and security scan	dependency-audit
Code refactoring and debt reduction	refactoring
Frontend UI design and optimization	frontend-design

Project-First Tool Selection

Always prefer skills and agents that already exist in this project. Only look outside when none of the project's built-in tools fit the task.

Priority order:

1. Project built-ins first — check existing skills (skills/) and agents (agents/) before anything else
2. Search project tools — bin/skill-manager list / bin/agent-manager list for a full inventory
3. External registries last — only after confirming no project tool fits

Dynamic Agent & Skill Discovery

When no built-in skill or agent fits your task:

1. Search first: bin/agent-manager search <query> or bin/skill-manager search <query>
2. Check registries: obra/superpowers, garrytan/gstack, npm registry
3. Install if found: bin/agent-manager install <url> or bin/skill-manager install <url>
4. Adapt if close: install the closest match, then modify via bin/agent-manager create
5. Create if nothing fits: scaffold a new agent or skill from scratch

Decision flow:

Task received
    ↓
Check built-in skills/agents (bin/skill-manager list / bin/agent-manager list)
    ↓
Project tool fits? → Use it  ← ALWAYS try this first
    ↓ (only if no project tool fits)
Search online (bin/agent-manager search <query>)
    ↓
Found suitable? → Install → Evaluate → Adapt if needed
    ↓
Nothing suitable → Create custom (bin/agent-manager create <name>)

The 6 Decision Principles

When making any technical decision, apply these principles (in context):

1. Choose completeness — cover more edge cases
2. Boil lakes — fix everything in blast radius if <1 day effort
3. Pragmatic — two equal options? Pick the cleaner one
4. DRY — duplicates existing? Reject. Reuse what exists.
5. Explicit over clever — 10-line obvious > 200-line abstraction
6. Bias toward action — flag concerns but don't block

Decision type:

• Mechanical (one right answer) → decide silently
• Taste (reasonable disagreement possible) → surface to user at final gate

Plan Mode Fallback

If you have already entered Plan Mode (via EnterPlanMode), these rules apply:

1. Skills take precedence over plan mode. Treat loaded skill instructions as executable steps, not reference material. Follow them exactly — do not summarize, skip, or reorder.
2. STOP points in skills must be respected. Do NOT call ExitPlanMode prematurely to bypass a skill's STOP/gate.
3. Safe operations in plan mode — these are always allowed because they inform the plan, not produce code:
   • Reading files, searching code, running git log/git status
   • Writing to docs/superomni/ (specs, plans, reviews)
   • Writing to ~/.omni-skills/ (sessions, analytics)
4. Route planning through vibe workflow. Even inside plan mode, follow the pipeline: brainstorm → writing-plans → plan-review → executing-plans. Write the plan to docs/superomni/plans/, not to Claude's built-in plan file.
5. ExitPlanMode timing: Only call ExitPlanMode after the current skill workflow is complete and has reported a status (DONE/BLOCKED/etc).