Use APKG in an existing project

You just joined a project and there is an apkg.json file in the repo. This guide gets you from zero to a fully working setup in a few minutes.

Prerequisites

• APKG CLI installed — see Installation if you haven’t set it up yet.

What is apkg.json?

apkg.json is the package manifest. It lists the AI packages the project depends on — skills, agents, commands, and rules that the team uses with their AI coding tools. It looks something like this:

{
  "name": "@acme/backend",
  "version": "1.0.0",
  "type": "skill",
  "dependencies": {
    "@apkg/skilled-tests": "^0.1.2",
    "@acme/code-reviewer": "^1.0.0"
  }
}

You will also see an apkg-lock.json file — this is the lockfile that pins exact versions so every team member gets the same packages. Both files should be committed to version control.

Configure your tool

Tell APKG which AI coding tool you use so it can wire packages into the right configuration directory automatically. This is a one-time global setting:

apkg config set defaultSetup.claude-code true

Replace claude-code with your tool of choice:

Key	Tool
defaultSetup.claude-code	Claude Code
defaultSetup.cursor	Cursor

You can enable multiple tools if you switch between editors. See apkg config for all available options.

Install dependencies

From the project root (where apkg.json lives), run:

apkg install

This downloads every package listed in apkg.json, resolves versions from the lockfile, and runs tool setup for skill and agent packages. After it finishes your AI coding tool will have access to all the project’s AI packages.

CI environments

In CI pipelines, use the --frozen-lockfile flag to ensure builds fail if apkg-lock.json is out of date:

apkg install --frozen-lockfile

See apkg install for the full reference.

Verify the setup

Check that everything installed correctly:

apkg config list

You should see your defaultSetup entry. The installed packages live in the apkg_packages/ directory in your project.

Day-to-day usage

Add a package

When you need a new AI package for the project:

apkg add @scope/package-name

This adds the package to apkg.json, installs it, and runs tool setup. See apkg add for version pinning and other options.

Update packages

Pull the latest compatible versions:

apkg update

Or update a single package:

apkg update @scope/package-name

See apkg update for details on --latest and --dry-run.

Remove a package

apkg remove @scope/package-name

This removes the package from apkg.json, deletes its files, and cleans up tool configuration. See apkg remove for more.

Commit your changes

After adding, updating, or removing packages, commit both apkg.json and apkg-lock.json so your teammates get the same setup:

git add apkg.json apkg-lock.json
git commit -m "update apkg dependencies"

Next steps

• Package Types — Understand the different kinds of packages APKG manages.
• Publish your first package — Create and publish your own package to the registry.
• CLI Reference — Complete reference for all APKG commands.