Merge pull request #48 from danielmeppiel/feature/install-skills

feat: Claude Skills installation support

Author: danielmeppiel

CHANGELOG.md

@@ -6,6 +6,17 @@ 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.6.1] - 2025-12-08
+
+### Added
+
+- **SKILL.md as first-class primitive**: meta-description of what an APM Package does for agents to read
+- **Claude Skills Installation**: Install Claude Skills directly as APM Packages
+- **Bidirectional Format Support**: 
+  - APM packages → SKILL.md (for Claude target)
+  - Claude Skills → .agent.md (for VSCode target)
+- **Skills Documentation**: New `docs/skills.md` guide
+
 ## [0.6.0] - 2025-12-08
 
 ### Added

README.md

@@ -51,9 +51,10 @@ apm compile
 
 **One package. Every AI agent. Native format for each.**
 
-> 💡 **Install any `.prompt.md` or `.agent.md` directly from GitHub!**  
-> Explore ready-to-use prompts and agents at [github/awesome-copilot](https://github.com/github/awesome-copilot) and install them with a simple command:  
-> `apm install github/awesome-copilot/prompts/code-review.prompt.md`
+> 💡 **Install prompts, agents, and Claude Skills from anywhere!**  
+> Browse [github/awesome-copilot](https://github.com/github/awesome-copilot) or [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) and install with:  
+> `apm install github/awesome-copilot/prompts/code-review.prompt.md`  
+> `apm install ComposioHQ/awesome-claude-skills/brand-guidelines`
 
 ## Real Example: corporate-website
 
@@ -98,6 +99,9 @@ apm install dev.azure.com/org/project/repo
 
 # Single file (Virtual Package)
 apm install github/awesome-copilot/prompts/code-review.prompt.md
+
+# Claude Skills
+apm install ComposioHQ/awesome-claude-skills/brand-guidelines
 ```
 
 ## Create Your Own Package

docs/cli-reference.md

@@ -134,6 +134,9 @@ apm install danielmeppiel/design-guidelines
 # Add multiple packages and install
 apm install org/pkg1 org/pkg2
 
+# Install a Claude Skill from a subdirectory
+apm install ComposioHQ/awesome-claude-skills/brand-guidelines
+
 # Install only APM dependencies (skip MCP servers)
 apm install --only=apm
 
@@ -156,7 +159,13 @@ apm install --exclude codex
 - **With apm.yml**: Works as before - installs existing dependencies or adds new packages
 
 **Dependency Types:**
-- **APM Dependencies**: GitHub repositories containing `.apm/` context collections
+
+- **APM Dependencies**: GitHub repositories containing `apm.yml`
+- **Claude Skills**: Repositories with `SKILL.md` (auto-generates `apm.yml` upon installation)
+- **Virtual Packages**: Single files or collections installed directly from URLs
+  - Single `.prompt.md` or `.agent.md` files from any GitHub repository
+  - Collections from curated sources (e.g., `github/awesome-copilot`)
+  - Example: `apm install github/awesome-copilot/prompts/code-review.prompt.md`
 - **MCP Dependencies**: Model Context Protocol servers for runtime integration
 
 **Working Example with Dependencies:**

docs/concepts.md

@@ -154,7 +154,8 @@ Package your prompt engineering into reusable, configurable components:
 
 - **Instructions** (.instructions.md) - Context and coding standards
 - **Prompts** (.prompt.md) - Executable AI workflows  
-- **Chat Modes** (.chatmode.md) - AI assistant personalities
+- **Agents** (.agent.md) - AI assistant personalities
+- **Skills** (SKILL.md) - Package meta-guides for AI agents
 - **Context** (.context.md) - Project knowledge base
 
 ### Layer 3: Context Engineering
@@ -194,18 +195,33 @@ input: [auth_method, session_duration]
 Use ${input:auth_method} with ${input:session_duration} sessions
 ```
 
-### Chat Modes (.chatmode.md)
+### Agents (.agent.md)
 AI assistant personalities with tool boundaries:
 
 ```yaml
 ---
 name: "Backend Developer"
 model: "gpt-4"
+description: "Senior backend developer focused on API design"
 tools: ["terminal", "file-manager"] 
 ---
 You are a senior backend developer focused on API design and security.
 ```
 
+### Skills (SKILL.md)
+Package meta-guides that help AI agents understand what a package does:
+
+```yaml
+---
+name: Brand Guidelines
+description: Apply corporate brand standards
+---
+# How to Use
+Apply these colors and typography standards...
+```
+
+Skills provide AI agents with a quick summary of package purpose and usage.
+
 ### Context (.context.md)
 Optimized project knowledge for AI consumption: