AgentPort

Portable AI agent & skills framework. Write your agents and skills once, compile them for any IDE. Switch between IDEs without losing context.

The Problem

Every AI coding IDE has its own incompatible format:

| IDE | Rules File | Skills | Memory | |-----|-----------|--------|--------| | Claude Code | CLAUDE.md + .claude/ | .claude/skills/*/SKILL.md | Auto-memory | | Cursor | .cursorrules | .cursor/rules/*.mdc | Session-based | | Windsurf | .windsurfrules | .windsurf/rules/*.md | Cascade Memories | | VS Code Copilot | .github/copilot-instructions.md | N/A | Session-based | | Aider | CONVENTIONS.md | N/A | Convention-based |

When you hit a token limit or want to switch IDEs, you lose all your context, skills, and agent definitions. You have to rewrite everything from scratch.

The Solution

AgentPort gives you:

1. One portable format for skills and agents (Markdown + YAML frontmatter)
2. A compiler that generates IDE-specific configs for all 5 major IDEs
3. Context checkpointing so you can switch IDEs mid-task without losing progress

.agentport/          ← you write this (portable, version-controlled)
  skills/
  agents/
  state.json

     ↓ agentport compile cursor

.cursorrules         ← generated for your target IDE
.cursor/rules/

Quick Start

Install from npm

npm install -g agentport

Usage

# Initialize in your project
cd my-project
agentport init

# Compile for your current IDE
agentport compile claude-code

# When you hit a token limit, switch to another IDE
agentport switch cursor

From source (for contributors)

git clone https://github.com/akarshagrawal/agent-docker.git
cd agent-docker
npm install
npm run build
npm link

# Or run directly without linking
npx tsx bin/agentdock.ts init
npx tsx bin/agentdock.ts compile claude-code

CLI Commands

| Command | Description | |---------|-------------| | agentport init | Create .agentport/ with an example skill and agent | | agentport compile <target> | Generate IDE-specific config files | | agentport checkpoint -m "msg" | Save a context snapshot (todos, decisions, progress) | | agentport switch <target> | Checkpoint + clean old files + compile for new IDE | | agentport status | Show current state, tasks, and generated files |

Targets: claude-code, cursor, windsurf, copilot, aider

Defining Skills

Skills are reusable instruction sets. Create them in .agentport/skills/:

# .agentport/skills/code-reviewer.skill.md
---
name: code-reviewer
description: Reviews code for bugs, security, and style issues
version: 1.0.0
tags: [review, quality]
requires: []
triggers:
  - glob: "**/*.ts"
  - glob: "**/*.py"
---

# Code Reviewer

Review the provided code for:
1. Logical bugs and edge cases
2. Security vulnerabilities
3. Performance issues
4. Style consistency

Always suggest fixes, not just identify problems.

Skill Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Unique identifier | | description | Yes | One-line summary | | version | No | Semver (defaults to 1.0.0) | | tags | No | Categorization labels | | requires | No | Other skill names this depends on | | triggers | No | Glob patterns — skills with triggers become file-scoped rules in IDEs that support it |

Defining Agents

Agents compose skills and define a persona. Create them in .agentport/agents/:

# .agentport/agents/backend.agent.md
---
name: backend-developer
description: Backend-focused developer agent
skills:
  - code-reviewer
  - api-designer
---

# Backend Developer

You are a senior backend developer specializing in Node.js/TypeScript APIs.

## Conventions
- Use repository pattern for data access
- All endpoints return JSON envelope: { data, error, meta }
- Prefer composition over inheritance

Agent Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Unique identifier | | description | Yes | One-line summary | | skills | No | List of skill names to include (dependencies resolved automatically) | | context.include | No | Glob patterns for relevant files | | context.exclude | No | Glob patterns for files to ignore |

Switching IDEs

When you hit a token limit or want to continue in a different IDE:

# Save current progress and switch
agentport switch cursor -m "Implemented auth endpoints, need to add rate limiting next"

This does three things:

1. Checkpoints your current state (todos, decisions, conversation summary)
2. Cleans the previously generated IDE files
3. Compiles for the new target with context injected

The new IDE gets a ## Current Context section with your tasks, decisions, and summary so you can pick up right where you left off.

What Gets Generated

Claude Code

CLAUDE.md                          ← agent body + context
.claude/skills/<name>/SKILL.md     ← each skill as a native Claude skill
.claude/rules/<name>.md            ← trigger-based skills as rules

Cursor

.cursorrules                       ← agent body + inline skills + context
.cursor/rules/<name>.mdc           ← trigger-based skills as MDC rules

Windsurf

.windsurfrules                     ← agent body + inline skills + context
.windsurf/rules/<name>.md          ← trigger-based skills

VS Code Copilot

.github/copilot-instructions.md    ← agent body + all skills + context

Aider

CONVENTIONS.md                     ← agent body + all skills
.aider.conf.yml                    ← references CONVENTIONS.md
CONTEXT.md                         ← checkpoint context (if switching)

Context & State

Always-synced state (.agentport/state.json)

Lightweight file kept up to date continuously:

{
  "activeAgent": "backend-developer",
  "currentIDE": "claude-code",
  "todos": [
    { "id": "t1", "text": "Add rate limiting", "status": "pending" }
  ],
  "decisions": [
    { "id": "d1", "text": "Using JWT with refresh tokens", "reason": "Stateless API requirement" }
  ]
}

Checkpoints (.agentport/checkpoints/)

Full snapshots created on checkpoint or switch:

{
  "sourceIDE": "claude-code",
  "state": { "..." : "..." },
  "summary": "Implemented auth flow. Login works. Need refresh token rotation.",
  "filesModified": [
    { "path": "src/api/auth.ts", "changeDescription": "Added login endpoint" }
  ],
  "conversationSummary": "User asked for JWT auth. We chose rotation strategy...",
  "gitRef": "abc123f"
}

Skill Dependencies

Skills can depend on other skills via the requires field. Dependencies are resolved automatically with topological sorting:

# schema-validator.skill.md
name: schema-validator
requires: []

# api-designer.skill.md
name: api-designer
requires:
  - schema-validator

When an agent uses api-designer, schema-validator is automatically included. Circular dependencies are detected and rejected.

Development

# Clone and install
git clone https://github.com/akarshagrawal/agent-docker.git
cd agent-docker
npm install

# Run CLI in dev mode
npx tsx bin/agentdock.ts init
npx tsx bin/agentdock.ts compile claude-code

# Run tests
npm test

Project Structure

bin/agentdock.ts              CLI entry point
src/
  types.ts                    All TypeScript interfaces
  parser.ts                   Parses .skill.md/.agent.md + dependency resolution
  checkpoint.ts               Context checkpointing
  index.ts                    Public API exports
  compiler/
    base.ts                   Abstract compiler with shared formatting
    claude.ts                 Claude Code target
    cursor.ts                 Cursor target
    windsurf.ts               Windsurf target
    copilot.ts                VS Code Copilot target
    aider.ts                  Aider target
    index.ts                  Compiler registry
  cli/
    init.ts                   agentport init
    compile.ts                agentport compile
    checkpoint.ts             agentport checkpoint
    switch.ts                 agentport switch
    status.ts                 agentport status
examples/
  skills/                     Example skill definitions
  agents/                     Example agent definitions

Adding a New IDE Target

1. Create src/compiler/<name>.ts extending BaseCompiler
2. Implement the compile() method returning { files, target }
3. Register it in src/compiler/index.ts

import { BaseCompiler } from './base.js';
import type { CompileInput, CompileOutput } from '../types.js';

export class MyIDECompiler extends BaseCompiler {
  readonly target = 'my-ide' as const;

  compile(input: CompileInput): CompileOutput {
    // Transform portable format → IDE-specific files
    return { files: [...], target: this.target };
  }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

git clone https://github.com/akarshagrawal/agent-docker.git
cd agent-docker
npm install
npm test

License

MIT