Agent Skills Architecture¶

Zenith provides a first-class framework for autonomous AI coding agents (Claude Code, Google Gemini CLI, Antigravity, OpenAI Codex, Cursor, Windsurf, Aider).

Rather than relying on vague prompts or unbounded system prompts, Zenith organizes all agent capabilities into modular, prefixed Agent Skills located in .agents/skills/.

Agentic Tool Compatibility Matrix¶

Zenith projects operate with modern autonomous coding agents, terminal assistants, and AI-native IDEs out of the box when enabled. During project scaffolding, the ai_tools prompt lets you select all tools (all), popular tools (recommended), targeted form factors (ide-only, cli-only), custom tool combinations, universal context only (minimal), or completely exclude AI tooling (none).

The table below audits popular AI coding tools, their scaffolded configuration assets, their support level in Zenith, and their current verification status:

Audit Summary & Verified Workflows¶

Zenith maintains first-class support for autonomous coding agents by enforcing three architectural invariants across all supported tools:

1. Deterministic Single Source of Truth: Every tool resolves instructions back to the canonical AGENTS.md at the repository root, either natively or via symbolic links (CLAUDE.md, .cursorrules, .windsurfrules, .cursor/rules/zenith.mdc, .github/copilot-instructions.md).
2. Subagent Specialization: Where supported (Claude Code, Google Gemini CLI, Antigravity, Cursor, OpenAI Codex, OpenCode), Zenith links or compiles specialized subagent personas (sdd-specifier, sdd-planner, sdd-implementer, sdd-reviewer) from .agents/subagents/.
3. Hermetic Task Sandboxing: Tools operate within isolated environment boundaries using uv run poe <task>, preventing dependency pollution and ensuring identical execution between local agents, developers, and CI pipelines.

Explicitly Tested Tools¶

• Google Antigravity:
• Validated with Antigravity IDE and agy CLI environments.
• Verifies auto-discovery of AGENTS.md via .gemini/settings.json.
• Subagents in .gemini/agents/ execute Spec-Driven Development tasks with full tool calling, hermetic testing, and quality verification gates.
• OpenAI Codex CLI:
• Validated with the OpenAI Codex CLI runner.
• Verifies project instruction loading through project_doc_fallback_filenames = ["AGENTS.md", "CLAUDE.md"].
• Verifies workspace-write sandbox confinement and on-request approval policies.
• Verifies native .codex/agents/*.toml subagent declarations.
• OpenCode:
• Validated with the OpenCode CLI / TUI environment.
• Verifies auto-discovery of AGENTS.md at project root.
• Verifies command permissions and task pre-authorizations via opencode.json.
• Subagents in .opencode/agents/ execute Spec-Driven Development tasks with hermetic task execution and quality verification gates.

Skill Taxonomy¶

To prevent naming collisions, maintain predictable agent discovery, and separate template capabilities from project domain logic, Zenith standardizes on 5 distinct skill prefixes:

Skill Discovery¶

Agent tools auto-discover skills through progressive disclosure:

flowchart TD
    Prompt["Developer Request"] --> Agent["AI Coding Agent"]
    Agent --> Root["AGENTS.md Context File"]
    Root --> Index[".agents/skills/ Index"]

    subgraph Taxonomy["Prefixed Skill Groups"]
        Index --> S["sdd-*<br/>(Spec-Driven Development)"]
        Index --> W["workflow-*<br/>(Procedures & Lifecycle)"]
        Index --> T["tool-*<br/>(Tool Syntax & Mechanics)"]
        Index --> G["guide-*<br/>(Code & Prose Standards)"]
        Index --> D["domain-*<br/>(Reserved: Project Logic)"]
    end

    Taxonomy --> Execution["Hermetic Poe Task Execution<br/>(uv run poe &lt;task&gt;)"]

1. Context Discovery: The agent reads root AGENTS.md (or symlinks CLAUDE.md, .cursorrules, .windsurfrules).
2. Progressive Disclosure: The runner initially loads only the skill name and description frontmatter. Full procedural instructions and templates are loaded into context only when that skill is activated.
3. Execution Grounding: The agent follows the skill's step-by-step instructions and executes tasks inside the hermetic project environment with uv run poe <task>.

Activation Modes¶

Each skill uses one of three activation modes. The mode is set in the description and frontmatter of its SKILL.md.

Manual-only skills set disable-model-invocation: true in their frontmatter. Zenith reserves this mode for skills with heavy side effects or cost: rebuilding the local environment, or dispatching several reviewer subagents. The domain-to-skill mapping for mandatory skills is repeated in AGENTS.md, so agents that ignore skill descriptions still receive the rule.

How Skills Work in Action: a 3-Step Walkthrough¶

Here is how an everyday developer interaction looks when pairing with an AI coding assistant:

1. Step 1: Developer Request: In your editor chat or terminal (Claude Code, Cursor, Copilot, Gemini CLI), you submit an intent:

   "Draft a technical specification for our new stripe billing webhook following sdd-spec."

2. Step 2: Skill Activation: The assistant inspects AGENTS.md, activates .agents/skills/sdd-spec/SKILL.md, and adopts its structured EARS specification format and artifact boundaries.
3. Step 3: Execution & Verification: The assistant writes the specification document, executes local Poe tasks to verify syntax (uv run poe code-quality), and presents the draft for human review.

Skill Groups¶

Explore the dedicated documentation pages for each skill group:

• Spec-Driven Development: Structured specifications, technical planning, TDD implementation, and verification reviews.
• Workflows: Release engineering, git hygiene, pre-flight audits, ADRs, environment setup, and skill creation.
• Tools: Direct syntax runbooks for all developer tools integrated into Zenith.
• Guides: Modern Python 3.12+ engineering conventions and Simplified Technical English (ASD-STE100) writing rules.
• Domains: Guidelines for project authors on adding custom domain-specific skills.