Agentic Tool Kit (ATK)

A CLI-based asset manager for AI coding tools. Think npm but for skills, agents, rules, hooks, memory templates, and MCP configs that extend AI coding assistants like Claude Code.

Why ATK?

AI coding assistants become far more capable with the right configuration — curated prompts, custom agents, hook scripts, and MCP server setups. But sharing and maintaining these assets across projects and teams is painful. ATK solves this with:

• A searchable registry of versioned, validated assets
• One-command install with automatic dependency resolution
• Integrity tracking via lockfile with SHA-256 checksums
• Trust levels (vetted / community / experimental) with security review metadata
• A tool adapter layer so assets get placed correctly for each AI tool

Quick Start

Prerequisites

• Node.js >= 24.0.0
• pnpm 10.5.2+

Installation

npm install -g @detergent-software/atk

Dev Channel

To install the latest pre-release version from the develop branch, use the @dev dist-tag:

npm install -g @detergent-software/atk@dev

Dev releases follow the format x.y.z-dev.N and include features and fixes that haven't been promoted to a stable release yet. Use this to preview upcoming changes or test in-progress work.

Basic Usage

# Search for assets
atk search "planning"

# Browse the registry interactively
atk browse

# View asset details
atk info plan-feature

# Install an asset (dependencies resolved automatically)
atk install plan-feature

# List installed assets
atk list

# Check for updates
atk outdated

# Update all installed assets
atk update

Commands

| Command | Description | | ----------------------- | ----------------------------------------------------------------- | | atk audit | Verify installed asset integrity via checksums | | atk browse | Interactively browse the registry with filtering | | atk cache | Manage the registry cache | | atk config | Manage user configuration (~/.atkrc.json) | | atk diff <asset> | Show changes between installed and latest versions | | atk doctor | Run environment diagnostics | | atk info <asset> | Show detailed asset information | | atk init | Scaffold a new asset or bundle | | atk install <asset> | Install an asset with dependency resolution | | atk list | List all installed assets | | atk outdated | Show assets with available updates | | atk pin <asset> | Pin an asset to its current version | | atk prune | Remove orphaned dependencies | | atk publish | Publish an asset or bundle to the registry | | atk search <query> | Search for assets by keyword, type, or tag | | atk sync | Re-apply all installed assets from the lockfile | | atk uninstall <asset> | Remove an asset and clean up placed files | | atk unpin <asset> | Remove a version pin | | atk update [asset] | Update installed assets to latest versions | | atk why <asset> | Explain why an asset is installed (direct, dependency, or orphan) |

Asset Types

| Type | Description | Example | | -------------------- | ---------------------------------------- | ------------------------------------------------------- | | Skills | Reusable prompt-based workflows | plan-feature — orchestrated implementation planning | | Agents | Specialized sub-agents for complex tasks | clarification-agent — gathers context-aware questions | | Rules | Project or user-level behavior rules | Configuration conventions, coding standards | | Hooks | Shell scripts triggered by tool events | Pre-commit validation, post-install setup | | Memory Templates | Persistent memory structures | Project context templates | | MCP Configs | Model Context Protocol server configs | External tool integrations |

How It Works

1. Registry — Assets live in the assets/ directory, each with a manifest.json declaring metadata, dependencies, trust level, and security review info. CI validates asset and bundle changes on pull requests, rebuilds registry.json and schemas/ on pushes to develop and main, and promotes asset-only changes to main through a dedicated promotion branch.

2. Tool Adapters — JSON adapter files define how assets are placed for each AI tool. The Claude Code adapter knows to put skills in .claude/commands/, agents in .claude/agents/, etc. New tools can be supported by adding adapter files — no CLI code changes needed.

3. Lockfile — When you install an asset, ATK records it in .atk-lock.json with file paths, SHA-256 checksums, and timestamps. This enables auditing, syncing across machines, and precise uninstallation.

4. Dependency Resolution — Assets can declare dependencies on other assets. ATK resolves the full dependency graph (depth-first with circular dependency detection) and installs everything in the correct order.

Authoring Assets

Scaffolding a New Asset

Use atk init to scaffold a new asset or bundle with starter files:

# Interactive — prompts for name, description, author, tags
atk init skill

# Non-interactive — provide all fields via flags
atk init agent --name my-agent --description "Does a thing" --author "Jane Doe"

# Fork from an installed asset as a starting point
atk init skill --from plan-feature --name my-planner

# Skip the registry name-availability check (offline mode)
atk init rule --offline

Supported types: skill, agent, rule, hook, memory-template, mcp-config, bundle.

This creates a directory with:

• manifest.json (or bundle.json for bundles) — pre-filled metadata with a $schema reference
• Entrypoint file (e.g., SKILL.md, my-agent.md, my-hook.sh) — type-appropriate starter content
• README.md — documentation template

To scope the asset to an organization, use the @org/name format:

atk init skill --name @acme/my-skill

This sets the org field in the generated manifest automatically.

Publishing to the Registry

After editing your asset, publish it to the registry via PR:

# Preview what would happen without creating a PR
atk publish ./my-skill --dry-run

# Publish (creates a branch, commits files, opens a PR)
atk publish ./my-skill

# Include a custom note in the PR description
atk publish ./my-skill --message "Adds support for monorepo projects"

The publish workflow:

1. Detects whether the directory contains a manifest.json (asset) or bundle.json (bundle)
2. Validates the manifest — checks required fields, file existence, name format, and semver version
3. Checks the registry — determines if this is a new asset or an update to an existing one
4. Version bump — if updating and the manifest version hasn't been bumped, prompts for patch, minor, or major
5. Builds a plan — lists files, target registry path, branch name, and PR metadata
6. Executes — clones the registry repo, creates a branch, copies files, commits, pushes, and opens a PR against the develop branch

The PR is reviewed and merged through the normal GitHub workflow. Once merged, CI rebuilds registry.json and the asset becomes available.

Organizations

Organizations provide namespace scoping for assets. They allow teams to maintain their own versions of assets that can shadow global ones.

Setting Your Org

There are three ways to set the active org, in priority order:

1. CLI flag (highest priority):

   atk search planning --org acme
   atk install my-skill --org acme

2. Lockfile — stored per-project in .atk-lock.json when assets are installed with an org context

3. User config (lowest priority):

   atk config set org acme

The resolved org follows the chain: CLI flag > lockfile org > config org. If none are set, only global (unscoped) assets are visible.

Org-Scoped Assets

To create an org-scoped asset, set the org field in manifest.json:

{
  "name": "my-skill",
  "org": "acme",
  "type": "skill",
  "version": "1.0.0",
  ...
}

Or use the @org/name format when scaffolding:

atk init skill --name @acme/my-skill

The org value must be kebab-case (lowercase letters, numbers, hyphens, starting with a letter).

Shadowing

When an org is active, asset resolution follows these rules:

• Org-scoped assets matching the active org are always visible
• Global assets are visible unless an org-scoped asset exists with the same name and type (shadowed)
• Without an org context, only global (unscoped) assets are visible

This lets teams override global assets with org-specific versions while still inheriting the rest of the global registry.

Implicit Org Creation

There is no separate "create org" step. Publishing the first asset with an org value creates the namespace automatically. Org assets are stored under assets/<type>s/@<org>/<name>/ in the registry.

Configuration

Manage user-level settings stored in ~/.atkrc.json:

# List all config keys with current values
atk config

# Get a single value
atk config org

# Set a value
atk config org acme

# Reset a key to its default
atk config org --reset

Available Keys

| Key | Default | Description | | ----------------- | --------------- | --------------------------------------------------- | | registryUrl | (GitHub repo) | Override registry URL | | registryBranch | main | Override registry branch for API calls | | defaultTool | claude-code | Default tool when --tool is not specified | | cacheDir | ~/.atk/cache/ | Override cache directory | | cacheTtlMinutes | 60 | Cache TTL in minutes for registry data | | githubToken | (not set) | GitHub token override (defaults to gh auth token) | | org | (not set) | Default organization scope for asset resolution |

Development

Setup

git clone https://github.com/EmergentSoftware/agentic-toolkit.git
cd agentic-toolkit
pnpm install
pnpm build

Commands

pnpm dev              # Watch mode (tsc --watch)
pnpm build            # Full TypeScript build
pnpm test             # Run tests (Vitest)
pnpm test:watch       # Tests in watch mode
pnpm lint             # ESLint
pnpm lint:fix         # Auto-fix lint issues
pnpm typecheck        # Type checking (tsc --noEmit)
pnpm format           # Format with Prettier
pnpm format:check     # Check formatting

Project Structure

├── src/
│   ├── commands/          # Pastel file-based command routes
│   ├── lib/               # Core business logic
│   ├── lib/schemas/       # Zod schema definitions
│   ├── components/        # Ink terminal UI components
│   └── hooks/             # Custom React hooks
├── build/                 # Compiled output
├── tool-adapters/         # Tool placement definitions (JSON)
├── schemas/               # Auto-generated JSON Schema files
└── scripts/               # Build and validation scripts

Deployment Pipeline

This project uses a fully automated release pipeline powered by Conventional Commits, commitlint, and semantic-release.

Conventional Commits

All commits must follow the Conventional Commits format. The commit type determines what kind of release is produced:

| Prefix | Release | Example | | ----------------------------- | --------------- | ----------------------------------- | | feat: | Minor (0.x.0) | feat: add browse command | | fix: | Patch (0.0.x) | fix: correct checksum validation | | perf: | Patch | perf: speed up registry fetch | | refactor: | Patch | refactor: simplify resolver logic | | style: | Patch | style: update header colors | | docs: | Patch | docs: add install instructions | | chore: | No release | chore: update dev dependencies | | feat!: / BREAKING CHANGE: | Major (x.0.0) | feat!: redesign config format |

Commitlint

Commit messages are validated by commitlint (extending @commitlint/config-conventional) in two places:

• Locally — via a commit-msg Git hook that checks messages before they are committed
• CI — the Validate workflow lints all commit messages in a PR against the base branch

Non-conforming commits will be rejected.

Semantic Release

semantic-release automates versioning, changelog generation, npm publishing, git tagging, and GitHub Releases based on commit messages. No manual version bumps are needed — the version in package.json is managed entirely by the pipeline.

The release workflow runs on two branches:

| Branch | Trigger | npm Tag | Version Format | Example | | --------- | ------------------------ | -------- | -------------- | ------------- | | main | Push to main | latest | x.y.z | 1.2.0 | | develop | PR merged into develop | dev | x.y.z-dev.N | 1.3.0-dev.1 |

Pipeline steps:

1. Release — on push to main or develop, invokes semantic-release which:
   • Analyzes commits since the last release to determine the version bump
   • Generates release notes grouped by type (Features, Bug Fixes, Performance, etc.)
   • Updates CHANGELOG.md
   • Publishes the package to npm
   • Creates a git tag and GitHub Release
   • Commits the updated changelog and package.json version

PR Validation

Pull requests targeting main or develop run linting, type checking, tests, and commitlint.

Tech Stack

Runtime: Node.js >= 24, TypeScript 5.7+, ES2024 CLI: Pastel (file-based routing) + Ink (React for terminals) + React 19 Validation: Zod 4 (runtime schemas + JSON Schema export) Auth: GitHub CLI (gh auth token) / GITHUB_TOKEN Distribution: npm (@detergent-software scope) CI/CD: GitHub Actions + semantic-release