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 --setup playwright-cli
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 --setup playwright-cli
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.

Some skills provide a recognized setup command (setup.sh, scripts/setup.sh, or package.json with scripts.setup). Non-interactive installs and updates run setup only when you pass --setup; interactive installs/updates ask for confirmation only when the selected skills include a recognized setup command. Accepted setup runs once inside each installed copy: .claude/skills/<name>/ and .agents/skills/<name>/.

Skills can also declare reusable project-hook setup in hooks/manifest.json. The shared installer in lib/project-hooks.js copies listed hook assets and merges each registration into its Claude or Codex JSON settings file, preserving unrelated configuration and updating an existing hook with the same type and command instead of duplicating it. A hook manifest counts as a recognized setup even when the skill has no setup script, so future skills only need to provide their assets and declarative registrations. Deleting the skill removes unchanged manifest-owned registrations and assets; user-modified hooks and invalid settings files are left untouched with a warning.

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.