Troubleshooting
Troubleshooting
Section titled “Troubleshooting”Use agents-pack status first. It is always read-only and reports scope, pack version, pin state, component lists, and every managed output as clean, missing, modified, or malformed.
Common errors
Section titled “Common errors”“Agents Pack is not initialized”
Section titled ““Agents Pack is not initialized””Run the command from inside the intended repository, or initialize the desired scope first:
agents-pack init“Agents Pack is installed in both global and current-repository scope”
Section titled ““Agents Pack is installed in both global and current-repository scope””The current release does not combine scopes. Choose which installation should remain, move any user-owned canonical source you want to keep, and eject the other scope.
A file is reported as modified, missing, or malformed
Section titled “A file is reported as modified, missing, or malformed”Agents Pack stopped to protect your work.
- Run
agents-pack status. - Inspect the reported file or managed block.
- If you intentionally customized an official skill or subagent, restore the generated file, use
agents-pack fork, and then edit the canonical user-owned copy. - If it is user-owned, make the change in
.agents-pack/user/or~/.agents-pack/user/and restore the generated copy. - Rerun
status, then retry the command.
Agents Pack does not currently provide an automatic “discard my edits” or three-way prose merge command. See Safety and drift.
“The installed Base is unavailable”
Section titled ““The installed Base is unavailable””The content-addressed cached pack is missing or unreadable. Component operations need that exact Base. For a local installation, provide the exact pack again with update --pack. For an official installation, do not manually delete ~/.agents-pack/cache/packs/; restore the matching pack before continuing.
“This installation uses a local pack”
Section titled ““This installation uses a local pack””Updates for a local installation need an explicit candidate:
agents-pack update --pack /path/to/new-local-pack --dry-runREMOTE_ERROR
Section titled “REMOTE_ERROR”Agents Pack could not load the official registry or release artifact. Check your network connection and try again. If GitHub or GitHub Pages is temporarily unavailable, wait and retry. Use --pack only when you intentionally have a local candidate.
PINNED
Section titled “PINNED”The installed version is intentionally fixed. You can still run agents-pack update --check. Run agents-pack unpin only when you want to allow the update. See Update, pin, and rollback.
“No cached version older than … is available”
Section titled ““No cached version older than … is available””Rollback only uses versions previously initialized or successfully applied on this machine. It does not fetch missing historical packs.
Global Cursor is rejected
Section titled “Global Cursor is rejected”Use Cursor in repository scope, or initialize global scope for Claude Code and Codex only. Global Cursor instructions are not supported yet.
A previous operation was interrupted
Section titled “A previous operation was interrupted”agents-pack status reports recovery without changing anything. Rerun the interrupted mutating command. The command acquires the operation lock, recovers the unfinished transaction, creates a fresh plan, and continues safely.
FAQ highlights
Section titled “FAQ highlights”Do I need to memorize the CLI commands?
Section titled “Do I need to memorize the CLI commands?”No. After the first agents-pack init, ask your coding agent for the outcome you want. The required ap-manage-agents-pack skill teaches it how to inspect the installation, preview safe operations, use the CLI, and verify the result.
Will Agents Pack overwrite my existing AGENTS.md?
Section titled “Will Agents Pack overwrite my existing AGENTS.md?”No. Codex instructions are placed inside a clearly marked managed block. Text outside that block remains yours. A malformed or conflicting block stops the operation.
Do I have to install every component?
Section titled “Do I have to install every component?”No. Start with Recommended, choose All, or select exact IDs. You can later use list, install, and remove. See Component selection.
Will new recommended components appear automatically?
Section titled “Will new recommended components appear automatically?”They appear as available after you update the pack, but are not installed silently. Your selection is stored as explicit component IDs.
Can I edit an official skill directly?
Section titled “Can I edit an official skill directly?”You can inspect it, but direct edits to the generated copy are drift. Fork the official component into a user-owned name, then edit the canonical copy.
Can a coding agent create a portable skill for me?
Section titled “Can a coding agent create a portable skill for me?”Yes. The required ap-create-new-skill skill teaches selected agents to create or update one canonical user-owned skill and synchronize it through the CLI.
Where should I edit my custom content?
Section titled “Where should I edit my custom content?”| Scope | Path |
|---|---|
| Repository | .agents-pack/user/ |
| Global | ~/.agents-pack/user/ |
Do not edit the generated provider copies.
Does rollback change my custom skills or subagents?
Section titled “Does rollback change my custom skills or subagents?”No. Rollback changes the official pack and leaves canonical user-owned content alone.
Does eject delete my custom source?
Section titled “Does eject delete my custom source?”No. Eject removes generated copies and lifecycle state but preserves the canonical user directory.
Can I work offline?
Section titled “Can I work offline?”Yes, with a local pack directory supplied through --pack. Official registry checks and downloads require network access.
Does update update the Agents Pack CLI?
Section titled “Does update update the Agents Pack CLI?”No. It updates the content pack only. Rerun the public installer to upgrade or reinstall the CLI.
How do I uninstall the CLI?
Section titled “How do I uninstall the CLI?”rm "$HOME/.local/bin/agents-pack"This does not eject managed project or global content. Preview and apply eject first if you also want to remove an initialized scope. See Eject and uninstall.
Should repository-generated files be committed?
Section titled “Should repository-generated files be committed?”Usually, yes. Review and commit .agents-pack state, canonical user-owned source, and provider files so the repository carries the same setup for other developers and agents. The user-level cache under ~/.agents-pack/cache/ should not be committed.