Architecture

This page explains how the repository turns one canonical skill catalog into agent-specific files for Codex, Claude, DeepSeek, GitHub Copilot, OpenCode, Antigravity CLI, Grok, and Kimi Code.

The manifests are the source of truth:

manifest/skills.yaml defines canonical skill names, descriptions, supported agents, dependencies, and aliases.
manifest/profiles.yaml defines selectable skill bundles.
manifest/artifacts.yaml defines optional templates, personas, instruction docs, entrypoints, and management notices.
manifest/runtime.yaml defines portable runtime runners and runtime-backed skill files that may be copied into a local runtime root.
manifest/delegation.yaml defines cross-provider delegation policy, research model requirements, active/reference providers, and nested worker limits. The delegate-agent CLI consumes this policy for parent-owned live external CLI dispatch after explicit opt-in and run-specific probes.
manifest/dependencies.yaml and manifest/system-dependencies.yaml define logical tools and sanitized maintainer-system dependency observations.

The primary manifests are JSON-compatible YAML files loaded and validated by installer/ai_agents_skills/manifest.py. The JSON Schemas under manifest/schema/openclaw/ are for the gated OpenClaw integration pipeline, not the primary installer manifest format.

The installer resolves those manifests into per-agent target artifacts and records ownership in the selected root’s installer state file. Existing unmanaged files are skipped by default.

Install flow:

Resolve selected skills and artifacts from --skill, --skills, --profile, --artifact, --artifacts, or --artifact-profile.
Detect available agent homes under the selected --root.
Resolve the requested install mode, then apply per-agent loader compatibility before linking, referencing, or copying canonical skill bodies into each supported target format.
Add managed instruction blocks only for skills or artifacts that are installed, adopted, migrated, updated, or already managed.
Add root-scoped runtime-file actions for selected runtime-backed skills according to --runtime-profile and --runtime-root.
Record hashes, source paths, install modes, and ownership metadata for verification, uninstall, and rollback.

Artifact classes:

Artifact class	Current behavior
`skill-file`	Default `auto` mode links Claude skill files to canonical `SKILL.md`. Codex, OpenCode, Antigravity, Grok, Kimi, and chatgpt-local-coder copy the full canonical skill body and support files by default; Codex uses copied regular files because symlinked discovery is not assumed and its install must remain self-contained. DeepSeek and Copilot resolve to reference adapters. Antigravity writes flat global Markdown files under `~/.gemini/antigravity-cli/skills/<skill>.md`, Grok writes directory-layout `SKILL.md` files under `~/.grok/skills/<skill>/`, Kimi writes directory-layout `SKILL.md` files under `~/.kimi-code/skills/<skill>/`, and chatgpt-local-coder writes directory-layout `SKILL.md` files under `~/.chatgpt-local-coder/skills/<skill>/`. Explicit reference and copy modes are available for all agents; Copilot symlink mode is blocked until loader evidence exists.
`skill-support-file`	Symlinks canonical references, scripts, assets, templates, and agent notes when the effective skill install remains symlinked; copied in copy mode; skipped in reference mode.
`instruction-block`	Adds or updates a managed block in `AGENTS.md` or `CLAUDE.md` only when the matching skill artifact is installed, adopted, updated, or migrated.
`management-notice`	Optional top-level managed block explaining that this repo is the source and local agent homes are runtime targets.
`agent-persona`	Optional reviewer/persona files. Codex receives TOML custom agents, Claude, OpenCode, and Kimi receive Markdown subagents, Antigravity receives plugin-scoped Markdown agent definitions, Grok receives Claude-style Markdown subagents (name/description overlay; Claude tool-restriction frontmatter is not enforced on Grok), Copilot receives `.agent.md` custom-agent profiles, DeepSeek receives reference prompts, and chatgpt-local-coder receives Markdown files that are inert storage rather than registered subagents.
`template`	Optional research, report, specification, and task templates.
`instruction-doc`	Optional workflow reference documents installed outside skill folders.
`entrypoint-alias`	Optional quick-action aliases. Claude, OpenCode, and Grok receive command files; Antigravity receives flat global Markdown skill aliases; Codex, DeepSeek, and chatgpt-local-coder receive reference documents; Kimi has no commands-dir loader (skills are invoked as `/skill:<name>`).
`plugin`	Antigravity receives a managed `ai-agents-skills` plugin marker and payload directory when Antigravity artifacts are installed.
`mcp-config`	Antigravity receives a no-op plugin-scoped `mcp_config.json` scaffold with an empty `mcpServers` map.
`hook-config`	Antigravity receives a no-op plugin-scoped `hooks.json` scaffold.
`settings-file`	Antigravity receives a sparse no-op `settings.json` scaffold in its global CLI home.
`settings-hook-merge`	When the autonomous-research-loop runtime is installed for Claude, one managed `hooks.Stop` entry (tagged `_managedBy`/`_id`) is idempotently merged into `~/.claude/settings.json` and removed on uninstall; user-authored hooks are preserved.
`native-hook-file`	When the autonomous-research-loop runtime is installed for Grok, the autoloop `Stop` hook installs as a discrete fully-owned `~/.grok/hooks/ai-agents-skills-autoloop.json`; `~/.grok/settings.json` is never written because Grok does not read it for hooks.
`settings-compat-merge`	When a Grok surface is installed, a managed `[compat.claude]` block (skills/agents/rules/hooks = false) is idempotently merged into `~/.grok/config.toml` so the native install presents a single self-contained view; the block is removed on uninstall and user-authored TOML is preserved.
`runtime-file`	Root-scoped copied runtime runners and skill helper files. Runtime files are never installed as per-agent skills and are verified by transformed source hash, newline policy, mode, and secret scan.
`command`	Reserved optional target class for direct command wrappers.
`tool-shim`	Reserved optional target class for DeepSeek or runtime helper tools.

Target rendering is intentionally adapter-heavy where native behavior has not been proven. Codex personas are TOML custom-agent files, Claude, OpenCode, and Kimi personas are Markdown subagents, Antigravity personas are plugin-scoped Markdown agent definitions, Grok personas are Claude-style Markdown subagents (name/description overlay only), Copilot personas are .agent.md custom-agent profiles, and DeepSeek personas are reference prompts. Claude, OpenCode, and Grok entrypoint aliases are command files, Antigravity entrypoint aliases are flat global Markdown skill aliases, Codex, DeepSeek, and chatgpt-local-coder entrypoint aliases are reference documents under instructions/entrypoints, and Kimi does not install command-file entrypoint aliases.

Copilot is included in default target detection when ~/.copilot exists. Existing repository-level .github/* files do not activate the personal Copilot target. The installer currently writes personal Copilot skill adapters to ~/.copilot/skills/<skill>/SKILL.md and optional personal custom-agent profiles to ~/.copilot/agents/*.agent.md. Repository Copilot surfaces such as .github/skills, .github/agents, .github/copilot-instructions.md, and .github/instructions/**/*.instructions.md are reported in precheck metadata but are not written by the home-root installer path.

OpenCode is included in default target detection when ~/.config/opencode exists. The installer writes user-global OpenCode skills, rules, agents, commands, templates, and instruction docs under ~/.config/opencode. Project .opencode/ directories remain project-local and do not activate the global install target.

Antigravity is included in default target detection when ~/.gemini/antigravity-cli exists. The installer writes flat global Markdown skills under ~/.gemini/antigravity-cli/skills/, managed global context blocks under ~/.gemini/GEMINI.md, and the managed ai-agents-skills plugin payload under ~/.gemini/antigravity-cli/plugins/ai-agents-skills/. Project-local .agents/ directories remain project/workspace-local and do not activate the global Antigravity target.

Grok is included in default target detection when ~/.grok exists. The installer copies directory-layout SKILL.md files under ~/.grok/skills/, managed instruction blocks into ~/.grok/AGENTS.md (there is no GROK.md), subagents into ~/.grok/agents/, commands into ~/.grok/commands/, and instruction docs into ~/.grok/rules/. The optional autoloop hook installs as a discrete ~/.grok/hooks/ai-agents-skills-autoloop.json, and a managed [compat.claude] block is merged into ~/.grok/config.toml so the native install presents a single self-contained view. Because Grok’s [compat.claude] ride-along is default-on, installing both Claude and Grok would otherwise double-load every managed surface from both homes. GROK_HOME-relocated installs are unsupported: unset GROK_HOME before installing.

Kimi Code is included in default target detection when ~/.kimi-code exists. The installer copies directory-layout SKILL.md files under ~/.kimi-code/skills/, managed instruction blocks into ~/.kimi-code/AGENTS.md, personas into ~/.kimi-code/agents/, and inert templates/tools/instructions support storage. Copy mode is the default. The installer does not rewrite config.toml (hooks stay manual). Unattended ARL force-continue uses drive --provider kimi. Host-owned ARL panel phases use drive --panel on|auto|off so multi-agent advice/review stays outside the primary sandbox. KIMI_CODE_HOME-relocated installs are unsupported: unset KIMI_CODE_HOME before installing. See targets/kimi/README.md.

Codex user-level skills target ~/.codex/skills in this setup. The optional .agents/skills layout is treated as a compatibility or workspace target when detected, not as the default global Codex target.

Portable runtime runners accept workspace-relative skill commands only. They set runtime-specific environment variables such as AAS_RUNTIME_ROOT, AAS_RUNTIME_WORKSPACE, and AAS_SECRETS_FILE. OpenCode, Antigravity, and other non-Codex targets use the neutral shared ai-agents-skills runtime root unless a runtime root is supplied explicitly. Absolute paths and .. traversal are rejected by the runtime wrappers.

Autonomous loop enforcement:

When an autonomous loop runs, stop-condition enforcement is built in rather than hand-wired per project. One stop policy governs it: user requirements override everything; otherwise the loop stops only when the required iteration count is reached, credit or a spend cap is exhausted, the stated goal is fully resolved (agents may run an optional machine-checkable success_check command and record proof/success evidence; the done arbiter does not execute that command itself), or the user asks to stop. Nothing else is a valid stop. The policy ships as the autonomous-loop-enforcement instruction rule, and a single runtime arbiter (done) derives the verdict both enforcement paths consult.

Interactive (Claude): a managed hooks.Stop entry is merged into ~/.claude/settings.json (the settings-hook-merge surface). The entry invokes the runtime’s cross-platform hook-check subcommand directly (python3|python "<runtime>" hook-check; no shell wrapper), so it behaves identically on Windows, macOS, and Linux. It reads the hook JSON on stdin and resolves the project root from CLAUDE_PROJECT_DIR, and is fail-open: any error, timeout, missing runtime, the stop_hook_active re-entrancy payload, or a kill switch (AUTOLOOP_DISABLE, removing the registry entry, or a STOP_REQUESTED sentinel) allows turn-end. It blocks turn-end only when the arbiter reports an active, unfinished loop for that root.
Headless (driver): the runtime’s cross-platform drive subcommand runs one agent iteration per loop (the POSIX autoloop_driver.sh is now a thin shim that delegates to it), exports AUTOLOOP_DRIVER=1 so the interactive hook stands down, enforces a per-iteration timeout, and stops on the arbiter’s verdict or after repeated iteration failures. It fails safe: if it cannot determine state, it stops rather than running unbounded. Optional host-owned multi-agent panel phases (drive --panel on|auto|off, or loop panel.json) run top-level provider CLIs for target advice and result review outside the primary agent sandbox; the primary stays single-path math/research only. See docs/multi-agent-examples.md and the ARL runtime skill.

Per-target enforcement is honest, not uniform: Claude supports both the Stop hook and the driver; Codex and OpenCode are driver-only because they use TOML configuration rather than a JSON hooks map; targets without a headless agent run are documented as unsupported for built-in enforcement.

Safety boundary:

auth files, API keys, provider config, session logs, downloaded libraries, and local runtime state are not managed by this repo
runtime configs, databases, caches, downloaded documents, symlinks, and persistence-oriented scripts are denied by runtime inventory and source gates
unmanaged user files are skipped unless --adopt, --backup-replace, or --migrate is selected explicitly
uninstall and rollback require confirmation when applied and affect only recorded managed artifact paths and managed marker blocks