ai-agent-tools

Shared AI agent tooling for mobile app projects — Flutter, Android Native, and iOS Native. One repository, installed once per machine, serving every project.

Works in Codex, Antigravity, Claude Code, and Kiro CLI from a single source: skills/ and rules/ are written once, with a thin manifest for each runtime. Rule loading differs by runtime; see per-project setup.

There are three lifecycles, and which one you enter depends on what will exist when you finish:

Full directions, including the cases where you should skip all three: docs/lifecycles.en.md — what each lifecycle is for and what it produces. To pick one for a specific piece of work: docs/choosing-a-lifecycle.en.md. Bản tiếng Việt: lifecycles.vi.md · choosing-a-lifecycle.vi.md.

Quality provider architecture and contracts: docs/architecture/quality-provider-system.en.md · Bản tiếng Việt: quality-provider-system.vi.md.

The product discovery suite is described in 3.6.

Contents

• 1. Installation
  • 1.1. Claude Code
  • 1.2. Antigravity
  • 1.3. Codex
  • 1.4. Kiro CLI
  • 1.5. Per-project setup
• 2. Daily workflow
  • 2.1. Where the single source of truth is
  • 2.2. Editing a skill and republishing
  • 2.3. Updating another machine
  • 2.4. Command reference
• 3. Reference
  • 3.1. Repository layout
  • 3.2. How the runtimes differ
  • 3.3. The session-start hook
  • 3.4. Authoring a skill
  • 3.5. Rules vs audit criteria
  • 3.6. The upstream product discovery suite
  • 3.7. Measuring whether a skill works
• 4. License

Release notes: CHANGELOG.md.

1. Installation

Install once per machine; it applies to every project on that machine. You only need to clone this repository if you intend to edit the skills.

1.1. Claude Code

claude plugin marketplace add DanhDue/ai-agent-tools
claude plugin install d3nexus@danhdue-agent-tools

Skills then appear as d3nexus:<skill-name> — for example /d3nexus:dev-lifecycle.

Restart the session afterwards. Reload the IDE window (Cmd+Shift+P → Developer: Reload Window) or start a new CLI session. Skills are read at session start, and a new chat in the same window is not always enough.

1.2. Antigravity

Antigravity loads a plugin from any directory under its customization root that contains a root-level plugin.json. Clone this repository straight into the global plugins folder:

git clone https://github.com/DanhDue/ai-agent-tools.git ~/.gemini/config/plugins/d3nexus

That is all — plugin.json, skills/ and rules/ sit at the repo root, which is exactly the shape Antigravity expects. Skills are namespaced automatically.

Important

Check for stale global skills first. Anything already in ~/.gemini/config/skills/ is discovered independently of the plugin and competes with it — an old copy of a skill will quietly shadow the one you just installed.

ls ~/.gemini/config/skills/    # move aside any directory this kit now supplies

Antigravity also ranks workspace over global: a project's own .agents/skills/ outranks this plugin. If a project vendors its own copy, that copy wins there — remove it to let the plugin serve every project uniformly.

1.3. Codex

Use a Codex CLI version that provides codex plugin (check with codex plugin --help):

codex plugin marketplace add DanhDue/ai-agent-tools
codex plugin add d3nexus@danhdue-agent-tools

Start a new thread after installation. Select a skill from Codex's skill picker, or ask for it explicitly, for example: Use the d3nexus dev-lifecycle skill to plan this feature. The Codex manifest loads the same skills/ directory as the other runtimes; the marketplace points at the repository root.

This distributes the plugin through this GitHub marketplace. Listing it in OpenAI's public Plugins Directory is a separate process: submit a skills-only package, complete review, and publish after approval. See OpenAI's publishing guide and plugin packaging reference.

1.4. Kiro CLI

Install the power directly into Kiro CLI via GitHub repository URL:

kiro-cli powers install https://github.com/DanhDue/ai-agent-tools.git

Or from a local checkout of this repository:

cd ~/AllProjects/ai-agent-tools
kiro-cli powers install .

Kiro automatically discovers the shared skills and rules via plugin.json and AGENTS.md. Start a new chat session to activate the power.

1.5. Per-project setup

The plugin supplies skills and rule files. Each project still needs an entry point. From a working clone of this repository, run:

scripts/init-project.sh /path/to/project "Project Name"

This writes an AGENTS.md from the template, symlinks CLAUDE.md → AGENTS.md so one file serves all three runtimes and they cannot drift, and prints the editor guardrails to merge into .vscode/settings.json.

Codex reads AGENTS.md; Claude's @file imports and Antigravity's trigger: always_on do not replace explicit Codex instructions. The template tells Codex to read the two rule files from the installed plugin (or the project's own .agents/rules/ when present). Existing projects should merge the updated Rules section from templates/AGENTS.md.

Note

Overlap with superpowers: 13 of these skills began as forks of superpowers and have since diverged. Both are namespaced plugins so they can be installed side by side, but running both means two answers to the same question — claude plugin disable superpowers to avoid ambiguity.

2. Daily workflow

2.1. Where the single source of truth is

This git repository. Everything else is a derived copy you must never edit:

DanhDue/ai-agent-tools (GitHub)                              ← THE source
 └─ ~/AllProjects/ai-agent-tools/                            ← your working clone: EDIT HERE
     ├─ ~/.claude/plugins/marketplaces/danhdue-agent-tools/  ← git clone, pulled by `marketplace update`
     │   └─ ~/.claude/plugins/cache/.../d3nexus/<version>/   ← what Claude Code actually reads
     ├─ ~/.gemini/config/plugins/d3nexus/                    ← what Antigravity reads (its own clone)
     └─ Codex-managed marketplace and plugin cache          ← refreshed by the Codex commands below

An edit to a copy works until the next update, then silently vanishes. Quick test: if the path contains .claude/plugins, .codex/plugins, or .gemini/config, it is a copy.

To read what a skill currently says, open it in your working clone (skills/<name>/SKILL.md), or run claude plugin details d3nexus for the installed inventory. Opening the project together with this repository in one editor window — see the multi-root workspace in a consuming project — keeps the source one click away.

2.2. Editing a skill and republishing

Warning

A version bump is required for Claude Code. claude plugin update compares the version in plugin.json; if it is unchanged it reports "already at the latest version" and leaves every machine on the old cached copy — the edit silently never lands.

cd ~/AllProjects/ai-agent-tools
$EDITOR skills/dev-lifecycle/SKILL.md     # 1. edit
$EDITOR CHANGELOG.md                     # 2. add dated notes for the next version
scripts/release.sh                       # 3. verify + bump + commit + push

release.sh requires a newer MAJOR.MINOR.PATCH version, dated release notes, and the main branch. It verifies before and after synchronizing all three manifests and the Claude marketplace, then commits and pushes. For anything bigger than a patch, pass the version explicitly, for example scripts/release.sh 1.4.0 when releasing from 1.3.1.

It refreshes Claude Code and Antigravity when installed and prints the Codex refresh commands from 2.3. Run those commands for an existing Codex installation, then start a new thread. For Claude Code, restart the session as in 1.1.

Antigravity needs no bump — it reads its clone's working tree directly:

git -C ~/.gemini/config/plugins/d3nexus pull

2.3. Updating another machine

Codex — refresh the registered marketplace, then reinstall the plugin:

codex plugin marketplace upgrade danhdue-agent-tools
codex plugin add d3nexus@danhdue-agent-tools

Start a new thread to pick up the changed skills.

Claude Code — both steps are needed: the first pulls the repo, the second copies it into the versioned cache Claude Code reads.

claude plugin marketplace update danhdue-agent-tools
claude plugin update d3nexus@danhdue-agent-tools

Antigravity:

git -C ~/.gemini/config/plugins/d3nexus pull

Kiro CLI:

kiro-cli powers install https://github.com/DanhDue/ai-agent-tools.git

2.4. Command reference

3. Reference

3.1. Repository layout

skills/<name>/SKILL.md           # single source of truth for all runtimes
rules/                           # always-on behavioural constraints
templates/                       # per-project scaffolding
scripts/verify.sh                # pre-publish checks
scripts/release.sh               # the publish loop
scripts/init-project.sh          # per-project scaffolding

hooks/session-start              # injects using-superpowers at conversation start
hooks/hooks.json                 # Claude Code hook config (SessionStart)
hooks.json                       # Antigravity hook config (PreInvocation, root level)

plugin.json                      # Antigravity plugin manifest (root level — required)
.claude-plugin/plugin.json       # Claude Code plugin manifest
.claude-plugin/marketplace.json  # Claude Code marketplace
.codex-plugin/plugin.json        # Codex plugin manifest
.agents/plugins/marketplace.json # Codex / Antigravity marketplace

skills/<name>/SKILL.md is shared by all three runtimes. Supporting files stay beside each skill so installed copies retain their relative references.

3.2. How the runtimes differ

Worth knowing, because it explains why the layout looks the way it does:

All four load skills by progressive disclosure: only name and description enter the context window; the body is read when the skill activates. Keep SKILL.md concise and push bulk into the skill's own references/, scripts/, resources/ or examples/ subdirectory.

3.3. The session-start hook

Skills activate on description matching, which is probabilistic. The hook makes it deterministic: at the start of a conversation it injects the using-superpowers skill, which instructs the agent to reach for a skill before answering.

Claude Code and Antigravity need different wiring, so one script serves both:

Antigravity has no SessionStart event — PreInvocation is the only place to inject context, and it runs before every model call. The script therefore gates on the invocation number, and fails closed: if the payload cannot be parsed it injects nothing, because guessing "first turn" would re-inject on every turn for the rest of the session.

Important

invocationNum is zero-based — the opening turn of a conversation reports 0, not 1. Gating on 1 silently never fires, and because the gate fails closed there is no error to notice. Confirmed from a live payload:

{"conversationId":"…","invocationNum":0,"initialNumSteps":1,"modelName":"…"}

Antigravity reads a hooks.json both at the customization root (~/.gemini/config/hooks.json) and inside a plugin (plugins/<name>/hooks.json) — configuring both makes the hook run twice. This kit ships only the plugin-level one, so nothing extra is needed per machine.

scripts/verify.sh step 6 exercises all five paths.

Codex installations with bundled hook support can also discover hooks/hooks.json and provide the CLAUDE_PLUGIN_ROOT compatibility variable. Hook execution depends on the host's hook configuration and trust settings. The Codex setup above uses AGENTS.md and explicit skill selection as its entry point; see the Codex tool mapping.

3.4. Authoring a skill

A skill is a directory under skills/ containing SKILL.md with YAML frontmatter of exactly two fields:

---
name: my-skill                 # lowercase, hyphenated, matches the directory name
description: Use this skill when …   # what it does AND when to use it — drives activation
---

description is the field all three runtimes read to decide whether to activate the skill, so it carries more weight than anything in the body. All 54 skills use these two fields and nothing else — adding non-standard keys risks a frontmatter parse failure with no error surfaced.

Use the writing-skills skill when creating or editing one, and run scripts/verify.sh before publishing.

3.5. Rules vs audit criteria

Rules stay deliberately thin and runtime-agnostic — they are constraints that hold in every context, not checklists.

House conventions that are really audit criteria — Clean Architecture wiring, the Freezed contract, naming and formatting, the security baseline — live in references/flutter-project-baseline.md inside the audit skill that enforces them. That way quality_check loads them only when it actually audits a Flutter project, and each reference holds only what its SKILL.md does not already cover.

3.6. The upstream product discovery suite

Four skills implementing Dan Olsen's Lean Product Process, covering the discovery work that happens before dev-lifecycle — deciding what to build and for whom, rather than how.

Artefacts land in .devtool/product/<slug>/, and the Gate 3 backlog is consumed directly by dev-designer. Steps 5 and 6 of the process — building an MVP test and running it with customers — are not implemented; the orchestrator says so at Gate 3 rather than implying the journey is over.

Important

These skills teach an external methodology, so they are written from The Lean Product Playbook itself rather than from summaries of it. The summaries in docs/books/ are derivatives: useful as leads, not as evidence. Six behaviour-changing errors found in them are catalogued with the author's own wording in .devtool/epic/lean_product_suite/source_fidelity_review.md, and scripts/verify.sh step 7 fails the build if any of them reappear.

3.7. Measuring whether a skill works

evals/ holds a blind-judge ablation harness. Each scenario runs with the skill and without it, and a third agent grades both replies without knowing which is which. The finding is the delta — whether the skill changed what the agent decided, as opposed to whether an agent holding it can recite it.

# see evals/protocol.md — ~3 agent invocations per case

Not part of scripts/verify.sh: each run costs real agent invocations, so it belongs at release time or after editing a skill. A zero delta is a result, not a failure — it says the rule is not paying for the context it occupies.

Current findings for the Lean Product suite are in evals/results/2026-09-16-baseline/report.md, and the honest summary is in CHANGELOG.md under Known limitations.

4. License

MIT