Packages

Packages are the essential building blocks that enable modular reuse of AI coding specs and tools.
By organizing your rules, slash commands, subagents (and more) into sets of packages, reuse and sync across projects and AI coding platforms become super simple and straightforward.

Essentials

Structure of a package

A package can contain the following files:

• The openpackage.yml file
• Package files (README.md, LICENSE.md, etc.)
• AGENTS.md (universal platform root file)
• MCP config file
• Rules
• Slash commands
• Subagents
• Skills
• Workspace files (installed to workspace root)

Packages are composed using the following directory structure:

<package>
│   
│   # Package files
├── openpackage.yml       # The OpenPackage manifest, required
├── README.md             # LICENSE.md, CONTRIBUTING.md, etc.
│   
│   # Content files
├── rules/                # Rule files
├── commands/             # Command files (slash commands)
├── agents/               # Agent files (subagents)
├── skills/               # Skill files (skills)
├── root/                 # Any other root dirs or files (Ex: specs/, docs/, tests/, etc.)
├── AGENTS.md             # Platform root file
├── mcp.jsonc             # MCP config file
│   
│   # Custom files
└── <other>               # Customizable via `platforms.jsonc` overrides/extensions

To create a package:

1. Run opkg new, select package location, enter package details
   (or create the openpackage.yml file manually)
2. Add workspace files to package via opkg add <package-name-or-path> <path-to-file-or-dir>
   (or populate the package dir manually)

To pack versioned packages (to local registry at ~/.openpackage/registry/):

1. Update package openpackage.yml version manually or via opkg set --version <version>
2. Run opkg pack (in the package dir) or opkg pack <package-name-or-path>

The openpackage.yml file

A openpackage.yml file contains metadata and configurations for a package.

name: <package-name>
version: <semver> # 0.1.0, 1.2.0, etc. (optional)
description: <package-description>
keywords: [keyword1, keyword2]
author: <author>
license: <license>
packages:
- name: <some-package>
  version: ^0.1.2 # semver and ranges (optional)
dev-packages:
- name: <some-dev-package>
  version: ^0.1.2 # semver and ranges (optional)

You are free to edit the contents of a openpackage.yml file as required. See the install command for more details on how fields are updated by the CLI.

Packages in workspaces

When a package is installed to a codebase, the CLI tool automatically copies the files from the package to your codebase into their respective locations, converted, and synced across existing supported AI coding platforms. Refer to the install and uninstall commands for more details.

essentials/
├── openpackage.yml
├── rules/
│   └── essentials/
│       └── clean-code.md
├── commands/
│   └── essentials/
│       └── clean-files.md
├── root/
│   └── specs/
│       └── guidelines/
│           ├── dry.md
│           └── modular.md
└── mcp.jsonc

Advanced

Platform specific frontmatter overrides

You can create per platform key value overrides directly in the package file frontmatters.

---
description: Generates NextJS pages and components
openpackage:
  opencode:
    mode: subagent
    tools:
      write: true
      edit: true
      bash: true
  claude:
    name: ui-builder
    tools: Read, Edit, Bash, Grep, Glob
---

You are a NextJS UI designer that specializes in creating pages and components.

Use the following guidelines to complete the given task(s):
- Pages: @ai/nextjs/pages/
- Shadcn: @ai/nextjs/shadcn.md
- Tailwind CSS: @ai/nextjs/tailwindcss.md

Platform specific files

In the package dir, create platform marked files using the format <filename>.<platform>.<ext>, which will tell the CLI to install and keep this file only for this platform and not sync it across all detected platforms. You can manually add these override files or use the add command with the --platform-specific option.

Set up a nestjs codebase using these steps:

1. Read relevant guideline files
2. Initialize cwd as nextjs codebase
3. Reinstall OpenPackage package files with `npx opkg i @hyericlee/nextjs` if needed

The openpackage.index.yml file

A per workspace index file will be generated and updated by OpenPackage CLI for mapping file locations for installs, updates, and uninstalls. Do not manually update the index file.

# This file is managed by OpenPackage. Do not edit manually.

packages:
  specs:
    files:
      commands/read-specs.md:
        - .claude/commands/read-specs.md
        - .cursor/commands/read-specs.md
      commands/update-specs.md:
        - .claude/commands/update-specs.md
        - .cursor/commands/update-specs.md
    path: ./.openpackage/packages/specs/
    version: 0.0.0
  nextjs:
    files:
      root/specs/nestjs/architecture.md:
        - specs/nestjs/architecture.md
      root/specs/nestjs/controllers.md:
        - specs/nestjs/controllers.md
      root/specs/nestjs/repositories.md:
        - specs/nestjs/repositories.md
      root/specs/nestjs/services.md:
        - specs/nestjs/services.md
    path: ~/.openpackage/registry/nextjs/1.0.0/
    version: 1.0.0

Bundling

You can list other packages to install together alongside the current package by listing "dependency" packages under the packages or dev-packages fields.

name: @hyericlee/nestjs
version: 0.1.0
packages:
- name: scalable-typescript
  version: ^1.0.0
dev-packages:
- name: package-essentials
  version: ^1.0.0

Installation of the package will subsequently install the specified packages in the package's package.yml file recursively for all nested packages. (dev-packages will only be installed for the top level project scoped package.yml files.)