[FEATURE] Promote sub-skills inside packages to top-level `.github/skills/` entries

[sergio-sisternes-epam]

Feature

Allow APM packages to ship multiple independently-discoverable skills within a single package. Sub-skills placed under .apm/skills/<name>/SKILL.md should be promoted to top-level entries in .github/skills/<name>/ during apm install, so that Copilot can discover and invoke each one independently.

Motivation

Copilot only scans direct children of .github/skills/ for SKILL.md files — it does not recurse into nested directories. Today, if a package contains sub-skills (e.g., a monorepo package shipping both modernization agents and an Azure naming skill), only the parent package's SKILL.md is discoverable. The sub-skills are buried inside the parent tree and invisible to the IDE.

Proposed behavior

Given a package with this structure:

agent-library/
└── acme-bookstore/
    ├── SKILL.md
    ├── apm.yml
    └── .apm/
        └── skills/
            └── azure-naming/
                └── SKILL.md

After apm install org/agent-library/acme-bookstore, the resulting layout should be:

.github/skills/
├── acme-bookstore/          # Parent skill
│   └── SKILL.md
└── azure-naming/            # Promoted sub-skill
    └── SKILL.md

This way Copilot discovers both skills and can invoke azure-naming independently.

Design notes

• Sub-skills live under .apm/skills/ to match the existing authoring convention (all primitives under .apm/).
• Only directories containing a SKILL.md are promoted — other files/dirs are ignored.
• Name collisions with existing top-level skills produce a warning and overwrite.
• Promoted sub-skills are also synced to .claude/skills/ when a .claude/ directory exists.
• apm deps sync preserves promoted sub-skills (does not mark them as orphaned).

Context

Per the VS Code agent skills spec, skill discovery scans .github/skills/<name>/SKILL.md — only direct children. This feature closes the gap for monorepo-style agent libraries shipping multiple skills per package.

[sergio-sisternes-epam]

Rationale: why this gap exists and why it matters

The current skill integration was designed around a one package = one skill assumption. When a package has a SKILL.md at its root, APM treats the entire package directory as a single, atomic skill unit and copies it wholesale via copytree. This made sense for simple, single-purpose skill packages where the package IS the skill.

However, this assumption breaks down for composite packages — monorepo-style agent libraries where a parent package bundles reusable sub-skills in a skills/*/ convention. The parent SKILL.md describes the overarching capability, while each sub-skill provides a focused, independently-invocable piece of domain knowledge (e.g., naming conventions, migration checklists).

The root cause is a mismatch between two contracts:

1. The authoring contract: Package authors can nest sub-skills under skills/*/SKILL.md to organize related capabilities hierarchically.
2. The runtime contract: VS Code/Copilot only discovers skills at .github/skills/<name>/SKILL.md — direct children, no recursion.

APM satisfies contract (1) by preserving the full directory tree, but violates contract (2) because nested sub-skills end up at .github/skills/parent/skills/child/SKILL.md — a path Copilot never inspects. The sub-skills are physically present but invisible to the runtime.

This is not an edge case. The skills/*/ convention is the natural way to organize multi-skill packages (we use it in our own agent-library), and any package author shipping more than one skill will hit this silently — sub-skills simply won't appear in Copilot's skill list with no error or warning.