microsoft · danielmeppiel · Dec 19, 2025 · Dec 19, 2025 · Dec 19, 2025 · Dec 19, 2025
@@ -61,4 +61,7 @@ docs/wip/
 .env.*.local
 AGENTS.md
 PRD.md
-PRD*.md
+PRD*.md
+# Internal planning documents
+skill-plan.md
+skill-strategy.md
@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.7.0] - 2025-12-19
+
+### Changed
+
+- **Native Skills Support**: Skills now install to `.github/skills/` as the primary target (per [agentskills.io](https://agentskills.io/) standard)
+- **Skills ≠ Agents**: Removed skill → agent transformation; skills and agents are now separate primitives
+- **Explicit Package Types**: Added `type` field to apm.yml (`instructions`, `skill`, `hybrid`, `prompts`) for routing control
+- **Skill Name Validation**: Validates and normalizes skill names per agentskills.io spec (lowercase, hyphens, 1-64 chars)
+- **Claude Compatibility**: Skills also copy to `.claude/skills/` when `.claude/` folder exists
+
+### Added
+
+- Auto-creates `.github/` directory on install if neither `.github/` nor `.claude/` exists
+
 ## [0.6.3] - 2025-12-09
 
 ### Fixed

@@ -224,8 +224,13 @@ When you run `apm install`, APM automatically integrates primitives from install
 APM also integrates with Claude Code when `.claude/` directory exists:
 
 - **Commands**: `.prompt.md` files → `.claude/commands/*-apm.md`
-- **Skills**: Skill packages → `.claude/skills/{folder-name}/` (copies entire folder)
-- **APM packages**: Packages with `.apm/` primitives → `.claude/skills/{folder-name}/SKILL.md` (generated)
+
+**Skill Integration:**
+
+Skills are copied directly to target directories:
+
+- **Primary**: `.github/skills/{skill-name}/` — Entire skill folder copied
+- **Compatibility**: `.claude/skills/{skill-name}/` — Also copied if `.claude/` folder exists
 
 **Example Integration Output**:
 ```
@@ -270,7 +275,7 @@ apm uninstall danielmeppiel/design-guidelines --dry-run
 | Integrated agents | `.github/agents/*-apm.agent.md` |
 | Integrated chatmodes | `.github/agents/*-apm.chatmode.md` |
 | Claude commands | `.claude/commands/*-apm.md` |
-| Skill folders | `.claude/skills/{folder-name}/` |
+| Skill folders | `.github/skills/{folder-name}/` |
 
 **Behavior:**
 - Removes package from `apm.yml` dependencies
@@ -632,8 +637,8 @@ target: vscode  # or claude, or all
 
 | Target | Output Files | Best For |
 |--------|--------------|----------|
-| `vscode` | AGENTS.md, .github/prompts/, .github/agents/ | GitHub Copilot, Cursor, Codex, Gemini |
-| `claude` | CLAUDE.md, .claude/commands/, .claude/skills/, SKILL.md | Claude Code, Claude Desktop |
+| `vscode` | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Codex, Gemini |
+| `claude` | CLAUDE.md, .claude/commands/, SKILL.md | Claude Code, Claude Desktop |
 | `all` | All of the above | Universal compatibility |
 
 **Examples:**

@@ -41,7 +41,7 @@ target: vscode  # or claude, or all
 | `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](integrations.md) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.claude/commands/`, and `.claude/skills/`.
+> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](integrations.md) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, and `.claude/commands/`.
 
 ### How It Works
 

@@ -41,20 +41,20 @@ apm install ComposioHQ/awesome-claude-skills/brand-guidelines
 
 #### Skill Integration During Install
 
-When your project has a `.claude/` folder, skills are integrated automatically:
+Skills are integrated to `.github/skills/`:
 
 | Source | Result |
 |--------|--------|
-| Package with existing `SKILL.md` | Skill folder copied to `.claude/skills/{folder-name}/` |
-| APM package with `.apm/` primitives (no SKILL.md) | SKILL.md auto-generated, folder copied to `.claude/skills/{folder-name}/` |
+| Package with existing `SKILL.md` | Skill folder copied to `.github/skills/{folder-name}/` |
+| APM package with `.apm/` primitives (no SKILL.md) | SKILL.md auto-generated, folder copied to `.github/skills/{folder-name}/` |
 | Package without SKILL.md or primitives | No skill folder created |
 
 #### Skill Folder Naming
 
 Skill folders use the **source folder name directly** (not flattened paths):
 
 ```
-.claude/skills/
+.github/skills/
 ├── brand-guidelines/      # From ComposioHQ/awesome-claude-skills/brand-guidelines
 ├── mcp-builder/           # From ComposioHQ/awesome-claude-skills/mcp-builder
 └── compliance-rules/      # From danielmeppiel/compliance-rules

@@ -389,10 +389,10 @@ apm install
 For VSCode/Copilot (when `.github/` exists):
 - `.github/prompts/*-apm.prompt.md` - Reusable prompt templates
 - `.github/agents/*-apm.agent.md` - Agent definitions
+- `.github/skills/{folder-name}/` - Skills with `SKILL.md` meta-guide
 
 For Claude Code (when `.claude/` exists):
 - `.claude/commands/*-apm.md` - Slash commands
-- `.claude/skills/{folder-name}/` - Skills with `SKILL.md` meta-guide
 
 > **Tip:** Both integrations can coexist in the same project. APM installs to all detected targets.
 
@@ -665,8 +665,8 @@ apm deps list         # 🔗 Show installed APM dependencies
 - `SKILL.md` - Package meta-guide for AI discovery
 - `AGENTS.md` - Generated VSCode/Copilot instructions
 - `CLAUDE.md` - Generated Claude Code instructions
-- `.github/prompts/`, `.github/agents/` - Installed VSCode primitives
-- `.claude/commands/`, `.claude/skills/` - Installed Claude primitives
+- `.github/prompts/`, `.github/agents/`, `.github/skills/` - Installed VSCode primitives and skills
+- `.claude/commands/` - Installed Claude commands
 - `apm_modules/` - Installed APM dependencies
 - `*.prompt.md` - Executable agent workflows
 

@@ -226,7 +226,7 @@ When you run `apm install`, APM integrates package primitives into Claude's nati
 | Location | Purpose |
 |----------|---------||
 | `.claude/commands/*.md` | Slash commands from installed packages (from `.prompt.md` files) |
-| `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
+| `.github/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
 
 ### Automatic Command Integration
 
@@ -250,23 +250,23 @@ apm install danielmeppiel/design-guidelines
 
 ### Automatic Skills Integration
 
-APM automatically integrates skills from installed packages into `.claude/skills/`:
+APM automatically integrates skills from installed packages into `.github/skills/`:
 
 ```bash
 # Install a package with skills
 apm install ComposioHQ/awesome-claude-skills/mcp-builder
 
 # Result:
-# .claude/skills/mcp-builder/SKILL.md    → Skill available in Claude
-# .claude/skills/mcp-builder/...         → Full skill folder copied
+# .github/skills/mcp-builder/SKILL.md    → Skill available for agents
+# .github/skills/mcp-builder/...         → Full skill folder copied
 ```
 
 **Skill Folder Naming**: Uses the source folder name directly (e.g., `mcp-builder`, `design-guidelines`), not flattened paths.
 
 **How skill integration works:**
 1. `apm install` checks if the package contains a `SKILL.md` file
-2. If `SKILL.md` exists: copies the entire skill folder to `.claude/skills/{folder-name}/`
-3. If no `SKILL.md` but package has `.apm/` primitives: auto-generates `SKILL.md` in `.claude/skills/{folder-name}/`
+2. If `SKILL.md` exists: copies the entire skill folder to `.github/skills/{folder-name}/`
+3. If no `SKILL.md` but package has `.apm/` primitives: auto-generates `SKILL.md` in `.github/skills/{folder-name}/`
 4. Updates `.gitignore` to exclude generated skills
 5. `apm uninstall` removes the skill folder
 
@@ -318,12 +318,12 @@ apm compile --target claude
 #    /gdpr-assessment → Runs GDPR compliance check
 
 # 4. CLAUDE.md provides project instructions automatically
-# 5. Skills in .claude/skills/ are available for Claude to reference
+# 5. Skills in .github/skills/ are available for agents to reference
 ```
 
 ### Claude Desktop Integration
 
-Skills installed to `.claude/skills/` are automatically available in Claude Desktop. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files.
+Skills installed to `.github/skills/` are automatically available for AI agents. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files.
 
 ### Cleanup and Sync
 

@@ -37,21 +37,28 @@ When you run `apm install`, APM handles skill integration automatically:
 ### Step 1: Download to apm_modules/
 APM downloads packages to `apm_modules/owner/repo/` (or `apm_modules/owner/repo/skill-name/` for subdirectory packages).
 
-### Step 2: Skill Integration (if `.claude/` exists)
-When your project has a `.claude/` folder, APM integrates skills:
+### Step 2: Skill Integration
+APM copies skills directly to `.github/skills/` (primary) and `.claude/skills/` (compatibility):
 
 | Package Type | Behavior |
 |--------------|----------|
-| **Has existing SKILL.md** | Entire skill folder copied to `.claude/skills/{folder-name}/` |
-| **Has `.apm/` primitives but no SKILL.md** | SKILL.md auto-generated, folder copied to `.claude/skills/{folder-name}/` |
+| **Has existing SKILL.md** | Entire skill folder copied to `.github/skills/{skill-name}/` |
 | **No SKILL.md and no primitives** | No skill folder created |
 
+**Target Directories:**
+- **Primary**: `.github/skills/{skill-name}/` — Works with Copilot, Cursor, Codex, Gemini
+- **Compatibility**: `.claude/skills/{skill-name}/` — Only if `.claude/` folder already exists
+
 ### Skill Folder Naming
 
-Skills use the **source folder name directly**:
+Skill names are validated per the [agentskills.io](https://agentskills.io/) spec:
+- 1-64 characters
+- Lowercase alphanumeric + hyphens only
+- No consecutive hyphens (`--`)
+- Cannot start/end with hyphen
 
 ```
-.claude/skills/
+.github/skills/
 ├── mcp-builder/           # From ComposioHQ/awesome-claude-skills/mcp-builder
 ├── design-guidelines/     # From danielmeppiel/design-guidelines
 └── compliance-rules/      # From danielmeppiel/compliance-rules
@@ -231,14 +238,13 @@ APM automatically detects package types:
 
 ## Target Detection
 
-APM decides where to output based on project structure:
+APM decides where to output skills based on project structure:
 
-| Condition | Target | Skill Output |
-|-----------|--------|--------------|
-| `.github/` exists | VSCode | `.github/agents/*.agent.md` |
-| `.claude/` exists | Claude | Native SKILL.md |
-| Both exist | All | Both outputs |
-| Neither | Minimal | AGENTS.md only |
+| Condition | Skill Output |
+|-----------|---------------|
+| `.github/` exists | `.github/skills/{skill-name}/SKILL.md` |
+| `.claude/` also exists | Also copies to `.claude/skills/{skill-name}/SKILL.md` |
+| Neither exists | Creates `.github/skills/` |
 
 Override with:
 ```bash
@@ -320,16 +326,16 @@ Error: Could not find SKILL.md or apm.yml
 apm install owner/repo/subdirectory
 ```
 
-### Agent Not Generated
+### Skill Name Validation Error
 
-If `.github/agents/*.agent.md` isn't created:
+If you see a skill name validation warning:
 
-1. **Check target:** Create `.github/` folder or use `--target vscode`
-2. **Reinstall:** Run `apm install package-name` again
+1. **Check naming:** Names must be lowercase, 1-64 chars, hyphens only (no underscores)
+2. **Auto-normalization:** APM automatically normalizes invalid names when possible
 
 ### Metadata Missing
 
-If agent lacks APM metadata:
+If skill lacks APM metadata:
 
 1. Check the skill was installed via APM (not manually copied)
 2. Reinstall the package

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.6.3"
+version = "0.7.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.9"