AgentPM™

init#

Scaffold a new AgentPM package by generating a starter agent.json manifest for a tool, skill, knowledge, memory, profile, loop, agent, or template package.

Overview#

agentpm init creates the minimal manifest you’ll complete later. Choose a kind (tool, skill, knowledge, memory, profile, loop, agent, or template), set a name/description, and optionally an output directory.

Command synopsis#

agentpm init [--kind <tool|skill|knowledge|memory|profile|loop|agent|template>] [--mode <context|vector>] [--name <string>] [--description <string>] [--out-dir <path>]

Arguments#

  • --kind (default: tool). What to scaffold: a single tool, a procedural skill, a knowledge package, a memory blueprint package, an instruction profile package, a loop package, a composed agent, or a workflow template package.
  • --mode (default: context). Only used with --kind knowledge. Choose context for direct context documents or vector for a prepared retrieval corpus starter.
  • --name (default: my-tool). Name for the tool/agent (used in the manifest).
  • --description (default: Starter AgentPM project). Short human-readable description.
  • --out-dir. Directory to write files to (defaults to current working directory).
Tip

Use --out-dir ./my-project to keep each package in its own folder.

Examples#

Create an agent#

agentpm init --kind agent --name research-assistant --description "Assistant composed of multiple tools"

Generates agent.json:

{
  "kind": "agent",
  "name": "research-assistant",
  "version": "0.1.0",
  "description": "Assistant composed of multiple tools",
  "tools": [],
  "skills": [],
  "knowledge": [],
  "memory": [],
  "profiles": [],
  "examples": [
    {
      "title": "Example prompt",
      "prompt": "Describe the user request this agent should handle."
    }
  ]
}

Create a skill#

agentpm init --kind skill --name incident-commander --description "Incident response coordination playbook"

Creates:

incident-commander/
  agent.json
  SKILL.md

Generates agent.json:

{
  "kind": "skill",
  "name": "incident-commander",
  "version": "0.1.0",
  "description": "Incident response coordination playbook",
  "tools": [],
  "skill": {
    "entrypoint": "SKILL.md"
  }
}

Create a tool#

agentpm init --kind tool --name summarize --description "Summarize input text"

Generates agent.json:

{
  "kind": "tool",
  "name": "summarize",
  "version": "0.1.0",
  "description": "Summarize input text",
  "files": [],
  "entrypoint": {
    "command": "",
    "args": []
  },
  "inputs": {},
  "outputs": {}
}

Create a knowledge package#

agentpm init --kind knowledge --name engineering-playbook --description "Engineering playbook intended for direct context loading"

Creates:

engineering-playbook/
  agent.json
  README.md
  knowledge/
    docs/
      context.md

Generates agent.json:

{
  "kind": "knowledge",
  "name": "engineering-playbook",
  "version": "0.1.0",
  "description": "Engineering playbook intended for direct context loading",
  "knowledge": {
    "mode": "context",
    "content_type": "documentation",
    "documents": [
      {
        "path": "knowledge/docs/context.md",
        "content_type": "text/markdown",
        "role": "context",
        "description": "Starter context document."
      }
    ],
    "retrieval": {
      "strategy": "full_context"
    }
  }
}

The generated README.md is also mode-specific and explains the direct-context workflow rather than the vector workflow.

For a vector-mode starter:

agentpm init --kind knowledge --mode vector --name python-docs --description "Prepared retrieval corpus for Python documentation"

Creates:

python-docs/
  agent.json
  README.md
  knowledge/
    chunks.jsonl
    sources.jsonl
    embeddings/

Generates agent.json:

{
  "kind": "knowledge",
  "name": "python-docs",
  "version": "0.1.0",
  "description": "Prepared retrieval corpus for Python documentation",
  "knowledge": {
    "mode": "vector",
    "content_type": "documentation",
    "corpus": {
      "chunks_path": "knowledge/chunks.jsonl",
      "sources_path": "knowledge/sources.jsonl"
    },
    "embedding": {
      "id": "default",
      "provider": "custom",
      "model": "unknown",
      "dimensions": 1536,
      "metric": "cosine",
      "normalized": true,
      "vectors_path": "knowledge/embeddings/default.f32"
    },
    "retrieval": {
      "strategy": "vector"
    }
  }
}

The generated README.md for vector mode explains the prepared corpus placeholders and calls out that knowledge/indexes/default is generated later by agentpm knowledge build.

Create a memory blueprint#

agentpm init --kind memory --name conversation-continuity --description "Describe the durable memory contract this blueprint provides."

Creates:

conversation-continuity/
  agent.json
  README.md
  schemas/
    user-preference.schema.json

Generates agent.json:

{
  "kind": "memory",
  "name": "conversation-continuity",
  "version": "0.1.0",
  "description": "Describe the durable memory contract this blueprint provides.",
  "readme": "README.md",
  "memory": {
    "scopes": {
      "user": {
        "description": "The user whose memory is being retained."
      }
    },
    "record_types": {
      "user_preference": {
        "version": "1.0.0",
        "description": "Durable structured preferences for one user.",
        "schema": "schemas/user-preference.schema.json"
      }
    },
    "spaces": {
      "profile": {
        "description": "The current durable profile for one user.",
        "model": "document",
        "record_types": ["user_preference"],
        "scope": ["user"],
        "retrieval": {
          "modes": ["key"]
        }
      }
    }
  }
}

The generated README.md explains the authored files, when to run agentpm memory build, how to use agentpm memory inspect, and that the blueprint does not provide a live memory store by itself.

Create a loop#

agentpm init --kind loop --name incident-response-loop --description "Portable incident triage and response loop"

Creates:

incident-response-loop/
  agent.json
  README.md

Generates agent.json:

{
  "kind": "loop",
  "name": "incident-response-loop",
  "version": "0.1.0",
  "description": "Portable incident triage and response loop",
  "readme": "README.md",
  "loop": {
    "archetype": "investigate_review_respond",
    "entry_phase": "assess",
    "phases": [
      {
        "id": "assess",
        "objective": "Assess the request and decide whether work should proceed.",
        "outcomes": [
          {
            "id": "proceed",
            "description": "The work should move forward."
          },
          {
            "id": "handoff",
            "description": "The work should be handed off."
          }
        ]
      },
      {
        "id": "execute",
        "objective": "Perform the active work for the request."
      },
      {
        "id": "review",
        "objective": "Review whether the work is complete or needs another pass.",
        "outcomes": [
          {
            "id": "needs-more-work",
            "description": "Another execution pass is required."
          },
          {
            "id": "ready",
            "description": "The work is complete and ready to end."
          }
        ]
      }
    ],
    "transitions": [
      { "from": "assess", "on": "proceed", "to": "execute" },
      { "from": "assess", "on": "handoff", "to": "$handoff" },
      { "from": "execute", "on": "complete", "to": "review" },
      { "from": "review", "on": "needs-more-work", "to": "execute" },
      { "from": "review", "on": "ready", "to": "$end" }
    ]
  }
}

The generated README.md explains Loop versus Agent responsibilities, implicit complete, graph-defined control flow, and that the README is documentation only.

Create an instruction profile#

agentpm init --kind profile --name support-style --description "Portable support communication profile"

Creates:

support-style/
  agent.json
  README.md

Generates agent.json:

{
  "kind": "profile",
  "name": "support-style",
  "version": "0.1.0",
  "description": "Portable support communication profile",
  "readme": "README.md",
  "profile": {
    "identity": {
      "role": "Customer support assistant"
    },
    "objectives": [
      "Resolve the user's issue clearly and efficiently."
    ],
    "communication": {
      "tone": ["calm", "helpful"],
      "verbosity": "balanced"
    }
  }
}

The generated README.md explains the Profile-versus-Skill boundary, notes that constraints express author intent rather than runtime enforcement, and clarifies that README text is package documentation rather than executable runtime instruction.

Create a workflow template#

agentpm init --kind template --name research-template --description "Bootstrap a research workflow"

Creates:

research-template/
  agent.json
  template/
    README.md

Generates agent.json:

{
  "kind": "template",
  "name": "research-template",
  "version": "0.1.0",
  "description": "Bootstrap a research workflow",
  "template": {
    "display_name": "Research Template",
    "use_case": "starter",
    "execution_surfaces": ["agentpm-run"],
    "files_root": "template",
    "variables": [
      {
        "name": "project_name",
        "description": "Generated project name. Generation-time only; do not use for API keys, tokens, passwords, or runtime secrets.",
        "required": true,
        "default": "research-template"
      }
    ],
    "dependencies": {
      "tools": [],
      "agents": []
    },
    "entrypoints": [
      {
        "label": "Review generated scaffold",
        "command": "cat README.md"
      }
    ]
  }
}

agentpm init --kind template does not create consumer output like template/agent.json.

What's next?#

The generated manifests are intentional skeletons—you’ll need to finish them before you can install, new, or publish.

  • For agents:
    • Add tools to the tools[] array (via agentpm install <tool> or by editing then running agentpm install).
    • Replace the placeholder example prompt with a real user request your agent should handle.
    • Leave dependency arrays empty unless you intentionally want the agent to resolve them.
  • For tools:
    • Fill in entrypoint.command (and args if needed).
    • Define inputs and outputs schemas.
    • List any packaged artifacts in files[] (scripts, models, prompts, etc.).
  • For skills:
    • Author SKILL.md.
    • Add tool refs to tools[] when the skill depends on runnable packages.
    • Add optional skill.references, skill.scripts, and descriptive skill.compatibility metadata.
  • For templates:
    • Fill in the template package metadata, variables, dependencies, and entrypoints.
    • Add scaffold files under template/ (or your chosen template.files_root).
    • Keep registry docs in the root README.md and generated-project docs in template/README.md.
    • Use agentpm new . ../my-template-test to verify the scaffold locally before publishing.
  • For knowledge packages:
    • Replace the placeholder files under knowledge/ with your real content.
    • Keep mode: "context" for direct context bundles, or use --mode vector when starting a prepared retrieval corpus.
    • Run agentpm knowledge build before publishing so the derived metadata and local vector index are current.
  • For memory packages:
    • Replace the starter schema and authored memory metadata with the real scopes, record types, spaces, and optional lifecycle operations your blueprint needs.
    • Run agentpm memory build before publishing so memory/build.json and the generated contracts are current.
    • Use agentpm memory inspect to verify the authored metadata, generated contracts, and freshness status before publishing.
  • For profile packages:
    • Fill in the authored profile structure with real identity, objectives, communication guidance, and any optional constraints.
    • Keep README content as package documentation; the structured profile object is the runtime-facing contract.
    • Do not add runtime fields, build output, parameters, variables, or install-time prompts.
  • For loop packages:
    • Replace the starter phases, outcomes, and transitions with the real control-flow contract you want to publish.
    • Keep loop packages declarative: author phases, checkpoints, limits, and error policy metadata, but do not add runtime/provider configuration.
    • Use agentpm lint to validate graph semantics locally before publishing.

Run a quick check:

agentpm lint
Tip

Lint helps you catch missing fields, schema issues, and versioning problems early.

After linting and completing the manifest:

  • Use agentpm install to fetch declared tools, skills, knowledge, memory, profiles, and an optional loop (for agents) or declared tools (for skills).
  • Use agentpm new to verify local or published templates.
  • When ready to share, head to agentpm publish.

Notes & gotchas#

  • Naming: Choose a unique name—it’s surfaced in the registry and in your namespaces.
  • Versioning: init seeds 0.1.0. Bump versions semantically as your package evolves.
  • Subprocess runtime: Tools execute in a managed subprocess; define any required environment variables in the manifest so hosts know what to set.
←CLIInstall
→CLIlogin