Claude skills silently skipped when CLAUDE.md exists but .claude/ directory does not

[tillig]

Summary

When a project has a CLAUDE.md file (strong signal that Claude Code is in use) but no .claude/ directory, apm install and apm compile --targets all silently skip Claude skill deployment. No warning is emitted, and the user has no indication that Claude was excluded from skill integration.

To Reproduce

1. Start with a repo that has CLAUDE.md and .github/ but no .claude/ directory:

   CLAUDE.md          ← exists (file)
   .github/           ← exists (directory)
   apm.yml            ← no explicit target: field
   

2. Run apm install followed by apm compile --targets all

3. Observe that .agents/skills/ is populated (for Copilot, Cursor, Codex, etc.) but .claude/skills/ is never created.

Expected behavior

One of:

• .claude/skills/ is created and populated (since CLAUDE.md indicates Claude Code usage), OR
• A warning is emitted explaining that Claude skill deployment was skipped because .claude/ does not exist, with guidance on how to enable it (e.g., "create .claude/ or set target: claude in apm.yml")

Root cause

Three factors combine to produce the silent skip:

1. Auto-detection doesn't see Claude. target_detection.py:167 checks (project_root / ".claude").exists() — this looks for a path literally named .claude, not for CLAUDE.md. A project with only CLAUDE.md (no .claude/ directory) does not register Claude as a detected target.

2. auto_create=False for Claude. Even when --targets all resolves and includes Claude in the target list, the directory-creation loop in install/phases/targets.py:161 skips it:

   if not _t.auto_create and not _explicit:
       continue

   The --targets all value from auto-detection (triggered by ≥2 detected folders) is not considered "explicit" in the _explicit variable sense (which tracks --target CLI flag or apm.yml target: field).

3. Skill integrator bails out. skill_integrator.py:341 independently guards on the directory:

   if not target.auto_create and not target_root_dir.is_dir():
       continue

   So even if Claude somehow ends up in the resolved target set, skills aren't deployed.

Relationship to existing issues

• [BUG] apm install never deploys local .apm/ primitives to .claude/ because claude isn't a registered runtime #751 (closed): Described apm install --target claude silently skipping deployment. Fixed by PR fix: create target dir for explicit --target claude; content hash fallback when .git absent #763, which gates directory creation on _explicit — so explicit --target claude or target: claude in apm.yml now works correctly. The scenario here is different: no explicit target is set, and the user relies on auto-detection.

• Scope-awareness gaps: hook integrator, auto_create, integration tests #576 (closed): Identified that install.py was creating directories for auto_create=False targets under --target=all (P1-4). The fix correctly gated mkdir on auto_create — but didn't account for the case where a project clearly uses Claude (evidenced by CLAUDE.md) without having a .claude/ directory yet.

Workarounds

Any of:

• mkdir .claude before running apm install
• Add target: claude (or target: all) to apm.yml

Neither is documented, and the behavior is surprising for users who expect CLAUDE.md to be sufficient signal.

Possible approaches

A few options (not prescriptive — just thinking out loud):

1. Expand auto-detection: Treat the existence of CLAUDE.md as equivalent to .claude/ for target detection purposes.
2. Emit a warning: When Claude is in the resolved target set but .claude/ doesn't exist, log a message suggesting the user create it or set an explicit target.
3. Treat --targets all as explicit: When the user passes --targets all on the CLI, treat it the same as an explicit target for the auto_create guard (distinct from auto-detected "all").

Environment

• APM: v0.12.2 (2b1fb6b)
• OS: macOS 15.5 (Darwin 25.4.0)
• Claude Code: 1.0.33

[tillig]

Before I submit a PR for this, I'm curious how the project team would like to resolve it. It seems like there's some sort of migration away from compiling everything into a central CLAUDE.md (or AGENTS.md or whatever) and into using the .agents or .claude folders instead.

If it was up to me...

• --targets all would actually mean all targets - and it'd generate whatever was required for Claude even if it wasn't already present.
• It wouldn't matter if CLAUDE.md was there already or not, if the .claude/ folder needed to be created based on the set of targets, it would be created and populated.

This somewhat relates to my other issue where things in .claude/rules get doubled into CLAUDE.md. It could potentially mean that there is no CLAUDE.md but there is totally a .claude folder, all of which should come out of apm. Thus the presence or absense of CLAUDE.md wouldn't have quite as much impact on whether .claude/ needs to be created - it would be entirely based on the target being specified. For auto-detection, either a .claude/ folder or CLAUDE.md would signify Claude usage.