Tool Setup Explained

When you install a skill or agent package, APKG can automatically generate configuration files for your AI coding tools. This page is the single reference for how that mechanism works — which tools are supported, how APKG decides what to set up, what files are written, and how to control the behavior. Other package types (command, rule, etc.) do not trigger automatic setup.

Supported tools

APKG currently supports five AI coding tools. Each tool has a key used in CLI flags and configuration, and a marker directory used for auto-detection.

Tool key	Tool	Detection signal
claude-code	Claude Code	.claude/ directory exists
cursor	Cursor	.cursor/ directory exists
windsurf	Windsurf	.windsurf/ directory exists
kiro	Kiro	.kiro/ directory exists
codex	Codex	.codex/ directory exists

These keys are used in both the --setup <tool> CLI flag and the defaultSetup.<tool> config setting.

Note

Claude Code is the most thoroughly documented tool. Detection signals and output paths for other tools follow the same conventions but are not yet fully verified in this documentation.

How APKG decides what to set up

APKG uses a three-level precedence to determine which tool(s) to configure. The highest-priority match wins:

1. Explicit flag — --setup <tool> targets exactly that tool. --no-setup disables setup entirely, overriding everything else.
2. Persistent config — Any defaultSetup.<tool> key set to true via apkg config causes that tool to be configured. Multiple tools can be enabled simultaneously.
3. Auto-detection — If neither a flag nor a config value applies, APKG scans the project directory for known marker directories (see the table above). If one is found, setup runs for that tool.

When --no-setup is passed, no tool setup runs regardless of config or detected tools. When --setup <tool> is passed, only the named tool is set up, even if other tools are detected or configured.

See Configuration and Precedence for the full override order across all APKG settings.

Which commands run setup

Command	When setup runs
apkg add	After installing a skill or agent package
apkg install	After installing each eligible package
apkg update	After updating each eligible package
apkg remove	Reverses setup — deletes generated config files

Definition file discovery

APKG looks for definition files inside the package to determine what to write into the tool’s configuration directory.

What counts as a definition file

A file qualifies as a definition file when it meets all of these criteria:

• It is a .md file.
• It contains YAML frontmatter (delimited by ---).
• Its filename is not README.md, CHANGELOG.md, or LICENSE.md (case-insensitive).

The frontmatter can include the following fields:

Field	Purpose
name	Identifier shown in the tool’s skill or agent list
description	Short summary the assistant uses to decide when this skill is relevant
tools	Comma-separated list of tools the skill or agent needs

Example definition file:

---
name: code-reviewer
description: Reviews code for bugs and quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Analyze the provided code for bugs,
security issues, and quality improvements.

Multiple definition files

When a package contains more than one qualifying .md file, all of them are copied into the tool’s configuration directory. This is useful when a package covers several related capabilities with separate prompts. See the Create a skill package guide for an example.

What APKG writes

Claude Code

For skill packages, APKG writes configuration into:

.claude/skills/@<scope>/<name>/

For agent packages:

.claude/agents/@<scope>/<name>/

For example, @acme/code-reviewer creates the directory .claude/skills/@acme/code-reviewer/.

When definition files are found: Each qualifying .md file from the package is copied into the target directory.

When no definition files are found (fallback): APKG generates a summary .md file:

• For skills: The summary lists the package description, capabilities (from skill.capabilities in apkg.json), and entry point.
• For agents: The summary includes the resolved system prompt, tool bindings with their required/optional status, and model preferences.

System prompt resolution

If agent.systemPrompt in apkg.json is a file path (e.g. prompts/system.md), the file is read from the package directory at setup time and its content is included in the generated summary. If it is inline text, the text is used as-is.

Example project after install

After installing a skill package and an agent package, a project looks like this:

your-project/
  .claude/
    skills/
      @acme/
        code-reviewer/
          code-reviewer.md
    agents/
      @acme/
        research-agent/
          research-agent.md
  apkg_packages/
    @acme/
      code-reviewer/
      research-agent/
  apkg.json
  apkg-lock.json

Other tools

APKG has setup logic for Cursor, Windsurf, Kiro, and Codex. Each tool has different directory structures, file formats, and feature support. For detailed per-tool documentation, see the Tool Integration section:

• Skills per tool — file paths, frontmatter fields, and capability surfacing
• Agents per tool — system prompt mapping, tool bindings, and model preferences
• Commands per tool — slash command support (currently Claude Code-specific)
• Rules per tool — alwaysApply, glob scoping, and auto-setup support

Cleanup on remove

When you run apkg remove, APKG:

1. Deletes the package directory from apkg_packages/.
2. Deletes the generated configuration directory (e.g. .claude/skills/@acme/code-reviewer/).
3. Cleans up empty parent directories left behind.

Reinstall and update behavior

• apkg update re-runs tool setup for updated packages, replacing previously generated files with new ones.
• Running apkg add on an already-installed package overwrites the existing setup files.
• There is no merge — old generated files are replaced entirely each time.

Quick reference

Question	Answer
Which package types trigger setup?	skill and agent only
Which commands run setup?	add, install, update
Which command reverses setup?	remove
How do I target a specific tool?	--setup claude-code (or cursor, windsurf, kiro, codex)
How do I skip setup?	--no-setup
How do I set a persistent default?	apkg config set defaultSetup.claude-code true
Where do Claude Code skills land?	.claude/skills/@<scope>/<name>/
Where do Claude Code agents land?	.claude/agents/@<scope>/<name>/
What files are excluded from discovery?	README.md, CHANGELOG.md, LICENSE.md

Related pages

Page	Description
apkg add	Add a package with --setup or --no-setup
apkg install	Install all dependencies with tool setup
apkg remove	Remove a package and clean up setup files
apkg config	Set defaultSetup.<tool> for persistent defaults
Configuration and Precedence	Full override order for all CLI settings
Skill	Skill package type and definition file format
Agent	Agent package type, system prompt, and tool bindings
Create a skill package	Step-by-step skill authoring guide
Create an agent package	Step-by-step agent authoring guide