agent-kit

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

🗂️ Project Structure

.
├── .github/    # CI workflows (GitHub Actions)
├── prompts/    # prompt presets
├── skills/     # skills (tools/, workflows/, automation/, .system/, _shared/, _projects/)
├── scripts/    # loader + helper scripts
├── docker/     # Docker images + env tooling
├── docs/       # runbooks, plans, and testing docs
├── tests/      # pytest regression/smoke tests
└── AGENTS.md   # global agent rules (response/tooling)

⚙️ Setup

Install required tooling via the Homebrew tap:

brew tap sympoies/tap
brew install nils-cli

Upgrade when needed:

brew upgrade nils-cli

Set AGENT_HOME in $HOME/.zshenv:

export AGENT_HOME="$HOME/.agents"

AGENT_HOME is the home for this agent-kit toolchain.

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-doc-init/scripts/agent_doc_init.sh --dry-run --project-path "$PROJECT_PATH"
$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh --apply --project-path "$PROJECT_PATH"
agent-docs baseline --check --target all --strict --project-path "$PROJECT_PATH" --format text

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

🐳 Docker environment

See docker/agent-env/README.md for the Ubuntu Docker environment, Docker Hub publish steps, and compose usage.

🧰 Prompts

Common

Prompt	Description	Usage
actionable-advice	Answer a question with clarifying questions, multiple options, and a single recommendation	/prompts:actionable-advice <question>
actionable-knowledge	Answer a learning/knowledge question with multiple explanation paths and a single recommended path	/prompts:actionable-knowledge <question>
parallel-first	Enable a parallel-first execution policy for this conversation thread (prefer delegate-parallel subagents when safe)	/prompts:parallel-first
plan-issue-delivery-main-agent-init	Init prompt for the orchestration-only main agent in plan-issue-delivery	/prompts:plan-issue-delivery-main-agent-init <optional overrides for repo/plan/issue/sprint/grouping>
plan-issue-delivery-subagent-init	Init prompt for implementation-owned subagents in plan-issue-delivery	/prompts:plan-issue-delivery-subagent-init <optional overrides for task/worktree/branch/pr-mode>

🛠️ Skills

Skill management

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

Core skills are grouped under skills/workflows/, skills/tools/, and skills/automation/. Internal/meta skills live under skills/.system/ (not listed below).

Workflows

Area	Skill	Description
Conversation	ask-questions-if-underspecified	Clarify requirements with minimal must-have questions before starting work when a request is underspecified
Conversation	delegate-parallel	Decompose a goal into parallelizable tasks and execute via parallel subagents, then validate
Planning	create-plan	Create a comprehensive, phased implementation plan and save it under docs/plans/
Planning	create-plan-rigorous	Create an extra-thorough implementation plan and get a subagent review
Planning	docs-plan-cleanup	Prune outdated docs/plans markdown with dry-run-first safeguards and related-doc reconciliation
Planning	execute-plan-parallel	Execute a markdown plan by spawning parallel subagents for unblocked tasks, then validate
Issue	issue-lifecycle	Main-agent workflow for opening, maintaining, decomposing, and closing GitHub Issues as the planning source of truth
Issue	issue-subagent-pr	Subagent workflow for assigned task-lane implementation (pr-shared/per-sprint/pr-isolated), draft PR creation, and review-response updates linked to the owning issue
Issue	issue-pr-review	Main-agent PR review workflow with explicit PR comment links mirrored to the issue timeline
PR / Feature	create-feature-pr	Create feature branches and open a PR with a standard template
PR / Feature	close-feature-pr	Merge and close PRs after a quick PR hygiene review; delete the feature branch
PR / Feature	deliver-feature-pr	Define the default end-to-end feature delivery method: create PR, wait/fix CI until green, then close PR
PR / Bug	create-bug-pr	Create a new bugfix branch, open a draft implementation PR early, and continue implementation in the same PR using standardized templates
PR / Bug	close-bug-pr	Merge and close a bug PR with gh after a quick PR hygiene review (title, required sections, testing notes) aligned with create-bug-pr
PR / Bug	deliver-bug-pr	Define the default end-to-end bug PR delivery method: create PR, wait/fix CI until green, then close PR

Tools

Area	Skill	Description
Agent Docs	agent-doc-init	Initialize missing baseline docs safely (dry-run first), then upsert optional project extension entries
App Ops	macos-agent-ops	Run repeatable macOS app checks/scenarios with macos-agent
Browser	chrome-devtools-debug-companion	Diagnose browser-level issues via chrome-devtools MCP with evidence-driven root-cause analysis
Browser	playwright	Automate a real browser via Playwright CLI using the wrapper script
Browser	agent-browser	Automate a real browser via agent-browser CLI using the wrapper script
Skill Management	skill-governance	Audit skill layout and validate SKILL.md contracts
Skill Management	create-skill	Scaffold a new skill directory that passes skill-governance audit and contract validation
Skill Management	create-project-skill	Scaffold a project-local skill under <project>/.agents/skills/ with contract/layout validation
Skill Management	remove-skill	Remove a tracked skill directory and purge non-archived repo references (breaking change)
DevEx	semantic-commit	Commit staged changes using Semantic Commit format
DevEx	open-changed-files-review	Open files edited by Codex in VSCode after making changes (silent no-op when unavailable)
DevEx	desktop-notify	Send desktop notifications via terminal-notifier (macOS) or notify-send (Linux)
Media	image-processing	Process images (convert/resize/crop/optimize) via ImageMagick
Media	screen-record	Record a single window or full display to a video file via the screen-record CLI (macOS 12+ and Linux)
Media	screenshot	Capture screenshots via screen-record on macOS and Linux, with optional macOS desktop capture via screencapture
SQL	sql-postgres	Run PostgreSQL queries via psql using a prefix + env file convention
SQL	sql-mysql	Run MySQL queries via mysql client using a prefix + env file convention
SQL	sql-mssql	Run SQL Server queries via sqlcmd using a prefix + env file convention
Testing	api-test-runner	Run CI-friendly API test suites (REST + GraphQL) from a single manifest; emits JSON (+ optional JUnit) results
Testing	graphql-api-testing	Test GraphQL APIs with repeatable, file-based operations/variables and generate API test reports
Testing	rest-api-testing	Test REST APIs with repeatable, file-based requests and generate API test reports

Automation

Area	Skill	Description
DevEx	semantic-commit-autostage	Autostage (git add) and commit changes using Semantic Commit format for fully automated workflows
Issue	issue-delivery	Orchestrate issue execution loops end-to-end: open issue, track status, request review, and close only after approval + merged PR gates
Issue	plan-issue-delivery	Orchestrate plan-driven issue delivery by sprint: split plan tasks, dispatch subagent PR work, enforce acceptance gates, and advance to the next sprint without main-agent implementation.
Maintenance	gh-fix-ci	Automatically fix failing GitHub Actions checks, semantic-commit-autostage + push, and retry until green
Maintenance	fix-bug-pr	Find bug-type PRs with unresolved bug items, fix and push updates, comment, and keep PR body status synced
Maintenance	find-and-fix-bugs	Find, triage, and fix bugs; open a PR with a standard template
Maintenance	semgrep-find-and-fix	Scan a repo using its local Semgrep config, triage findings, and open a fix PR or report-only PR
Release	release-workflow	Execute project release workflows by following a repo release guide (with a bundled fallback)

🧪 Local and CI Check Entrypoints

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.

🪪 License

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