agent-kit tracks AI agent setup to keep workflows consistent across machines. It contains prompt-style skills, custom workflows, and local tooling.

agent-kit is an agent-facing Heuristic System framework, not a generic skill marketplace. It gives agents a portable operating layer where skills, scripts, runbooks, evidence records, tests, hooks, and guardrails can turn repeated workflow experience into maintainable repo knowledge.

The framework does not train model weights. It keeps learning explicit and auditable: when agents run workflows, inspect failures, apply fixes, validate outcomes, or update policies, the durable lessons can become skill contracts, tests, scripts, primitives, or runbooks.

The portable core is the tracked repository content: AGENTS.md, DEVELOPMENT.md, HEURISTIC_SYSTEM.md, docs/, scripts/, hooks/, and public skills under skills/workflows/, skills/tools/, and skills/automation/. Project, company, system, and local overlays are supported, but they are not part of the portable core unless they are explicitly tracked and documented.

Best fit:

• Engineers or teams who want agents to follow one validated operating model.
• Daily multi-repo work where preflight, checks, semantic commits, PR/MR delivery, release flow, and repeatable tooling matter.
• Users who prefer explicit guardrails, failure handling, and durable workflow learning over a loose collection of standalone prompt snippets.

.
├── .agents/    # repo-local agent helper scripts, including release entrypoint
├── .github/    # CI workflows (GitHub Actions)
├── docker/     # Docker image docs and workspace launcher pointers
├── docs/       # runbooks, plans, and testing docs
├── hooks/      # Codex hook source and managed config block
├── scripts/    # validation, sync, build, and helper entrypoints
├── skills/     # tracked public skills, prompt-style skills, and ignored overlays
├── tests/      # pytest regression/smoke tests
├── AGENTS.md   # global agent rules (response/tooling)
├── DEVELOPMENT.md
└── HEURISTIC_SYSTEM.md

Run the macOS bootstrap script for a first install or repair:

curl -fsSL https://raw.githubusercontent.com/graysurf/agent-kit/main/install.sh | bash

The installer defaults to:

• installing Homebrew tools from CLI_TOOLS.md with the recommended profile
• installing or upgrading nils-cli from sympoies/tap
• cloning this repository to $HOME/.agents
• initializing $HOME/.codex/AGENTS.md
• linking $HOME/.agents/AGENTS.md to $HOME/.codex/AGENTS.md
• writing a managed $HOME/.zshenv block for AGENT_HOME, AGENT_DOCS_HOME, PLAN_ISSUE_HOME, and Homebrew PATH
• syncing the managed Codex hooks block into $HOME/.codex/config.toml

For a local checkout, run:

./install.sh

AGENT_HOME is the home for this agent-kit toolchain. Note: nils-cli ≥ 0.8.0 binaries (agent-docs, plan-issue) no longer auto-read AGENT_HOME. Pass the home explicitly via agent-docs --docs-home "$AGENT_HOME" and plan-issue --state-dir "$AGENT_HOME", or export AGENT_DOCS_HOME / PLAN_ISSUE_HOME alongside AGENT_HOME.

nils-cli also provides shared helper binaries used by skills and checks, including plan-tooling, api-*, semantic-commit, agent-out, and media tooling. Use nils-cli >= 0.8.7 for plan-folder scaffold defaults.

Optional: set PROJECT_PATH per project (e.g. in a repo’s .envrc) so tools can treat that repo as the active project context:

export PROJECT_PATH="$PWD"

For new repositories with missing policy baseline docs, run the canonical bootstrap flow:

$AGENT_HOME/skills/tools/agent-docs/agent-doc-init/scripts/agent_doc_init.sh --dry-run --project-path "$PROJECT_PATH"
$AGENT_HOME/skills/tools/agent-docs/agent-doc-init/scripts/agent_doc_init.sh --apply --project-path "$PROJECT_PATH"
agent-docs --docs-home "$AGENT_HOME" baseline --check --target all --strict --project-path "$PROJECT_PATH" --format text

See docs/runbooks/agent-docs/new-project-bootstrap.md for the full sequence.

Codex hooks are tracked under hooks/codex/, but the full $HOME/.codex/config.toml file stays local-only. Sync the managed hook block into the local config with:

$AGENT_HOME/scripts/codex-hooks-sync sync --apply

For a first install or handoff, keep the path short:

1. Install nils-cli and set AGENT_HOME.
2. Run agent-docs --docs-home "$AGENT_HOME" resolve --context startup --strict --format checklist.
3. From this repository, run scripts/check.sh --all.
4. Try one focused workflow, such as agent-doc-init in a disposable project.
5. Add project-local .agents/skills or private skills/_projects overlays only after the portable core works.

See docker/agent-env/README.md for the Ubuntu Docker environment, Docker Hub publish steps, and compose usage. See docker/agent-workspace-launcher/README.md for the host-native agent-workspace-launcher runtime that replaced legacy Docker wrapper usage.

Prompt presets are implemented as prompt-style skills so compatible agent CLIs can surface them through a skill picker or /skills-style command. The source prompt text lives under each skill's references/prompts/ directory.

See skills/tools/skill-management/README.md for how to create/validate/remove skills (including project-local .agents/skills) using canonical entrypoints.

The catalog below covers tracked public skills under skills/workflows/, skills/tools/, and skills/automation/. Treat these sections as behavior boundaries:

• Workflows guide judgment-heavy, multi-step agent work where the agent owns interpretation, sequencing, or handoff.
• Tools expose bounded commands, evidence records, execution surfaces, or maintenance helpers; the caller owns intent and safety.
• Automation owns an end-to-end loop and may stage, commit, push, retry checks, create or close PRs/MRs, or publish releases.

Tool skills may also be grouped by execution surface, such as skills/tools/computer-use/ for live GUI automation. Nested folders below the three public domains are catalog taxonomy only. They must describe the skill's behavior boundary, such as skills/tools/workflow-evidence/ or skills/automation/ci/, without changing whether the skill is a workflow, tool, or automation skill. Prompt-style skills are listed in the Prompts section above and are not duplicated in the general workflow table. Ignored local/system overlays may exist under skills/_projects/ and skills/.system/, but they are not part of the public catalog unless explicitly tracked.

Use scripts/check.sh as the canonical local check entrypoint:

scripts/check.sh --pre-commit

Use scripts/check.sh --all as the canonical minimum gate.

Common focused runs:

scripts/check.sh --docs
scripts/check.sh --markdown
scripts/check.sh --tests -- -m script_smoke
bash scripts/ci/stale-skill-scripts-audit.sh --check
scripts/check.sh --entrypoint-ownership

Lint CI (.github/workflows/lint.yml) maps its phases to scripts/check.sh modes. Generated phase blocks are managed by scripts/ci/generate-lint-workflow-phases.py (--check for CI, --write when updating mappings). Keep docs and CI guidance aligned with these modes instead of legacy ad-hoc wrappers.

This project is licensed under the MIT License. See LICENSE.