acp-vscode

acp-vscode is a small CLI to fetch and install agents, prompts, instructions and skills from the GitHub "awesome-copilot" repository into your VS Code workspace or VS Code User profile.

Install (when published):

npm install -g acp-vscode
# or run locally
node ./bin/acp-vscode.js --help

Commands:

• install <workspace|user> [names...]
  • target: workspace or user
  • names: optional list of ids or names to install (supports repo:id form)
  • type: specify with the option --type <type> (prompts|agents|instructions|skills|chatmodes|all). Note: chatmodes is legacy/deprecated (use agents instead). For backwards compatibility you can still pass the type as the first positional name (e.g. install workspace prompts p1 p2). The install command also accepts a deliberate typo alias --referesh (alias for --refresh) to preserve historical behavior.
• list [type]
  • list items available. type can be prompts, agents, instructions, skills, chatmodes (legacy), or all
• search
  • search across items
• uninstall <workspace|user> [names...]
  • remove installed files from workspace or user profile; use --yes to skip confirmation when targeting user.
• completion [shell]
  • print a simple shell completion script for bash or zsh (default bash)

Output formats

Both list and search support a machine-readable JSON output via the --json (or -j) flag. When provided the commands will emit an array of items (objects with type, id, and name) instead of the human-friendly table.

Example (JSON):

acp-vscode list prompts --json
acp-vscode search "find me" --json

Examples:

Install all prompts to workspace:

acp-vscode install workspace prompts

Install specific instructions to user profile (preferred):

acp-vscode install user --type instructions "Instruction Name"

Or (legacy positional type):

acp-vscode install user instructions "Instruction Name"

Completion examples

Print a bash completion helper and save it for interactive use:

acp-vscode completion bash > /etc/bash_completion.d/acp-vscode
# or source it in your shell for testing
acp-vscode completion bash | source /dev/stdin

For zsh add the script snippet to your .zshrc (the command prints a small helper function):

acp-vscode completion zsh >> ~/.zshrc

Uninstall examples

Remove two prompts from workspace:

acp-vscode uninstall workspace prompts one two

Remove a prompt from the user profile without confirmation:

acp-vscode uninstall user prompts my-prompt --yes

Troubleshooting

• Cache and stale index
  • By default the CLI writes a disk cache under the user's home directory in ~/.acp/cache/index.json (30 minute TTL). When running in development or tests the CLI preserves the old behavior and keeps the cache in the current working directory at ./.acp-cache/index.json to avoid surprising local workflows. If you see stale results or want to force a fresh fetch, remove the cache file and retry:

rm -rf .acp-cache
acp-vscode list --refresh

• Offline testing / injecting a local index

  • For tests or offline usage you can set ACP_INDEX_JSON to a JSON string representing the index. This bypasses network fetching entirely and the CLI will use the provided index verbatim.

• Nested folder support

  • The CLI automatically scans for prompts, agents, instructions, and skills at any folder depth. Items can be organized at the root level (prompts/, agents/, etc.) or in nested folders like .github/prompts/, workflows/prompts/, etc.

• Multiple upstream repos

  • To index multiple repos set ACP_REPOS_JSON to a JSON array of repo descriptors. Example:

[ { "id": "r1", "treeUrl": "https://api.github.com/repos/org/repo1/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo1/main" } ]

• Verbose logging
  • Add --verbose to commands to see extra diagnostic messages during fetch, cache clearing, and install/uninstall operations.

Cache: the CLI caches the fetched GitHub index in-memory and on-disk for 30 minutes to reduce network calls. The on-disk cache is stored under the current working directory in .acp-cache/index.json.

Configuration (environment variables)

Environment variables

ACP_INDEX_JSON

You can inject a full, pre-built index via the ACP_INDEX_JSON environment variable. This should be a JSON string representing the index shape the fetcher returns, for example:

{
  "prompts": [{ "id": "p1", "name": "Prompt 1", "repo": "r1", "url": "https://..." }],
  "chatmodes": [],
  "agents": [],
  "instructions": [],
  "skills": []
}

This is useful for tests or offline runs. When present, the fetcher will parse and return this value verbatim.

ACP_REPOS_JSON

To support multiple upstream repos, set ACP_REPOS_JSON to a JSON array describing the repositories to index. Each repo object should contain at least an id and a treeUrl. Optionally include rawBase (the base URL to fetch raw file contents).

Important: The default awesome-copilot repo is always included alongside your configured repos unless you explicitly set ACP_EXCLUDE_DEFAULT_REPO=true (environment variable). This means your custom repos are additive to the default, not replacements.

Example:

[
  { "id": "r1", "treeUrl": "https://api.github.com/repos/org/repo1/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo1/main" },
  { "id": "r2", "treeUrl": "https://api.github.com/repos/org/repo2/git/trees/main?recursive=1", "rawBase": "https://raw.githubusercontent.com/org/repo2/main" }
]

When multiple repos contain files with the same id, the fetcher adds an _conflicts array to the returned index listing conflicted ids. Consumers will display items as repo:id when necessary to disambiguate.

Local repo file (acp-repos.json)

In addition to ACP_REPOS_JSON the CLI will look for a file named acp-repos.json in a local configuration directory and use it to populate the upstream repo list if the environment variable is not set. In normal usage (when NODE_ENV is not development or test), this file is expected at ~/.acp/acp-repos.json. When NODE_ENV is set to development or test, the CLI instead looks for ./acp-repos.json in the current working directory; this behavior exists primarily to support local development and automated tests. This file should contain the same JSON array format as ACP_REPOS_JSON and is useful for per-user configuration without exporting environment variables. Like ACP_REPOS_JSON, the default awesome-copilot repo is always included alongside repos from this file unless you set ACP_EXCLUDE_DEFAULT_REPO=true. Precedence when building the repos list is:

1. ACP_REPOS_JSON environment variable (highest priority) — default repo is always added
2. Local acp-repos.json file (if ACP_REPOS_JSON not set): in ~/.acp/acp-repos.json by default, or ./acp-repos.json when NODE_ENV is development or test — default repo is always added
3. Built-in default repo (github/awesome-copilot) — used as fallback

To exclude the default awesome-copilot repo entirely, set the ACP_EXCLUDE_DEFAULT_REPO environment variable to true or 1.

ACP_EXCLUDE_DEFAULT_REPO

By default, the awesome-copilot repository is always included in the index regardless of whether you've configured custom repos via ACP_REPOS_JSON or acp-repos.json. This makes custom repos additive rather than replacements.

If you want to exclude the default awesome-copilot repo, set ACP_EXCLUDE_DEFAULT_REPO=true or ACP_EXCLUDE_DEFAULT_REPO=1:

# Exclude default repo and use only custom repos
export ACP_EXCLUDE_DEFAULT_REPO=true
export ACP_REPOS_JSON='[{"id":"myrepo","treeUrl":"...","rawBase":"..."}]'
acp-vscode list

When this is set to any value other than true or 1, the default repo will be included (default behavior).

Dry-run:

You can preview what would be installed without writing files using --dry-run:

acp-vscode install workspace prompts --dry-run

Other notes

Global flags

• --verbose enables extra logging across commands.
• --refresh is a global top-level flag but currently only applied by the list and search commands to force clearing in-memory and on-disk caches. The install command accepts a --referesh alias (typo preserved) which also triggers cache clearing when provided to install.

Commands reference

Short reference for each command, key options, and quick examples.

• install <workspace|user> [names...]

  • Description: Install prompts/agents/instructions/skills into a workspace or VS Code user profile.
  • Options: -t, --type <type> (prompts|agents|instructions|skills|chatmodes|all; chatmodes is legacy/deprecated), --dry-run, --referesh (alias for refresh), --verbose
  • Examples:
    • Install all prompts into the current workspace:
      • acp-vscode install workspace prompts
    • Install instruction by name into user profile (preferred):
      • acp-vscode install user --type instructions "Instruction Name"

• list [type]

  • Description: List available items. Type can be prompts, agents, instructions, skills, chatmodes (legacy), or all (default).
  • Options: -r, --refresh (clear caches and refetch), -j, --json, --verbose
  • Examples:
    • acp-vscode list agents
    • acp-vscode list --json

• search

  • Description: Search the index for matching items (name, id or content).
  • Options: -r, --refresh, -j, --json, --verbose
  • Examples:
    • acp-vscode search "temperature"

• uninstall <workspace|user> [names...]

  • Description: Remove installed files from workspace or user profile. When targeting user you'll be prompted for confirmation unless you pass --yes.
  • Options: --yes, --verbose
  • Examples:
    • acp-vscode uninstall workspace prompts one two

• completion [shell]

  • Description: Print a small shell completion snippet for bash or zsh.
  • Examples:
    • acp-vscode completion bash

Publishing:

This repository includes a release workflow that publishes to npm when a tag like v0.1.0 is pushed. You must add an NPM_TOKEN secret in the repository settings for the workflow to authenticate with npm.

Publish checklist:

1. Update package.json fields: version, repository.url, bugs.url, author.
2. Create a repo secret NPM_TOKEN in GitHub (Settings → Secrets → Actions). Generate the token with npm's access token UI.
3. Create a release tag and push it, e.g.:

git tag v0.1.0
git push origin v0.1.0

4. The release workflow will run tests and publish the package to npm on success.

Uninstall and confirmation:

To remove installed files:

acp-vscode uninstall workspace prompts one two

If you're uninstalling from the VS Code user profile, the CLI will prompt for confirmation. Use --yes to skip the prompt:

acp-vscode uninstall user prompts one --yes