Agent Portability Kit

Agent Portability Kit (apk) is a cross-platform converter for AI-agent assets. Its goal is to make skills, agents, rules/context, MCP server configs, and package metadata portable between agent ecosystems without relying on one developer's local setup.

The project is intentionally built as a portable compiler:

Claude / Codex / Cline / Generic source files
        ↓ scan + import
Portable intermediate representation
        ↓ plan + validate
Codex / Cline / Neutral output

The stable v1 product promise is:

Point the kit at a repository directory or validated zip/tar package and get a safe, deterministic dry-run plan for converting its skills, agents, rules, MCP config, and package metadata into Codex, Cline, or neutral output.

Home-directory discovery remains experimental and read-only. The tool does not write global configuration or publish packages without separate explicit approval.

Project context

This repo started as a Codex skill converter, but the real scope is broader:

• convert Claude Code .claude/skills, .claude/agents, and .claude/contexts
• convert Codex .agents/skills, AGENTS.md, and MCP config snippets
• convert Cline .cline/skills, .clinerules, and MCP JSON
• keep MCP secrets out of generated files
• work across Windows, Linux, macOS, WSL, containers, and CI
• avoid "works on my system" assumptions by keeping the core pure Python

The current version is v0.2.0, which improves skill and agent conversion while retaining the portable compiler architecture.

Current status

v0.2.0 includes:

• Python 3.11+ package with console command apk
• portable dataclass model for discovered artifacts and generated files
• source scanning for Claude, Codex, Cline, and generic agent files
• dry-run conversion planning
• Codex, Cline, and neutral emitters
• secret detection and withholding
• generated-file markers
• overwrite protection
• validation before writing
• audit output under .agent-portability/
• unit tests and fixtures
• safe byte-for-byte copying of skill scripts/, references/, and assets/
• explicit compatibility signals and agent-to-skill/rule classification
• target-native, secret-safe Codex and Cline skill frontmatter
• Codex skill wrapper under skills/agent-portability-kit/
• Codex plugin skeleton under .codex-plugin/
• previous standalone scripts preserved under legacy/

What it can scan today

Source	Artifacts
Claude Code	.claude/skills/*/SKILL.md, .claude/agents/*.md, .claude/contexts/*.md, CLAUDE.md
Codex	.agents/skills/*/SKILL.md, AGENTS.md, .codex/config.toml
Cline	.cline/skills/*/SKILL.md, .clinerules/*.md, .cline/mcp.json
Generic	GEMINI.md, README.agent.md

Output targets

Codex output:

.agents/skills/{skill}/SKILL.md
.agents/AGENTS.md
.agent-portability/codex-mcp-snippets.toml

Cline output:

.cline/skills/{skill}/SKILL.md
.clinerules/{rule}.md
.agent-portability/cline-mcp-snippets.json

Neutral output:

portable-output/manifest.json
portable-output/skills/{skill}/SKILL.md
portable-output/rules/{rule}.md
portable-output/mcp/mcp.json

Audit output:

.agent-portability/inventory.json
.agent-portability/plan.json
.agent-portability/validation.json
.agent-portability/run.json

Safety rules

The project should preserve these rules as non-negotiable behavior:

1. Dry-run is the default.
2. Existing user-authored files are not overwritten unless explicitly approved.
3. Generated files include AUTO-GENERATED by agent-portability-kit markers.
4. Secret-looking content is withheld or converted to environment-variable references.
5. No raw MCP token/API key/password should appear in generated output.
6. No OS-specific shell, PowerShell, registry, or profile behavior should exist in the conversion core.
7. Platform-specific behavior belongs under adapters/.
8. The same scan/plan should be reproducible across Windows, Linux, macOS, WSL, containers, and CI.

Install for development

From the repo root:

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS:

. .venv/bin/activate
python -m pip install -e .

Verify the CLI:

apk --version
apk --help

Run tests

python -m compileall -q src tests tools
python -m unittest discover -s tests -v

Jenkins CI

The root Jenkinsfile runs the test suite on native Jenkins agents for Windows, Linux, and macOS with Python 3.11, 3.12, and 3.13. Agents must have both an operating-system label (windows, linux, or macos) and a Python label (python-3.11, python-3.12, or python-3.13); python must resolve to that version on the selected agent.

Normal builds run only the cross-platform verification matrix. Set the BUILD_RELEASE_INTEGRITY parameter to generate and archive release-integrity.json on a linux && python-3.13 agent. Jenkins controller configuration is responsible for multibranch discovery and SCM webhook triggers.

Basic usage

Scan a repo:

apk scan --source .

Scan with JSON output:

apk scan --source . --json

Dry-run conversion to Codex and Cline:

apk convert --source . --target both --include skills,agents,rules,mcp --mode dry-run

Generate files after reviewing the plan:

apk convert --source . --target both --include skills,agents,rules,mcp --mode generate

MCP-only dry-run:

apk mcp convert --source . --target both --secret-mode env --mode dry-run

Package skeleton dry-run:

apk package --source . --format codex-plugin --mode dry-run

Run without installing by setting PYTHONPATH:

Windows PowerShell:

$env:PYTHONPATH="$PWD\src"
python -m agent_portability_kit scan --source .

Linux/macOS:

PYTHONPATH="$PWD/src" python -m agent_portability_kit scan --source .

Working with Codex on this repo

Open a terminal in the repo root and run:

codex

Recommended first Codex prompt:

Read AGENTS.md, README.md, NEXT_STEPS.md, ROADMAP.md, and MANIFEST.md. Then run the tests. Do not edit files yet. Summarize the current architecture and propose the smallest safe v0.3.0 MCP implementation plan.

Recommended second prompt:

Implement NEXT_STEPS.md v0.3.0 task 1: add a typed PortableMcpServer IR and align the MCP schema. Keep the core standard-library-only, add tests, and do not parse or emit MCP configs yet.

Repo layout

agent-portability-kit/
├── AGENTS.md                         Codex handoff/project instructions
├── README.md                         Project overview and usage
├── NEXT_STEPS.md                     Concrete implementation steps
├── ROADMAP.md                        Version-level roadmap
├── MANIFEST.md                       Important files and directories
├── pyproject.toml                    Python package metadata
├── src/agent_portability_kit/        Main Python package
├── skills/agent-portability-kit/     Codex skill wrapper
├── .codex-plugin/plugin.json         Codex plugin skeleton
├── legacy/                           Preserved standalone scripts
└── tests/                            Fixtures and smoke tests

Important modules

Path	Purpose
src/agent_portability_kit/cli.py	CLI entrypoint and command routing
src/agent_portability_kit/models.py	Portable intermediate representation
src/agent_portability_kit/scan.py	Source discovery and inventory
src/agent_portability_kit/classify.py	Compatibility classification
src/agent_portability_kit/planner.py	Conversion plan construction
src/agent_portability_kit/emitters/	Target-native output generation
src/agent_portability_kit/validate.py	Validation and safety checks
src/agent_portability_kit/writer.py	Safe writes and audit output
src/agent_portability_kit/utils/security.py	Secret detection
src/agent_portability_kit/adapters/	OS/platform-specific edge behavior

Development principles

• Build importers and emitters around the portable IR, not direct source-to-target hacks.
• Prefer deterministic code over LLM-only transformations.
• Add fixture tests for every new source/target behavior.
• Preserve raw source files unless a user explicitly approves changes.
• Keep generated output target-native: Codex should look like Codex, Cline should look like Cline.
• Keep CLI output useful for humans and --json output useful for automation.

Version milestones

v0.2.0 adds safe sidecar copying, stronger classification, target-native frontmatter normalization, and expanded fixtures.

The active v0.3.0 milestone focuses on first-class MCP conversion:

• add a typed portable MCP server IR and schema
• parse Codex TOML MCP configs into portable MCP server objects
• parse Cline MCP JSON into portable MCP server objects
• replace inline secrets with environment-variable references or withhold them
• emit real target-native snippets
• generate platform-specific wrappers only through adapters
• plan safe merge/diff operations without modifying global config
• migrate only safe rendering behavior from legacy/mcp_envkit.py

Same-target skill normalization is deferred beyond v0.3.0.

The full v0.3.0 through v1.0.0 release train, acceptance gates, and deferred work are defined in V1_PLAN.md. ROADMAP.md is the concise summary and NEXT_STEPS.md contains only the active milestone queue.