Intelligence Package (IP) File Specification

This document defines the format and semantics of .ip.yaml files used by IpMan.

Overview

An IP file is a skill manifest — a YAML file that declares a set of skills to install, along with metadata and dependencies on other IP packages. Anyone with an IP file can run ipman install <file>.ip.yaml to install all referenced skills in one command.

File Structure

# IpMan Intelligence Package — https://github.com/twisker/ipman
# Install: ipman install <this-file>.ip.yaml

name: <package-name>
version: "<semver>"
description: "<brief description>"
author:
  name: "<author name>"
  github: "@<github-username>"
license: <license-identifier>

skills:
  - name: <skill-name>
  # ... more skills

dependencies:
  - name: <ip-package-name>
    version: "<version-constraint>"
  # ... more dependencies

Header Comment

IP files generated by IpMan automatically include a header comment with: - A link to the IpMan project repository - A one-line install command

This ensures anyone who receives an IP file knows how to use it.

Fields

Package Metadata

Field	Required	Description
`name`	Yes	Package short name (lowercase + digits + hyphens, 3-50 chars)
`version`	Yes	Semantic version of this IP package (major.minor.patch)
`description`	Yes	Brief description of what this skill collection does
`author`	No	Author info (`name` and/or `github`)
`license`	No	License identifier (e.g. MIT, Apache-2.0)

Skills

The skills list declares which skills to install. Each entry supports two modes:

IpHub Mode (recommended)

Reference a skill by its short name registered on IpHub:

skills:
  - name: web-scraper
  - name: css-helper
    version: "1.0.0"

At install time, IpMan resolves the name via IpHub's index, retrieves the agent-specific install source, and calls the agent's native CLI.

Note: The version field is optional and records the installed version at pack time (for reproducibility). Agent CLIs always install the latest version from the source — the version field is informational, not a constraint.

Direct Source Mode

Specify agent-specific install parameters directly, bypassing IpHub:

skills:
  - name: our-internal-tool
    description: "Optional description"
    source:
      claude-code:
        plugin: "our-tool@our-marketplace"
        marketplace: "https://github.com/ourorg/claude-plugins"
      openclaw:
        slug: "our-internal-tool"
        hub: "https://internal-hub.ourorg.com"

This mode is useful for: - Private/internal skills not published to IpHub - Skills hosted on non-default marketplaces or hubs

The installer detects the mode automatically: if source is present, it uses direct mode; otherwise, it uses IpHub mode.

Direct Source Fields

For Claude Code:

Field	Required	Description
`plugin`	Yes	Plugin identifier (e.g. `name@marketplace`)
`marketplace`	No	Custom marketplace GitHub repo URL

For OpenClaw:

Field	Required	Description
`slug`	Yes	Skill slug on ClawHub
`hub`	No	Custom ClawHub URL (default: `https://clawhub.com`)

Dependencies

The dependencies list declares other IP packages that must be installed first. Like skills, dependencies support two modes:

IpHub Mode

dependencies:
  - name: base-utils
    version: ">=1.0.0"

IP package versions are fully controlled — IpHub stores each version as a separate file. Version constraints are resolved against the available versions on IpHub.

Direct Source Mode

dependencies:
  # Local file
  - name: team-toolkit
    source: "./team-toolkit.ip.yaml"

  # Remote URL
  - name: shared-skills
    source: "https://example.com/shared.ip.yaml"

Direct-source dependencies point to a specific .ip.yaml file (local path or URL). The file itself represents a specific version, so no version field is needed.

Version Constraint Syntax

Version constraints apply only to IpHub IP package dependencies (not to skills).

Syntax	Meaning
`>=1.2.0`	Greater than or equal to 1.2.0
`^1.3.0`	Compatible updates (>=1.3.0, <2.0.0)
`~1.3.0`	Patch updates only (>=1.3.0, <1.4.0)
`1.2.0`	Exact version

Complete Example

# IpMan Intelligence Package — https://github.com/twisker/ipman
# Install: ipman install frontend-kit.ip.yaml

name: frontend-kit
version: "2.0.0"
description: "Frontend development skill collection"
author:
  name: "Twisker"
  github: "@twisker"
license: MIT

skills:
  # Public skills (IpHub)
  - name: css-helper
  - name: a11y-checker

  # Private skill (direct source)
  - name: our-design-system
    description: "Internal design system skills"
    source:
      claude-code:
        plugin: "design-system@our-plugins"
        marketplace: "https://github.com/ourorg/claude-plugins"
      openclaw:
        slug: "our-design-system"
        hub: "https://internal-hub.ourorg.com"

dependencies:
  # Public IP package (IpHub, version constraint)
  - name: base-utils
    version: ">=1.0.0"

  # Internal IP file (direct source)
  - name: team-standards
    source: "https://raw.githubusercontent.com/ourorg/ips/main/standards.ip.yaml"

Install Behavior

# Install from local IP file
ipman install frontend-kit.ip.yaml

# Install from URL
ipman install https://example.com/frontend-kit.ip.yaml

The installer: 1. Parses the IP file 2. Resolves all dependencies (recursive, with cycle detection) 3. Collects all skills (deduplicated) 4. Installs each skill via the appropriate agent CLI