richfrem/agent-plugins-skills / plugins/agent-extension-authoring/.apm/skills/packaging-with-apm
packaging-with-apm
FlaggedPackages, installs and distributes agent extensions with APM (Agent Package Manager). Use when the user wants to create a new APM package, convert or migrate an existing plugin to APM and check it installs cleanly, compile a package into AGENTS.md, CLAUDE.md or GEMINI.md, install, update, pin or roll back packages globally or per project, or create a plugin marketplace catalog (marketplace.json). Not for authoring a single skill, plugin, sub-agent or rule (use the authoring-* skills).
scripts/migrate_to_apm.py
View on GitHub#!/usr/bin/env python
"""
migrate_to_apm.py (CLI)
=====================================
Purpose:
Analyzes an existing Claude plugin and implements an APM integration path
(Overlay, Hybrid, or Full).
Key Input Dependencies:
- Existing Claude plugin directory structure (plugin.json, skills/, agents/, etc.)
- PyYAML for configuration file generation
- pathlib.Path for directory traversal
- shutil for directory operations
Layer: Codify / Migration
"""
import argparse
import os
import json
import yaml
import shutil
import sys
import re
from pathlib import Path
from datetime import datetime
# Windows encoding safety
if sys.platform == "win32":
try:
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
except (AttributeError, Exception): pass
def generate_governance_doc(mode: str, lane: str, package_name: str) -> str:
"""Generate governance documentation based on migration mode (full, hybrid, overlay)."""
if mode == "full":
return (f"# Governance: {package_name}\nMode: {mode}\nLane: {lane}\n\n"
f"## Principle\nThis package has been converted to an APM-native layout. "
f"The `.apm/` directory is the canonical source tree for APM-managed primitives. "
f"The original plugin source remains preserved outside this converted package and "
f"should not be modified by this conversion.\n")
elif mode == "hybrid":
return (f"# Governance: {package_name}\nMode: {mode}\nLane: {lane}\n\n"
f"## Principle\nPlugin-native primitives remain in place. `.apm/` is used for "
f"new APM-native governance assets or future primitives.\n")
else: # overlay
return (f"# Governance: {package_name}\nMode: {mode}\nLane: {lane}\n\n"
f"## Principle\nThe plugin remains the source package. APM adds governance, "
f"manifest, lockfile, audit, and distribution metadata.\n")
def generate_policy_doc(package_name: str) -> str:
"""Generate APM enterprise policy template with allowed sources and review requirements."""
return f"# APM Enterprise Policy: {package_name}\n# TEMPLATE ONLY: replace allowed_sources before enterprise use.\nallowed_sources: [\"internal-registry.company.com\"]\nreview_required:\n primitive_types: [agent, hook, mcp]\n risk_classification: medium\n"
def dereference_content(path: Path) -> str:
"""Reads content, following relative path pointers if found."""
if not path.exists(): return ""
with open(path, "r", encoding='utf-8') as f:
content = f.read().strip()
# Simple heuristic: if content is a single line starting with ../ or ./, it's a pointer
if content.count('\n') == 0 and (content.startswith("../") or content.startswith("./")):
ptr_path = (path.parent / content).resolve()
if ptr_path.exists() and ptr_path.is_file():
with open(ptr_path, "r", encoding='utf-8') as f: return f.read()
with open(path, "r", encoding='utf-8') as f: return f.read()
def _load_plugin_metadata(source: Path) -> tuple[Path, dict]:
"""Load .claude-plugin/plugin.json metadata if present. Returns (manifest_path, plugin_data)."""
manifest_path = source / ".claude-plugin" / "plugin.json"
plugin_data = {}
if manifest_path.exists():
with open(manifest_path, "r", encoding='utf-8') as f: plugin_data = json.load(f)
return manifest_path, plugin_data
def _resolve_dest_root(source: Path, mode: str, output_path, output_exact, output_name, name: str, dry_run: bool) -> Path:
"""Resolve the destination root directory for the migration, per mode."""
if mode == "full":
if output_exact:
dest_root = Path(output_exact).resolve()
elif output_path:
target_name = output_name if output_name else name
dest_root = Path(output_path).resolve() / target_name
else:
print("❌ Error: --output or --output-exact required for 'full' mode."); sys.exit(1)
if dest_root.exists() and not dry_run:
print(f"❌ Error: Output path '{dest_root}' already exists. Aborting."); sys.exit(1)
else:
dest_root = source
return dest_root
def _build_migration_plan(source: Path, mode: str) -> dict:
"""Build the copy/convert plan and detect script-path warnings/prompt collisions."""
plan = {"created": [], "copied": [], "converted": [], "warnings": [], "collisions": []}
# 1. Plan Phase
if mode == "full":
dest_prompts = set()
if (source / "prompts").exists():
for p in (source / "prompts").glob("*.prompt.md"):
dest_prompts.add(p.name)
plan["copied"].append(f"prompts/{p.name}")
if (source / "commands").exists():
for cmd in (source / "commands").glob("*.md"):
normalized = f"{cmd.stem}.prompt.md"
if normalized in dest_prompts:
plan["collisions"].append(f"commands/{cmd.name} and prompts/ both map to .apm/prompts/{normalized}")
dest_prompts.add(normalized)
plan["converted"].append(f"commands/{cmd.name} -> .apm/prompts/{normalized}")
for folder in ["skills", "agents", "hooks", "instructions"]:
if (source / folder).exists():
plan["copied"].append(f"{folder}/")
for mcp in [".mcp.json", "mcp-servers.json", "mcp.json"]:
if (source / mcp).exists():
plan["copied"].append(f"{mcp}")
# Heuristic: Check for potential script path issues
for skill_dir in (source / "skills").glob("*"):
if (skill_dir / "scripts").exists():
for script in (skill_dir / "scripts").glob("*.py"):
with open(script, "r", encoding='utf-8', errors='ignore') as f:
script_content = f.read()
if 'resources' in script_content and 'assets' not in script_content:
plan["warnings"].append(f"Script {script.relative_to(source)} contains 'resources' but no 'assets' fallback.")
return plan
def _print_dry_run(source: Path, dest_root: Path, mode: str, governance: str, manifest_path: Path, plan: dict) -> None:
"""Print the dry-run preview of the migration plan."""
print(f"\n--- DRY RUN: {mode.upper()} ---")
print(f"Source: {source}")
print(f"Dest: {dest_root}")
print(f"Lane: {governance}")
print(f"Metadata Source: {'.claude-plugin/plugin.json' if manifest_path.exists() else 'Folder name'}")
if mode == "full":
print(f"Plan: {len(plan['copied'])} items to copy, {len(plan['converted'])} commands to convert.")
for c in plan["copied"]: print(f" [COPY] {c}")
for c in plan["converted"]: print(f" [CONV] {c}")
if plan["warnings"]:
print(f"Warnings: {len(plan['warnings'])}")
for w in plan["warnings"]: print(f" [WARN] {w}")
def _copy_full_mode_primitives(source: Path, apm_dir: Path) -> None:
"""Copy skills/agents/hooks/instructions, prompts, converted commands, and MCP configs into .apm/."""
apm_dir.mkdir(exist_ok=True)
for folder in ["skills", "agents", "hooks", "instructions"]:
if (source / folder).exists():
shutil.copytree(source / folder, apm_dir / folder, dirs_exist_ok=True)
(apm_dir / "prompts").mkdir(exist_ok=True)
if (source / "prompts").exists():
for p in (source / "prompts").glob("*.prompt.md"):
shutil.copy2(p, apm_dir / "prompts" / p.name)
if (source / "commands").exists():
for cmd in (source / "commands").glob("*.md"):
dst_file = apm_dir / "prompts" / f"{cmd.stem}.prompt.md"
with open(cmd, "r", encoding='utf-8') as f: content = f.read()
with open(dst_file, "w", encoding='utf-8') as f:
f.write(f"<!-- Migrated from plugin command: {cmd.name} -->\n" + content)
for mcp in [".mcp.json", "mcp-servers.json", "mcp.json"]:
if (source / mcp).exists():
(apm_dir / "mcp").mkdir(exist_ok=True)
shutil.copy2(source / mcp, apm_dir / "mcp" / mcp)
def _dereference_requirements(source: Path, apm_dir: Path) -> None:
"""Resolve relative-pointer requirements.* files under .apm/ against the SOURCE tree."""
for req_file in apm_dir.rglob("requirements.*"):
if req_file.is_file():
with open(req_file, "r", encoding='utf-8') as f:
raw_content = f.read().strip()
# If it's a relative pointer (../ or ./), resolve against SOURCE
if raw_content.count('\n') == 0 and (raw_content.startswith("../") or raw_content.startswith("./")):
# Calculate where it would have pointed in the SOURCE tree
rel_to_apm = req_file.relative_to(apm_dir)
source_file_loc = source / rel_to_apm
actual_ptr_target = (source_file_loc.parent / raw_content).resolve()
if actual_ptr_target.exists() and actual_ptr_target.is_file():
with open(actual_ptr_target, "r", encoding='utf-8') as f:
final_content = f.read()
with open(req_file, "w", encoding='utf-8') as f:
f.write(final_content)
def _write_full_mode_readme(source: Path, dest_root: Path, name: str, mode: str, governance: str) -> None:
"""Write the destination README, banner-prefixed with the original if one exists."""
readme_path = source / "README.md"
if readme_path.exists():
with open(readme_path, "r", encoding='utf-8') as f: original_readme = f.read()
banner = ("> [!NOTE]\n"
"> This package was converted from a Claude plugin into an APM-native package.\n"
"> APM-managed source primitives now live under `.apm/`.\n"
"> The original plugin README below is preserved for historical context.\n\n---\n\n")
with open(dest_root / "README.md", "w", encoding='utf-8') as f:
f.write(banner + original_readme)
else:
with open(dest_root / "README.md", "w", encoding='utf-8') as f:
f.write(f"# {name}\n\nMigrated from {source}\nMode: {mode}\nLane: {governance}\n")
def _execute_full_mode(source: Path, dest_root: Path, apm_dir: Path, name: str, mode: str, governance: str) -> None:
"""Run the full-mode migration: copy primitives, dereference requirements, write README."""
_copy_full_mode_primitives(source, apm_dir)
_dereference_requirements(source, apm_dir)
_write_full_mode_readme(source, dest_root, name, mode, governance)
def _execute_hybrid_mode(apm_dir: Path, name: str, plan: dict) -> None:
"""Scaffold the .apm/ governance layer for hybrid-mode migration."""
apm_dir.mkdir(parents=True, exist_ok=True)
(apm_dir / "prompts").mkdir(exist_ok=True)
(apm_dir / "instructions").mkdir(exist_ok=True)
with open(apm_dir / "README.md", "w", encoding='utf-8') as f:
f.write(f"# APM Governance Layer\nThis directory stores APM governance assets for the {name} hybrid package.\n")
plan["created"].append(".apm/")
def _write_final_assets(
source: Path, dest_root: Path, manifest_path: Path, name: str, version: str,
description: str, author: str, mode: str, governance: str, plan: dict,
output_exact, output_path, dry_run: bool
) -> None:
"""Write apm.yml manifest, docs/governance.md, optional policy, and migration-notes.md."""
manifest = {
"name": name, "version": version, "description": description, "author": author,
"targets": ["copilot", "claude", "cursor"],
"includes": "auto",
"metadata": {
"packaging_mode": mode, "governance_lane": governance,
"source_layout": "claude-plugin" if manifest_path.exists() else "unknown",
"source_plugin_manifest": str(manifest_path) if manifest_path.exists() else None,
"generated_at": datetime.now().isoformat()
}
}
with open(dest_root / "apm.yml", "w", encoding='utf-8') as f: yaml.dump(manifest, f, sort_keys=False)
# Optional Snapshot
if manifest_path.exists() and mode == "full":
(dest_root / "docs" / "source-plugin").mkdir(parents=True, exist_ok=True)
shutil.copy2(manifest_path, dest_root / "docs" / "source-plugin" / "plugin.json")
docs_dir = dest_root / "docs"
docs_dir.mkdir(exist_ok=True)
with open(docs_dir / "governance.md", "w", encoding='utf-8') as f: f.write(generate_governance_doc(mode, governance, name))
policy_gen = False
if governance == "enterprise":
with open(dest_root / "apm-policy.yml", "w", encoding='utf-8') as f: f.write(generate_policy_doc(name))
policy_gen = True
with open(docs_dir / "migration-notes.md", "w", encoding='utf-8') as f:
f.write(f"# Migration Notes\nSource: {source}\nDest: {dest_root}\nMode: {mode}\nLane: {governance}\n\n")
f.write(f"## Evidence\n- Dry run performed: {'Yes' if dry_run else 'No'}\n")
f.write(f"- Requested output: {output_exact or output_path or 'Source dir'}\n")
f.write(f"- Actual output: {dest_root}\n\n")
f.write(f"## Metadata Source\n{'.claude-plugin/plugin.json' if manifest_path.exists() else 'Folder name'}\n\n")
f.write(f"## Copied Primitives\n" + "\n".join(plan["copied"]) + "\n\n")
f.write(f"## Converted Commands\n" + "\n".join(plan["converted"]) + "\n\n")
if plan["warnings"]:
f.write(f"## Heuristic Warnings (Review Required)\n" + "\n".join(plan["warnings"]) + "\n\n")
f.write(f"## Enterprise Policy Generated\n{'Yes' if policy_gen else 'No'}\n\n")
f.write(f"## Collision Status\n{'No collisions detected' if not plan['collisions'] else 'Collisions resolved during planning'}\n\n")
f.write(f"## Validation\nRun: python scripts/validate_apm_package.py --path {dest_root}\n")
f.write(f"## Recommended Next Step\n/os-loop or manual primitive authoring in .apm/\n")
def migrate_to_apm(
source_path: str,
output_path: str = None,
output_exact: str = None,
mode: str = "overlay",
governance: str = "experimental",
dry_run: bool = False,
output_name: str = None
) -> None:
"""Migrate Claude plugin to APM format with specified mode (overlay/hybrid/full)."""
source = Path(source_path).resolve()
if not source.exists():
print(f"❌ Error: Source path '{source}' does not exist."); sys.exit(1)
manifest_path, plugin_data = _load_plugin_metadata(source)
name = plugin_data.get("name", source.name)
version = plugin_data.get("version", "1.0.0")
description = plugin_data.get("description", f"Migrated APM {mode} for {name}")
author = plugin_data.get("author", {}).get("name", "Unknown") if isinstance(plugin_data.get("author"), dict) else plugin_data.get("author", "Unknown")
dest_root = _resolve_dest_root(source, mode, output_path, output_exact, output_name, name, dry_run)
plan = _build_migration_plan(source, mode)
# CRITICAL: Abort on collision (Priority 1)
if plan["collisions"]:
print(f"❌ Collisions detected in migration plan:")
for c in plan["collisions"]: print(f" - {c}")
if not dry_run: sys.exit(1)
if dry_run:
_print_dry_run(source, dest_root, mode, governance, manifest_path, plan)
return
# 2. Execution Logic
dest_root.mkdir(parents=True, exist_ok=True)
apm_dir = dest_root / ".apm"
if mode == "full":
_execute_full_mode(source, dest_root, apm_dir, name, mode, governance)
elif mode == "hybrid":
_execute_hybrid_mode(apm_dir, name, plan)
# 3. Final Assets
_write_final_assets(
source, dest_root, manifest_path, name, version, description, author,
mode, governance, plan, output_exact, output_path, dry_run
)
print(f"✅ Migration complete! Result at {dest_root}")
def main() -> None:
"""Parse CLI arguments and migrate Claude plugin to APM format."""
parser = argparse.ArgumentParser(description="Plugin to APM Migrator")
parser.add_argument("--source-path", required=True, dest="source_path")
parser.add_argument("--output", dest="output_path")
parser.add_argument("--output-exact", dest="output_exact", help="Unambiguous destination path")
parser.add_argument("--output-name", dest="output_name")
parser.add_argument("--mode", default="overlay", choices=["overlay", "hybrid", "full"])
parser.add_argument("--governance", default="experimental", choices=["experimental", "team", "enterprise"])
parser.add_argument("--dry-run", action="store_true")
migrate_to_apm(**vars(parser.parse_args()))
if __name__ == "__main__": main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |