ultra-agent-skill

⚡ Ultra Skill v4.0 — The Autonomous AI Powerhouse

One skill to rule them all. Unifying 11 elite AI agent systems into an orchestrated, self-routing agentic powerhouse with specialized subagent personas, formal state-machine execution, executable workflows, interactive architecture visualization, resilient error recovery, deep reference archives, and ironclad verification gates.

---

📑 Table of Contents

• Overview & The Unified Vision
• The 6-Phase Agentic State Machine
• Specialized Subagent Roles & Personas
• Actionable Workflows Map
• Deep Reference Archives
• The 13 Unified Modules Matrix
• Slash Command Routing Table
• Core Feature Deep Dive
  • 1. AI Agent & Graph Workflow Engineering (ADK 2.0)
  • 2. Interactive Architecture Visualization (Archify)
  • 3. Lazy-Efficient Coding (Ponytail)
  • 4. Anti-Slop Frontend Design (Taste)
  • 5. Professional Animation Engines (GSAP & Motion Design)
  • 6. Systematic Debugging & TDD Discipline
  • 7. Verification Before Completion
  • 8. Implementation Planning & Live Progress Tracking
• Automation & Verification Utilities
• Directory & Repository Structure
• Installation & Multi-Platform Setup
• Pre-Flight Quality Checklist
• Cookbook & Real-World Recipes
• License & Sources

---

🌟 Overview & The Unified Vision

Modern AI agent workflows suffer from fragmentation and tool sprawl:

• You load one skill for writing tests, but it creates bloated boilerplate code.
• You ask an agent to build a landing page, and it generates generic "AI slop" with purple gradients, standard Inter typography, and three identical cards.
• You design animations, but they end up linear, laggy, or inaccessible.
• You build complex architectures, but lack clean, interactive system diagrams to explore them.
• You orchestrate agent systems with fragile monolithic prompts instead of deterministic state graphs.

Ultra Skill v3.1 solves this by establishing a deterministic, autonomous agentic workflow that unifies 11 best-in-class open-source agent patterns into a coherent operating system.

---

🧭 The 6-Phase Agentic State Machine

Every user request transitions through this deterministic 6-phase state machine:

[USER PROMPT]
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 0: INTAKE & INTENT ROUTING                       │
│ • Parse request & detect domain / slash-command        │
│ • Bind active subagent personas & reference manuals     │
└────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 1: RECONNAISSANCE & EVIDENCE GATHERING           │
│ • Audit existing codebase, dependencies, & type specs   │
│ • Formulate Design Read (Frontend) or Trace Log (ADK)  │
└────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 2: MANDATORY PLAN & PROGRESS CHECKLIST (IRON LAW)│
│ • When any new plan starts: Author Implementation Plan │
│ • Synthesize interactive markdown checklist (- [ ])    │
│ • NO CODE CHANGES BEFORE PLAN & CHECKLIST!             │
│ • Live progress tracking (- [x]) as steps verify       │
└────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 3: SUBAGENT EXECUTION LOOP                       │
│ • Dispatch @architect, @visualizer, @engineer, etc.    │
│ • Apply Ponytail Ladder (shortest working diff)        │
│ • Enforce strict TDD (Red-Green-Refactor)              │
└────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 4: AUTONOMOUS REVIEW & SELF-CORRECTION           │
│ • CodeRabbit triage (Critical -> Info) & secret scan   │
│ • Detect AI slop (detect_ai_slop.py) & contrast audit  │
│ • Archify layout checks (crossovers & geometry)        │
└────────────────────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────┐
│ STATE 5: GATE-FUNCTION VERIFICATION (MANDATORY)        │
│ • Execute fresh verification command via terminal      │
│ • Assert exit code 0 & zero test failures               │
│ • Output structured completion receipt with proof      │
└────────────────────────────────────────────────────────┘

---

👥 Specialized Subagent Roles & Personas

When operating on complex tasks, Ultra Skill dispatches or role-plays dedicated subagents:

Subagent Role	Focus Area	Superpower & Responsibility	Specification
@planner	Implementation Planning	Zero-context plans, spec synthesis, risk mitigation & interactive progress checklists (- [ ]).	planner.md
@architect	Google ADK 2.0	Graph workflows, multi-agent topologies, dynamic nodes, HITL interrupts, state channels.	architect.md
@visualizer	Archify	Interactive architecture, workflow, sequence, dataflow & lifecycle diagrams (SVG/HTML).	visualizer.md
@engineer	Ponytail	Lazy senior developer mode, YAGNI, stdlib first, shortest diff wins.	engineer.md
@designer	Taste + Design DNA	Anti-slop frontend aesthetics, 3 dials, layout rules, typography & color locks.	designer.md
@animator	GSAP + Motion Design	60fps GPU animations, 3 motion layers, ScrollTrigger, prefers-reduced-motion.	animator.md
@debugger	Systematic Debugging	4-phase root-cause investigation, boundary logs, 3-fix circuit breaker.	debugger.md
@tester	Test-Driven Development	Red-Green-Refactor enforcement; no production code without failing tests.	tester.md
@reviewer	CodeRabbit Review	Autonomous security scan, secret hygiene, severity triage (Critical → Info).	reviewer.md
@verifier	Gatekeeper Verification	5-step gate function, command execution verification, exit code 0 assertion.	verifier.md

---

📋 Actionable Workflows Map

Standardized step-by-step procedures located in workflows/:

1. 01: ADK 2.0 Graph & Multi-Agent Orchestration — Production graph workflows, dynamic loops, and HITL
2. 02: Subagent-Driven Development & Parallel Dispatch — Task decomposition, parallel dispatch & conflict resolution
3. 03: Anti-Slop Frontend Design — Taste-driven, anti-slop landing pages & UI components
4. 04: Cinematic Motion Choreography & Animation — GSAP timelines, ScrollTrigger & 3-layer motion design
5. 05: Systematic Root-Cause Debugging — 4-phase debugging & 3-fix circuit breaker
6. 06: Test-Driven Development (TDD) — Red-Green-Refactor pipeline
7. 07: Autonomous Code Review & Security Audit — Automated security scan & severity-based triage
8. 08: Design DNA Extraction & Style Transfer — Style quantization from URLs/images into CSS tokens
9. 09: Brand Asset Production (UI/UX Pro Max) — Logos, banners, slides, and 3-tier tokens
10. 10: Gate-Function Verification Before Completion — 5-step gate function before announcing task success
11. 11: Interactive Architecture Visualization (Archify) — Archify interactive HTML system, workflow & sequence diagrams
12. 12: Implementation Planning & Progress Checklists — Mandatory plan authoring & real-time progress checklist tracking
13. 13: Error Recovery & Graceful Degradation — Transient retries, circuit breaker tripping & atomic workspace rollback
14. 14: Performance Profiling & Optimization — Core Web Vitals, bundle analyzer & 60fps frame rate budgets
15. 15: Skill Implementation & Proper .agents Folder Arrangement — Automated installer & standardized .agents directory layout

---

📚 Deep Reference Archives

Comprehensive manuals, patterns, and design catalogs bundled in skills/ultra-skill/references/:

• references/archify/ — Archify CLI engine (bin/archify.mjs), 5 diagram schemas, recipes, brand marks.
• references/adk/ — 11 packages: agent builder, architecture, debug, git, review, sample creator, setup, style, unit design, unit guide, verify snippets.
• references/superpowers/ — Subagent-driven dev, parallel dispatch, systematic debugging, TDD, verification gates, writing plans.
• references/taste/ — Anti-slop guidelines, brandkit, minimalist, brutalist, soft design, redesign skill, image-to-code.
• references/ponytail/ — Lazy developer ladder, code audit, technical debt elimination, review rules.
• references/gsap/ — Core API, timelines, ScrollTrigger, performance tuning, React/framework integration, utility helpers.
• references/motion-design/ — Motion director guide, choreography, Disney principles, emotion mapping, timing tables.
• references/design-dna/ — 3D schema, generation guide, color math, verification scripts.
• references/ui-ux-pro-max/ — 55+ logo styles, 22 banner formats, corporate identity templates, design tokens.
• references/coderabbit/ — Code review rules, CLI workflows, autonomous autofix loop, security audit rubrics.

---

🧩 The 13 Unified Modules Matrix

Module / Skill	Provenance / Upstream	Primary Superpower & Contribution
§1 Ponytail	DietrichGebert/ponytail	Lazy-Efficient Engineering: Minimal code, YAGNI, standard library first, shortest diff wins.
§2 Taste	Leonxlnx/taste-skill	Anti-Slop Frontend Design: Brief inference, 3 dials (Variance/Motion/Density), typography & color locks.
§3 GSAP Mastery	greensock/gsap-skills	Professional Animation: High-performance sequencing, ScrollTrigger, transform aliases, responsive timelines.
§4 Motion Design	LottieFiles/motion-design-skill	Emotion-Driven Choreography: 3 motion layers (primary/secondary/ambient), micro-interaction timings.
§5 Design DNA	zanwei/design-dna	Visual Identity Pipeline: Extract, quantize, and apply design systems and WebGL/Canvas effects from URLs/images.
§6 Systematic Debugging	obra/superpowers	Root Cause Investigation: 4-phase investigation protocol, hypothesis testing, 3-fix circuit breaker.
§7 TDD	obra/superpowers	Ironclad TDD Discipline: Red-Green-Refactor; no production code without a verified failing test first.
§8 Verification	obra/superpowers	Gate-Function Verification: Fresh command execution evidence before any claim of completion is made.
§9 UI/UX Pro Max	nextlevelbuilder/ui-ux-pro-max-skill	Brand & Production Assets: 55+ logo styles, CIP for 20 industries, social banners, 3-tier token architecture.
§10 Code Review	coderabbitai/skills	Autonomous Review & Triage: Severity-rated findings (Critical → Info), secret hygiene, automated review loop.
§11 Implementation Planning	obra/superpowers	Zero-Context Engineering Plans: Exact file paths, precise method signatures, atomic TDD task steps.
§12 Performance Guardrails	greensock/gsap-skills	Performance Engineering: Hardware transforms only, 60fps budgets, prefers-reduced-motion, Core Web Vitals (LCP < 2.5s, INP < 200ms, CLS < 0.1).
§13 Accessibility Checklist	obra/superpowers	Inclusive Web Quality: WCAG AA/AAA contrast ratios, focus styles, keyboard navigation, reduced-motion fallbacks, semantic markup.
§14-17 Google ADK 2.0	google/adk-python	Enterprise Agent & Graph Workflows: Directed graph scheduling, fan-out/fan-in, dynamic nodes, HITL, headless diagnostics.
§18 Archify	tt-a1i/archify	Interactive Architecture Visualization: 5 diagram modes, Mermaid conversion, standalone HTML with SVG & trace motion.

---

⚡ Slash Command Routing Table

Slash Command / Intent	Active Subagents	Workflows & Modules Activated
/diagram or /archify	@visualizer	Workflow 11 + §18 Archify Visualization
/agent or /workflow	@architect, @engineer	Workflow 01 + §14 ADK Workflows + §1 Ponytail
/design or /frontend	@designer, @animator	Workflow 03 + Workflow 04 + §2 Taste + §3 GSAP + §4 Motion
/debug	@debugger, @tester	Workflow 05 + Workflow 06 + §6 Systematic Debugging + §7 TDD
/tdd	@tester, @engineer	Workflow 06 + §7 TDD + §1 Ponytail
/review or /audit	@reviewer, @engineer	Workflow 07 + §10 Code Review + scripts/detect_ai_slop.py
/plan	@planner, @architect	Workflow 12 + Workflow 02 + §11 Implementation Planning & Checklists
/dna	@designer	Workflow 08 + §5 Design DNA
/brand	@designer	Workflow 09 + §9 UI/UX Pro Max
/verify	@verifier	Workflow 10 + §8 Verification + scripts/verify_evidence.py
/recover	@architect, @debugger	Workflow 13 (Error Recovery & Rollback) + §6 Debugging
/perf	@animator, @engineer	Workflow 14 (Performance Profiling) + §12 Performance Guardrails
/install or /implement	@architect, @engineer	Workflow 15 (Skill Implementation & Layout) + scripts/install_skill.py

---

🔬 Core Feature Deep Dive

1. AI Agent & Graph Workflow Engineering (ADK 2.0)

(Powered by Google ADK 2.0 / google/adk-python)

Ultra Skill applies strict software engineering standards to AI agents, replacing fragile prompt chains with deterministic graph workflows.

• Canonical Public Imports:

  from google.adk import Agent, Workflow, Context, Event
  from google.adk.workflow import JoinNode, node
  from google.adk.runners import InMemoryRunner
  

• Graph Workflows & Edge Compilation: Connect deterministic nodes from "START" through branching logic.
• Fan-Out / Fan-In Parallelism: Execute concurrent tasks simultaneously and aggregate them with JoinNode.
• Dynamic Scheduling: Programmatically dispatch nodes at runtime with await ctx.run_node(agent, node_input=...).
• Human-in-the-Loop (HITL) Interrupts: Pause execution for user confirmation with RequestInput(prompt="...", interrupt_id="...").

---

2. Interactive Architecture Visualization (Archify)

(Powered by tt-a1i/archify)

Turn systems, workflows, and code repositories into interactive, explorable HTML visuals:

• 5 Diagram Modes:
  1. architecture: Services, databases, cloud & security boundaries, repository architecture.
  2. workflow: Step-by-step processes, approval gates, tool call paths.
  3. sequence: API call chains, async message traces between services.
  4. dataflow: Pipelines, ETL/ELT flows, data lineage.
  5. lifecycle: State machines, status transitions, retries.
• Mermaid Conversion: Automatically transforms Mermaid (flowchart, sequenceDiagram, stateDiagram) into interactive HTML.
• Standalone HTML Output: Zero external dependencies, embedded inline SVG, dark/light theme switch, zoom/pan controls, optional trace animation, and multi-format export (SVG, PNG, WebP, WebM).
• Validation Engine: Built-in finalize CLI validates schemas, detects overlapping nodes, and fixes layout geometry.

---

3. Lazy-Efficient Coding (Ponytail)

(Powered by DietrichGebert/ponytail)

"The best code is the code never written. Shortest working diff wins."

Ultra Skill adheres to the Lazy Senior Developer Ladder — evaluate every task top-to-bottom and stop at the first rung that satisfies the requirement:

1. Does this need to exist at all? (YAGNI — reject speculative features).
2. Is it already in this codebase? (Reuse existing utilities, types, and components).
3. Does the standard library do it? (Avoid external bloat).
4. Does a native platform feature cover it? (<input type="date"> over heavy JS pickers; CSS over JS; DB constraints over app validations).
5. Does an already-installed package solve it? (Never install a new package for 10 lines of logic).
6. Can it be written in one clear line? (Write that line).
7. Only then: Write the minimum necessary code.

---

4. Anti-Slop Frontend Design (Taste)

(Powered by Leonxlnx/taste-skill)

Ultra Skill completely eliminates generic AI slop from web apps and landing pages.

• Design Read: Declares page kind, vibe, and audience before coding.
• The Three Dials: DESIGN_VARIANCE (1-10), MOTION_INTENSITY (1-10), VISUAL_DENSITY (1-10).
• Hard Invariants:
  • 🚫 No default purple glowing cards (The Lila Rule).
  • 🚫 No Inter default font; use Geist, Outfit, Cabinet Grotesk, or Satoshi.
  • 🚫 Hero section MUST fit inside min-h-[100dvh] with CTA above fold.
  • 🚫 No div-based fake screenshots; use real imagery or Simple Icons SVGs.
  • 🎨 Single accent color per page (saturation < 80%) with locked corner radii.

---

5. Professional Animation Engines (GSAP & Motion Design)

(Powered by greensock/gsap-skills & LottieFiles/motion-design-skill)

• Transform Aliases Only: Always animate x, y, scale, rotation, and autoAlpha. Never animate top, left, width, or height.
• Responsive Animations: Utilize gsap.matchMedia() for responsive layouts and prefers-reduced-motion compliance.
• Three Motion Layers: Primary (focal action), Secondary (accompanying reactions), Ambient (environmental life).
• Easing Semantics: Never linear for spatial moves. Easing curves tailored to the project archetype (Playful, Premium, Corporate, Energetic).

---

6. Systematic Debugging & TDD Discipline

(Powered by obra/superpowers)

• The Iron Law of Debugging: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
  • 4 Phases: Investigate → Pattern Analysis → Hypothesis → Surgical Fix.
  • The 3-Fix Circuit Breaker: Halt immediately if 3 fix attempts fail.
• The Iron Law of TDD: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
  • Red → Verify Red → Green → Verify Green → Refactor.

---

7. Verification Before Completion

(Powered by obra/superpowers)

• The Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
• The 5-Step Gate Function: Identify → Run → Read → Audit → Announce.
• Strictly bans "should work", "probably fixed", or "seems to be working" without attached terminal logs.

---

8. Implementation Planning & Live Progress Tracking

(Powered by obra/superpowers / Workflow 12)

• The Iron Law of Planning: NO CODE CHANGES OR FILE CREATION WITHOUT AN IMPLEMENTATION PLAN AND CHECKLIST FIRST.
• Protocol for Every New Task:
  1. Author a structured Implementation Plan declaring the goal, architecture, tech stack, affected files, interfaces, and constraints.
  2. Generate an interactive Master Checklist with checkable markdown checkboxes (- [ ]).
  3. Live Progress Tracking: As each atomic step completes and passes verification, update the checkbox to - [x].
  4. Zero-Context Clarity: Plans must be executable by an engineer with zero prior codebase knowledge.

---

🛠️ Automation & Verification Utilities

Ultra Skill includes automated diagnostic and verification tools in scripts/:

• Gate Verification Runner (scripts/verify_evidence.py): Runs any test or build command, captures stdout/stderr, verifies exit code 0, and prints a structured pass/fail verdict or machine-parseable JSON receipt. Supports saving receipts to .verification/ and custom timeouts.

  python scripts/verify_evidence.py --json --save .verification/receipt.json "pytest tests/"
  

• AI Slop Detector & Fixer (scripts/detect_ai_slop.py): Audits HTML, CSS, JSX, and TSX files for generic AI design tropes (Inter font defaults, purple gradients, h-screen viewport bugs, fake browser divs, lorem ipsum copy, white-on-white CTAs, generic serifs, three-card triplets). Supports --fix recommendations, --json, and .slopignore.

  python scripts/detect_ai_slop.py ./src --fix --min-severity WARNING
  

• WCAG Contrast Checker (scripts/contrast_checker.py): Automated relative luminance and contrast ratio calculator supporting direct color evaluation (hex/rgb/named) and batch scanning of CSS/HTML/Tailwind files against WCAG AA (4.5:1 / 3:1) and AAA (7:1) criteria.

  python scripts/contrast_checker.py "#ffffff" "#0f172a" --json
  python scripts/contrast_checker.py ./src
  

• Implementation Plan Validator (scripts/plan_validator.py): Validates implementation plan markdown against §11 schema requirements (Goal, Architecture, Tech Stack, Affected Files, Master Checklist), enforces - [ ] syntax, checks file existence on disk, and warns if task count exceeds 20.

  python scripts/plan_validator.py plan.md --workspace . --json
  

• ADK Trace Inspector (scripts/adk_trace_inspector.py): Parses JSONL event streams from adk run --jsonl, extracts tool calls, verifies schema fidelity, tracks tool latency (warning on >5s), estimates token usage, and supports --filter-tool filtering.

  adk run --jsonl my_agent "Query" | python scripts/adk_trace_inspector.py --filter-tool query_knowledge_base
  

• Archify Finalizer CLI: Validates candidate diagram JSON and compiles interactive standalone HTML.

  node skills/ultra-skill/references/archify/bin/archify.mjs finalize architecture candidate.json output.html --quality showcase --json
  

---

📂 Directory & Repository Structure

ultra-skill/
├── AGENTS.md                  # Universal agent behavior rules & subagent registry
├── CLAUDE.md                  # Claude Code integration pointer
├── GEMINI.md                  # Gemini CLI integration pointer
├── README.md                  # This master documentation
├── .gitignore                 # Standard Python, IDE, and log ignore rules
├── agents/                    # Specialized subagent personas
│   ├── planner.md             # @planner: Zero-context plans & checklists
│   ├── architect.md           # @architect: ADK 2.0 graph builder
│   ├── visualizer.md          # @visualizer: Archify interactive diagrams
│   ├── engineer.md            # @engineer: Ponytail lazy senior dev
│   ├── designer.md            # @designer: Taste & Design DNA creator
│   ├── animator.md            # @animator: GSAP & Motion choreographer
│   ├── debugger.md            # @debugger: 4-phase root cause investigator
│   ├── tester.md              # @tester: TDD quality enforcer
│   ├── reviewer.md            # @reviewer: CodeRabbit security auditor
│   └── verifier.md            # @verifier: Gatekeeper evidence inspector
├── workflows/                 # Executable agentic workflow guides
│   ├── 01-agent-graph-orchestration.md
│   ├── 02-subagent-driven-development.md
│   ├── 03-anti-slop-frontend-design.md
│   ├── 04-cinematic-motion-choreography.md
│   ├── 05-systematic-root-cause-debugging.md
│   ├── 06-test-driven-development.md
│   ├── 07-autonomous-code-review.md
│   ├── 08-design-dna-extraction.md
│   ├── 09-brand-asset-production.md
│   ├── 10-gate-function-verification.md
│   ├── 11-interactive-architecture-visualization.md
│   ├── 12-implementation-planning-and-checklists.md
│   ├── 13-error-recovery-and-graceful-degradation.md
│   ├── 14-performance-profiling-and-optimization.md
│   └── 15-skill-implementation-and-installation.md
├── scripts/                   # Automated quality, installation and verification tools
│   ├── install_skill.py       # Automated .agents folder installer & layout manager
│   ├── verify_evidence.py     # Gate-function test & build verifier (JSON + save)
│   ├── detect_ai_slop.py      # Frontend AI design anti-slop auditor & fixer
│   ├── contrast_checker.py    # Automated WCAG AA/AAA contrast ratio auditor
│   ├── plan_validator.py      # Implementation plan §11 schema validator
│   └── adk_trace_inspector.py # Headless ADK JSONL trace & latency triage
├── tests/                     # Unit test suites for scripts
│   ├── test_install_skill.py
│   ├── test_detect_ai_slop.py
│   ├── test_verify_evidence.py
│   ├── test_contrast_checker.py
│   ├── test_plan_validator.py
│   └── test_adk_trace_inspector.py
├── CHANGELOG.md               # Version history and migration notes
├── LICENSE                    # MIT License
└── skills/
    └── ultra-skill/           # 100% Self-contained distributable bundle
        ├── SKILL.md           # Master skill definition & full instruction manual
        ├── agents/            # Bundled subagent persona markdown specs
        ├── workflows/         # Bundled workflow execution guides (01-15)
        ├── scripts/           # Bundled Python quality & verification scripts
        └── references/        # Deep reference archives from all 11 upstream systems
            ├── archify/       # Archify CLI engine, 5 diagram schemas, recipes
            ├── adk/           # 11 Google ADK 2.0 packages
            ├── superpowers/   # Subagent dev, parallel dispatch, TDD, debugging
            ├── taste/         # Anti-slop, minimalist, brutalist, soft, brandkit
            ├── ponytail/      # Laziness ladder, code audit, debt, review
            ├── gsap/          # Core, scrolltrigger, react, timelines, performance
            ├── motion-design/ # Director guide, choreography, emotion mapping
            ├── design-dna/    # Schema, generation guide, color math
            ├── ui-ux-pro-max/ # Design tokens, logo catalogs, banner specs
            └── coderabbit/    # Review workflows, autofix, CLI tools

---

🚀 Installation & Multi-Platform Setup

⚡ Automated Installation (Recommended)

Ultra Skill includes an automated installer (scripts/install_skill.py) that strictly organizes all files into the standardized .agents/ folder topology, copies the self-contained skill bundle, exposes subagent definitions to .agents/agents/, links rules to .agents/rules/, and establishes project root entrypoints:

# Install to any project workspace
python scripts/install_skill.py /path/to/my-project

# Or install to global user config directory (~/.agents)
python scripts/install_skill.py --global

Canonical Installed .agents Directory Topology:

<project_root>/
├── .agents/
│   ├── skills/
│   │   └── ultra-skill/        # Complete self-contained skill bundle
│   │       ├── SKILL.md
│   │       ├── agents/
│   │       ├── workflows/
│   │       ├── scripts/
│   │       └── references/
│   ├── agents/                 # Top-level subagent personas for platform discovery
│   │   ├── architect.md
│   │   ├── engineer.md
│   │   ├── designer.md
│   │   └── ... (all 10 subagents)
│   └── rules/                  # Workspace rule definitions
│       └── AGENTS.md
├── AGENTS.md                   # Root agent instruction entrypoint
├── CLAUDE.md                   # Anthropic Claude Code entrypoint
├── GEMINI.md                   # Google Gemini CLI entrypoint
└── .slopignore                 # Anti-slop exclusion rules

Manual Installation

For Google Antigravity & Gemini CLI

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills"
Copy-Item -Recurse -Force "skills/ultra-skill" "$HOME\.agents\skills\ultra-skill"

# macOS / Linux
mkdir -p ~/.agents/skills
cp -r "ultra-skill/skills/ultra-skill" ~/.agents/skills/

For Claude Code

# Run the automated installer or manually configure:
cp ultra-skill/CLAUDE.md ultra-skill/AGENTS.md /path/to/my-project/
mkdir -p /path/to/my-project/.claude/skills
cp -r ultra-skill/skills/ultra-skill /path/to/my-project/.claude/skills/

For Cursor, Windsurf, OpenCode & Other AI IDEs

Run python scripts/install_skill.py . in your workspace root, or copy AGENTS.md to your workspace root and point your AI assistant to .agents/skills/ultra-skill/SKILL.md.

---

✅ Pre-Flight Quality Checklist

Ultra Skill performs this verification audit before submitting any final response:

📋 Planning & Progress Tracking (All Tasks)

• Implementation plan formulated and structured before any code modifications?
• Live markdown checklist (- [ ]) created and updated with [x] as steps complete?
• Zero-context specifications provided (exact file paths, signatures, test commands)?

🗺️ Architecture & Diagram Tasks (Archify)

• Diagram mode chosen accurately (architecture, workflow, sequence, dataflow, lifecycle)?
• Candidate JSON validated against official Archify schema?
• Executed finalize CLI command with exit code 0?
• Real codebase nodes grounded with source file evidence pointers?
• Output HTML is self-contained with dark/light themes and export controls?

🤖 Agent & Workflow Tasks (ADK 2.0)

• Agent directory includes __init__.py exposing from . import agent?
• Primary agent or workflow exported as root_agent?
• Every tool parameter has strict type annotations and docstring explanations?
• Graph edges start at "START" and resolve to terminal outputs without loops?
• Fan-out nodes are converged with a JoinNode?
• Verified headlessly with adk run --jsonl or InMemoryRunner?

💻 Code & Refactoring Tasks

• Ponytail Ladder evaluated: Is this the shortest, simplest working diff?
• No unrequested abstractions, factories, or speculative scaffolding?
• TDD cycle followed (failing test written and verified before implementation)?
• Root cause identified and solved rather than masked?

🎨 Frontend & Design Tasks

• Initial Design Read declared before code was written?
• The Three Dials (VARIANCE, MOTION, DENSITY) explicitly calibrated?
• Hero section strictly fits min-h-[100dvh] with CTA above fold?
• Single accent color and unified border radius used across the entire page?
• Color contrast passes WCAG AA (4.5:1 text, 3:1 display)?
• Zero AI clichés (audited via scripts/detect_ai_slop.py)?

🛡️ Completion Verification (All Tasks)

• Terminal verification command executed via scripts/verify_evidence.py?
• Output verified for zero errors and exit code 0?
• Completion claims backed strictly by visible output logs?

---

🍳 Cookbook & Real-World Recipes

Recipe 1: Building a Branching AI Agent Workflow (ADK 2.0)

from google.adk import Workflow, Event

def analyze_sentiment(text: str) -> Event:
    score = len(text) % 2
    route = "positive" if score == 0 else "negative"
    return Event(output={"text": text, "route": route}, route=route)

def handle_positive(payload: dict) -> str:
    return f"Thank you for the kind feedback on: {payload['text']}"

def handle_negative(payload: dict) -> str:
    return f"Forwarded to support team: {payload['text']}"

root_agent = Workflow(
    name="feedback_triage",
    edges=[
        ("START", analyze_sentiment),
        (analyze_sentiment, {
            "positive": handle_positive,
            "negative": handle_negative,
        }),
    ],
)

Recipe 2: 60fps Scroll-Triggered Animation with GSAP

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

const mm = gsap.matchMedia();

mm.add({
  isDesktop: "(min-width: 768px)",
  reduceMotion: "(prefers-reduced-motion: reduce)"
}, (context) => {
  const { isDesktop, reduceMotion } = context.conditions;

  if (reduceMotion) {
    gsap.set(".feature-card", { autoAlpha: 1 });
    return;
  }

  gsap.from(".feature-card", {
    scrollTrigger: {
      trigger: ".features-grid",
      start: "top 80%",
      toggleActions: "play none none reverse",
    },
    y: isDesktop ? 40 : 20,
    autoAlpha: 0,
    duration: 0.6,
    stagger: 0.15,
    ease: "power2.out",
  });
});

Recipe 3: Generating an Interactive System Diagram with Archify

# 1. Author candidate architecture JSON
# 2. Run finalize gate command to produce standalone interactive HTML
node skills/ultra-skill/references/archify/bin/archify.mjs finalize \
  architecture \
  .archify/architecture-web-app/candidate.json \
  dist/architecture.html \
  --quality showcase \
  --json

Recipe 4: Synthesizing an Implementation Plan & Live Task Checklist

# 📋 Feature Implementation Plan

**Goal:** Integrate Stripe webhook handler for subscription renewals.
**Architecture:** Secure webhook endpoint validating signatures and publishing events.
**Tech Stack:** FastAPI, Stripe SDK, Pytest.
**Affected Files:**
- `app/api/webhooks.py` (Create)
- `tests/test_webhooks.py` (Create)

## 🎯 Global Constraints
- [ ] Must verify HMAC signature before payload parsing.
- [ ] Idempotent event processing via event ID caching.

## 📝 Master Implementation Checklist
- [ ] Step 1: Write failing tests for invalid signatures (RED)
- [ ] Step 2: Implement signature verification (GREEN)
- [ ] Step 3: Write tests for event dispatch logic (RED)
- [ ] Step 4: Implement event handler and verify pass (GREEN)
- [ ] Step 5: Run full verification suite (`pytest tests/`)

---

📄 License & Sources

Released under the MIT License.

Upstream Sources & Credits

• Archify: tt-a1i/archify
• Google ADK 2.0: google/adk-python
• Ponytail: DietrichGebert/ponytail
• Taste: Leonxlnx/taste-skill
• GSAP Skills: greensock/gsap-skills
• Motion Design: LottieFiles/motion-design-skill
• Design DNA: zanwei/design-dna
• Superpowers: obra/superpowers
• CodeRabbit Skills: coderabbitai/skills
• Vercel Skills: vercel-labs/skills
• UI/UX Pro Max: nextlevelbuilder/ui-ux-pro-max-skill

---

Engineered with precision for autonomous AI agents and pair-programming engineers.