# Compile Apm Package

> Activate when the user wants to compile an APM package into top-level context documents such as AGENTS.md, CLAUDE.md, or GEMINI.md, especially for Codex, Gemini, OpenCode, or agents-protocol style hosts. Do not use when the user only needs per-skill installation; use install-apm-package instead.

- Skill: `richfrem/compile-apm-package` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add richfrem/compile-apm-package`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richfrem/compile-apm-package/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: richfrem (https://skillmd.com/u/richfrem)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/richfrem/compile-apm-package

---


# compile-apm-package Skill 📄

## Overview
This skill generates merged context documents from APM primitives. This is primarily required for harnesses that consume a single authoritative file (like Gemini's `GEMINI.md`) rather than distributed skill directories.

## 🚫 Non-Negotiables
1. **Artifact Status** — Compiled files (`AGENTS.md`, etc.) are generated artifacts. NEVER edit them directly if a `.apm/` source tree exists.
2. **Conditional Use** — Do not run compile if the user's harness (e.g., Claude Code, Copilot Chat) supports native directory-based skills.
3. **Validation First** — Ensure the package is valid before merging primitives.

## Decision Tree
1. **Target supports directory-based skills?** -> Use `install-apm-package`.
2. **Target needs top-level context?** (e.g., Gemini, Codex) -> Run `apm compile`.
3. **Authoring shared context?** -> Use `apm compile` to verify how fragments merge into the final doc.

## Workflow
1. Verify `apm.yml` existence.
2. Execute `python scripts/validate_apm_package.py`.
3. Identify target requirements.
4. Run `apm compile [--target <slug>]`.
5. Report the location of generated context files.

## Anti-Patterns
- **Unnecessary Compilation**: Running `apm compile` for a Claude Code project (redundant work).
- **Direct Artifact Editing**: Fixing a typo in `GEMINI.md` instead of the source `.prompt.md`.