[FEATURE] Allow customizing skill integration target directory

[tanbro]

Summary

APM hardcodes the skill integration directory per runtime (e.g., .claude/skills/ for Claude Code). Users should be able to customize this path to match their existing project structure.

Motivation

Projects may already have skills organized under a different directory (e.g., .agents/skills/) and want APM to integrate there instead of .claude/skills/. Currently there is no config option, CLI flag, or apm.yml field to control this.

Proposed solution

A per-project config option to override the integration target directory. For example:

• apm.yml field: skill_dir: .agents/skills
• CLI flag: apm install --skill-dir .agents/skills
• Or a runtime-level override: integrations.claude.skill_dir: .agents/skills

This would allow projects to maintain their preferred directory structure while still benefiting from APM's dependency management.

Workarounds currently needed

• Manually symlink from .claude/skills/ to .agents/skills/
• Disable integration and manage file placement outside of APM

[tanbro]

The auto-detection is also questionable. My project has both CLAUDE.md and opencode.jsonc at the root, yet APM blindly chose .claude/skills/ without checking which runtime the user actually intends to use — or whether the project already has a skills directory at a different path (e.g. .agents/skills/).

It would be better if APM:

1. Respects an existing skills directory in the project rather than hardcoding one
2. Lets the user explicitly choose the runtime/target when multiple runtime config files coexist

[danielmeppiel]

Triaged under the new portability/security/governance roadmap (see #116).

Thanks for opening this tanbro (@tanbro) -- the request is well-framed and the
follow-up comment about auto-detection is a real concern we want to
address.

Triage decision

needs-design -- the underlying request (override the integration
target directory per project) is sound and aligns with the Portable
pillar, but the design has to be settled before code lands. Concretely
we need to decide:

1. Surface. Is this an apm.yml field, an integrations.<runtime>
   sub-key, or a CLI flag (or all three with documented precedence)?
2. Per-target vs global. Does one override apply to all runtimes
   (Claude, Codex, OpenCode, Copilot, Cowork) or per-runtime only?
3. Path-safety contract. Custom paths must flow through
   validate_path_segments + ensure_path_within so they cannot
   escape the project root; that boundary needs to be explicit in the
   design.
4. Multi-runtime auto-detect. Your second comment surfaces a
   related bug -- when CLAUDE.md and opencode.jsonc both exist, APM
   should not silently pick one. That belongs in the same design.

Proposed labels

theme/portability
area/multi-target
type/feature
status/needs-design

Milestone

null -- no milestone until the design lands.

Suggested next action

If you want to drive this, a short design note (markdown OK) covering
the four points above would unblock implementation. Otherwise we will
draft one and link it back here for your review.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Real surface, real workaround pain (symlinking .claude/skills/ to
.agents/skills/ is a classic "package manager doesn't fit my repo
layout" smell). Familiar precedent: npm directories.lib, pip
--target, cargo [build] target-dir. The right answer is
likely a config field with optional CLI override, not a CLI-only
flag. Auto-detect ambiguity (your second comment) is the real
sharper edge -- needs an explicit --target requirement when
multiple runtimes are detected.

Supply Chain Security Expert -- Risk-Surface Reviewer

Touches area/multi-target and surfaces a path-safety boundary: any
user-supplied directory path becomes a write target for vendored
files. Must route through path_security.validate_path_segments and
ensure_path_within(<resolved>, project_root) -- never raw join.
Symlink-following must be evaluated. No theme escalation (this is
portability-primary), but the design must explicitly call out the
guard placement.

OSS Growth Hacker -- Contributor-Tone Reviewer

First-time contributor on microsoft/apm (1 prior interaction). Tone
should warmly acknowledge both the original request and the follow-up
comment, name the concrete next step (design note or we draft one),
and avoid jargon ("contract", "primitive") that we use internally.
The reply does that.

APM CEO -- Triage Arbiter

Customizable integration paths fit the Portable pillar -- APM has to
adapt to the project's existing layout, not impose its own. The
auto-detect-ambiguity follow-up is what tips this from accept to
needs-design: we cannot ship the override without also fixing the
silent-pick bug. Ratifying needs-design, primary
theme/portability, no milestone.

[tanbro]

Thank you for the detailed triage. I want to provide additional context
that I believe reveals a fundamental design gap in APM's current model.

My actual use case

I'm building Agent Workspaces — complete environments containing multiple
skills, tools, and configurations — targeted at various agent runtimes
(OpenCode, OpenClaw, Hermes-Agent).

The workflow:

1. I use Claude Code as a development / writing assistant
2. The workspace contains skills in .agents/skills/, and tools, scripts, configs, etc.
3. The complete workspace is consumed by AI Agents like OpenClaw (target runtime)

Why this matters: APM conflates two different things

APM currently assumes that the agents I use during development are the
same as the runtime my workspace targets:

Evidence	APM assumes	Reality
CLAUDE.md exists	"This project runs on Claude Code"	"I used Claude Code as a dev assistant"
opencode.jsonc exists	"This project runs on OpenCode"	"I'm building FOR OpenCode, not WITH it"

This is a fundamental confusion: development tools ≠ target runtime.

What I need from APM

I'd like APM to serve as an Agent Workspace manager, not just a skill
package manager. For workspace creators, this means:

• Explicit control over workspace structure (skills dir, tools dir, etc.)
• Per-project configuration — each workspace targets a different runtime
• No auto-detection — as a workspace creator, I know my target runtime
• Respect existing layouts — don't force APM's conventions on my workspace

Design implications from the four points

1. Surface — Per-project apm.yml configuration is essential; CLI flags
   are optional conveniences, not the primary interface

2. Scope — "Per-target" doesn't fit my mental model. I need "per-project"
   because project = target workspace. My opencode project ≠ my openclaw project

3. Path-safety — Agreed, but also ensure APM never creates files outside
   the configured boundaries. Auto-detection that creates .claude/skills/
   uninvited is violating workspace boundaries

4. Auto-detect — For workspace creators, auto-detection is an
   anti-feature. We need explicit --target declaration to specify intent.
   When multiple runtime configs coexist, requiring an explicit choice is a
   feature, not a bug

The "skill workspace creator" persona

I believe "skill/workspace creator" is a distinct user persona that APM hasn't
designed for:

Persona	Goal	Current APM support
Coding agent user	Use agents to build software	✅ Well-supported
Skill/workspace creator	Build workspaces FOR agents	❌ Not designed for

The maintainer response mentions auto-detect ambiguity as a "bug" — but for
workspace creators, any auto-detection that creates files is problematic.
We don't want APM to guess; we want to declare.

---

I'm happy to provide a more detailed design doc if helpful, but wanted to
establish that this isn't just about directory paths — it's about APM
recognizing workspace creators as first-class users with different needs
than coding agent users.

Thank you for the thoughtful triage and for considering this use case.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/multi-target
area/docs-site
type/feature
status/needs-design
help wanted

Milestone

null

Suggested next action

Design the config surface for skill-dir override: specify whether it is an apm.yml field, a CLI flag, or a per-runtime config entry, and define how overridden paths interact with the lockfile and path-security validation.

Suggested issue comment

Thanks for the clear use case -- projects with pre-existing skill directory structures should not have to symlink or disable integration to work with APM.

The feature direction is sound, but the right config surface needs design before code lands:

- An `apm.yml` field (`skill_dir: .agents/skills`) applies project-wide across all runtimes.
- A CLI flag (`apm install --skill-dir .agents/skills`) applies per-invocation.
- A per-runtime override in `apm.yml` (`integrations.claude.skill_dir: .agents/skills`) allows different targets to write to different directories.

Each option has different implications for the lockfile (which records deployed file paths), for `apm uninstall` (which must know where to clean up), and for path security (customized paths must be validated with `validate_path_segments` and `ensure_path_within` before any file is written).

Before code can land safely, the config surface and lockfile interaction need to be agreed on. We welcome a design proposal as a comment on this issue or as a linked discussion.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Real friction point: projects with pre-existing skill directories (e.g. .agents/skills/ instead of .claude/skills/) must symlink or disable integration. The proposed override is a standard customization affordance. Three config-surface options are reasonable (apm.yml field, CLI flag, per-runtime override). The per-runtime option is the most powerful but also the most complex. The simpler apm.yml field is probably the right MVP.

Supply Chain Security Expert -- Risk-Surface Reviewer

A customizable integration directory is a path traversal concern. If users can set skill_dir: ../../../evil, APM would write files outside the project root. validate_path_segments and ensure_path_within from path_security.py must guard the customized path before any file operation. This is a hard implementing-PR requirement. No theme/security needed for triage, but the design must include a path-security section.

OSS Growth Hacker -- Contributor-Tone Reviewer

tanbro has author_association: NONE -- first-time or low prior interaction with microsoft/apm. The reply should be warm and welcoming. The issue is well-formed and technically clear. Point to the design discussion pathway and explicitly invite contribution. help wanted signals that community design input is welcome.

Python Architect -- Architecture Reviewer

The config surface options each have non-trivial implications: (1) apm.yml field -- how does it interact with the lockfile when the deployed path changes? (2) CLI flag -- how does uninstall know which path was used? (3) per-runtime override in apm.yml -- adds schema complexity. The design must answer: what does the lockfile record when a custom dir is used? How does apm uninstall know where to clean up? Path security is a hard requirement. status/needs-design is correct.

Doc Writer -- Documentation Reviewer

Any new apm.yml field or CLI flag will need documentation in the package authoring guide and the CLI reference. area/docs-site is warranted as a secondary label. The suggested comment wording is clear and grounded in APM user vocabulary.

APM CEO -- Triage Arbiter

needs-design confirmed. The config surface (apm.yml vs. CLI flag vs. per-runtime) must be decided, and the lockfile and path-security implications must be specified before any code lands. No milestone; design-first. Warm reply for a NONE-association author with a well-formed issue. help wanted encourages community design contribution.

{
  "decision": "needs-design",
  "decision_detail": "Config surface (apm.yml field vs. CLI flag vs. per-runtime override), lockfile interaction when custom dir is used, and path-security validation requirements must be designed before code lands.",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": ["help wanted"],
  "milestone": null,
  "next_action": "Design the config surface (apm.yml field vs. CLI flag vs. per-runtime override) and define lockfile interaction and path-security validation for custom integration directories.",
  "comment_markdown": "Thanks for the clear use case -- projects with pre-existing skill directories should not have to symlink or disable integration.\n\nThe config surface needs design: (1) apm.yml project-wide field; (2) CLI flag per invocation; (3) per-runtime override. Each option has different implications for the lockfile and for `apm uninstall`. Path security is a hard requirement: customized paths must pass `validate_path_segments` and `ensure_path_within` before any file is written.\n\nWe welcome a design proposal as a comment here."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.6M · ◷

[danielmeppiel]

tanbro (@tanbro) I agree with the declarative principle. You can use targets: in the manifest, and now apm by default puts skills in .agents folder for those harnessess that support the agentskills.io standard. However that destination folder is not configurable in the manifest today. I am wondering, in which case would you put them somewhere else, given harnessess don't generally load them unless they're placed in such specific folders?