AgentToolkit

Project Overview

This repository is a lightweight foundation for organizing reusable agent packs, skills, workflows, and evaluation assets.

Repository Layout

• AGENTS.md: Repository-specific operating instructions.
• agents/: Reusable agent packs (AGENTS.md + helper assets per pack).
• skills/: Reusable skills (SKILL.md, optional scripts/references, model metadata).
• workflows/: Reusable multi-step orchestration workflows.
• evals/: Evaluation cases, datasets, and runners.
• bin/cli.js: Installer entrypoint (arg parsing + presentation).
• lib/: Installer internals — catalog.js (catalog/install state), installer.js (copy/delete), frontmatter.js, semver.js, fs-utils.js.
• scripts/sync-readmes.js: Regenerates the catalog indexes in skills/README.md and agents/README.md from item frontmatter.
• test/: node --test unit tests for lib/.

Basic Usage

1. Add agent packs in agents/ and index them in agents/README.md.
2. Add capability specifications in skills/ and index them in skills/README.md.
3. Define orchestrations in workflows/ and index them in workflows/README.md.
4. Maintain evaluation assets in evals/.

CLI Usage

Run the packaged installer from inside a target project:

npx td-ai-tools

Useful commands:

npx td-ai-tools list
npx td-ai-tools install
npx td-ai-tools install --all
npx td-ai-tools install pr-solver
npx td-ai-tools install pr-solver horizon-component-library
npx td-ai-tools update
npx td-ai-tools update --all
npx td-ai-tools update pr-solver
npx td-ai-tools delete
npx td-ai-tools delete --all
npx td-ai-tools delete pr-solver

The installer copies requested items into both agent layouts:

• Skills: .claude/skills/<name>/ and .agents/skills/<name>/

If a skill bundles a sub-agent prompt (any .md with a name: field in skills/<name>/agents/), the installer also registers it to .claude/agents/<sub-agent>.md and .agents/agents/<sub-agent>.md so Claude Code and .agents-aware runtimes such as Codex can discover the same definition. delete removes these registrations alongside the skill.

This keeps the installed assets available to both Claude-style and .agents-style project conventions.

install now errors when the target item already exists. Use update to replace an existing installed skill or agent pack.

delete removes installed items from both .claude/ and .agents/ target directories, and works on any installed skill or agent pack regardless of whether it is in the catalogue.

Versioning

Every skill and agent pack carries a version: field in its frontmatter (SKILL.md / AGENTS.md), following semantic versioning (MAJOR.MINOR.PATCH). Because the installer copies these files verbatim into the target project, the installed copy itself records the version that was installed — no lockfile is needed.

list and the interactive update menu compare the installed version against the catalog and flag anything out of date, e.g. v1.0.0 → v1.2.0 ⬆ outdated. When any installed item is stale, the CLI prints a nudge: You have N items out of date — run npx td-ai-tools update. An item installed before versioning existed (no version: field) is also treated as out of date.

Maintainers: bump an item's version: whenever you change its contents — PATCH for fixes/tweaks, MINOR for new behavior, MAJOR for breaking changes. Without a bump, users will not see the update flagged.

Catalog Indexes

The "Available Skills" / "Available Agent Packs" lists in skills/README.md and agents/README.md are generated from each item's frontmatter description. After adding, removing, or re-describing an item, regenerate them:

npm run readmes          # rewrite the indexes in place
npm run readmes:check    # CI gate — fails if the indexes are stale

Local Verification

Run the unit tests and the local smoke test (packages the repo and verifies installation into a throwaway project):

npm test
npm run smoke:install

CI (.github/workflows/ci.yml) runs the unit tests, the README freshness check, and the smoke install on every push and pull request.