[BUG] "Unknown target '['agent-skills''

[petemounce]

Describe the bug
After upgrading from apm 0.12.2 to 0.12.4, I have the below error.

To Reproduce

1. Have an apm.yml listing targets like:

   targets:
     - agent-skills
     - claude
     - copilot
     - opencode

2. Run apm install

3. Observe error and log message stating agent-skills in the Valid targets list

   (.venv)$ apm install
   [>] Installing dependencies from apm.yml...
   [x] [x] Unknown target '['agent-skills''
   
   Valid targets: agent-skills, claude, codex, copilot, cursor, gemini, opencode, windsurf
   
   Fix with one of:
   
     apm targets                            # see all supported harnesses
     apm install <pkg> --target agent-skills
     apm install <pkg> --dry-run
   
   Or declare in apm.yml:
   
     targets:
       - agent-skills
   [!] Install interrupted after 0.6s.

4. Run apm targets as error message suggests

   (.venv)$ apm targets
     TARGET       STATUS     SOURCE                                   DEPLOY DIR
     ------------ ---------- ---------------------------------------- ----------
     claude       active     .claude/                                 .claude/
     copilot      inactive   needs .github/copilot-instructions.md    .github/
     cursor       inactive   needs .cursor/                           .cursor/
     codex        inactive   needs .codex/                            .codex/
     gemini       inactive   needs GEMINI.md                          .gemini/
     opencode     active     .opencode/                               .opencode/
     windsurf     inactive   needs .windsurf/                         .windsurf/

5. Observe agent-skills is not present in the output, despite being present in the apm install output.
   Expected behavior

• No error, as agent-skills was previously not producing one, and the error message suggests it is a valid target.
• agent-skills is listed by apm targets.

Environment (please complete the following information):

• OS: macOS
• Python Version: 3.14.3 (note, this is not a pre-release version as was flagged in a different bug report; it was released in Feb 2026)
• APM Version: 0.12.4
• VSCode Version (if relevant): n/a

Logs
Full log:

(.venv)$ apm --version
Agent Package Manager (APM) CLI version 0.12.4 (6aceef7)

pmounce at pmounce-Mac15,7 in ~/src/egen/awesome2 (pete/mise-bump)
(.venv)$ apm install
[>] Installing dependencies from apm.yml...
[x] [x] Unknown target '['agent-skills''

Valid targets: agent-skills, claude, codex, copilot, cursor, gemini, opencode, windsurf

Fix with one of:

  apm targets                            # see all supported harnesses
  apm install <pkg> --target agent-skills
  apm install <pkg> --dry-run

Or declare in apm.yml:

  targets:
    - agent-skills
[!] Install interrupted after 0.6s.

pmounce at pmounce-Mac15,7 in ~/src/egen/awesome2 (pete/mise-bump)
(.venv)$ apm targets
  TARGET       STATUS     SOURCE                                   DEPLOY DIR
  ------------ ---------- ---------------------------------------- ----------
  claude       active     .claude/                                 .claude/
  copilot      inactive   needs .github/copilot-instructions.md    .github/
  cursor       inactive   needs .cursor/                           .cursor/
  codex        inactive   needs .codex/                            .codex/
  gemini       inactive   needs GEMINI.md                          .gemini/
  opencode     active     .opencode/                               .opencode/
  windsurf     inactive   needs .windsurf/                         .windsurf/

Additional context
apm.yml:

---
name: foo
version: 0.0.1
description: Foo
author: Peter Mounce
dependencies:
  apm:
    - ./docs-as-code/content-root/standards/documenting/skills/docs-authoring
    - ./docs-as-code/content-root/standards/style-guides/skills/bash-authoring
    - ./docs-as-code/content-root/standards/style-guides/skills/code-authoring
    - ./docs-as-code/content-root/standards/style-guides/skills/git-commit
    - ./docs-as-code/content-root/standards/style-guides/skills/python-authoring
    - ./docs-as-code/content-root/standards/style-guides/skills/utility-scripts
    - Dicklesworthstone/beads_rust/.claude/skills/br#5cad749f1ed13a75e76bc95b776e47443b16c9bb
    - JuliusBrussee/caveman#ef6050c5e1848b6880ff47c32ade1a608a64f85e
    - microsoft/apm/packages/apm-guide#2b1fb6bfd42da6d7bcd14efdb0d87c5de7acc878
  mcp: []
scripts: {}
target:
  - agent-skills
  - claude
  - copilot
  - opencode

[petemounce]

Confirmed issue is present in 0.12.3 as well. I have reverted to 0.12.2 as the most recent usable version for my environment.

[danielmeppiel]

Thanks for the detailed report -- this one had two coupled symptoms, and both are addressed in main (unreleased) now:

1. The crash itself (Unknown target '['agent-skills'') is fixed by #1197 (already merged on main).

The root cause was the same as #1188: the singular target: parser branch was doing str(raw).split(",") on a Python list, producing tokens like "['agent-skills'". #1197 made the singular target: key accept the YAML list form (e.g. target: [copilot, claude]) the same way the plural targets: key always has.

I reproduced your exact symptom on 0.12.4 against both target: (singular, list) and targets: (plural, list); only the singular form crashes. On HEAD, both forms parse cleanly. Worth double-checking your local apm.yml -- the issue body shows targets: (plural) but the error text only manifests with the singular target: key carrying a list, so the file you actually had on disk almost certainly used singular target:.

2. The discoverability gap -- apm targets not listing agent-skills even though the error message advertised it -- is fixed by #1215 (just opened, against main).

agent-skills is a meta-target (multi-harness fan-out into .agents/skills/, no single deploy_dir) and is intentionally hidden from the apm targets table; it is surfaced only via apm targets --json --all for power users. The error renderer was advertising it anyway, which is exactly what made you (rightly) suspect APM was contradicting itself. #1215 filters agent-skills out of the unknown-target error suggestions so the recovery path printed on errors matches what the discovery command actually lists. It does NOT remove agent-skills from the canonical set: explicit --target agent-skills and targets: [agent-skills] in apm.yml continue to work for power users.

Shipping: both #1197 and #1215 land in the next minor release. Closing as solved on that basis -- please reopen if you still see either symptom on main (or once the next release ships).

[petemounce]

What's the reasoning behind both target and targets in the apm.yml, both evidently intended to support multiple items?

Would it be reasonable to introduce apm schema config|lock|policy [--output path] to write out jsonschema that one might validate the files against via pre-commit? That might also reduce user uncertainty in those files; a schema is easier to validate against vs docs prose, and that would also allow APM itself to reject bad input ¹ closer to its surface for a clearer UX.

Footnotes

1. via its own internal representation, I mean. Wouldn't lean on a file or remote call for something that can be internally represented. My thought was to serialise that representation to disk for a pre-commit to validate against. I'm not sure what apm's internal input handling is; I've had good experiences with pedantic in the past and I saw it has a schema generation hookup https://pydantic.dev/docs/validation/latest/concepts/json_schema/ ↩