Getting Started

Get up and running with AgentPKG in minutes. Install the CLI, create your account, and publish your first agent.

Installation

AgentPKG CLI requires Bun runtime. Install Bun first, then install the AgentPKG CLI globally.

Step 1: Install Bun

bash

curl -fsSL https://bun.sh/install | bash

Step 2: Install AgentPKG CLI

bash

bun install -g @agentpkg/cli

Step 3: Verify Installation

bash

agentpkg --version

Quick Start

Follow these steps to publish your first agent:

Create an Account

Account registration is only available through the web interface.

bash

agentpkg login

Create agent.agent.md

Create a file named agent.agent.md in your project with your agent instructions.

Publish Your Agent

bash

agentpkg publish agent

Install Other Agents

bash

agentpkg add agent @acme/my-agent

Authentication

Manage your AgentPKG account and authenticate the CLI.

Important

Account registration is only available through the web interface at agentpkg.com/register. After creating an account, you can login via the CLI.

Login

bash

agentpkg login

Check Login Status

bash

agentpkg whoami

Logout

bash

agentpkg logout

Working with Agents

Publish your AI agents to the registry and install agents from others.

Publishing Agents

Publish your agents to the AgentPKG registry. All agents are private by default (only organization members can view/install).

Interactive mode prompts you for all required information:

bash

agentpkg publish agent

You'll be prompted to select your organization, enter name, version, description, and choose access level (private/public).

Available Options:

--org Organization name (required in CI/CD)
--name Agent name (required in CI/CD)
--version Version in semver format (required in CI/CD)
--description Agent description (optional)
--access Access level: private (default) or public
--yes Skip all prompts

Installing Agents

Install agents from the registry to your project. Agents are installed to .github/agents/ directory.

Install latest version:

bash

agentpkg add agent @acme/my-agent

Install specific version:

bash

agentpkg add agent @acme/my-agent@1.2.0

Deprecation Notice

The agentpkg install command is deprecated. Use agentpkg add agent instead. The install command will be removed in v1.0.0.

Working with Skills

Skills are reusable capabilities that can be added to AI agents.

Publishing Skills

Skills follow the same publishing model as agents. All skills are private by default.

bash

agentpkg publish skill

The command reads SKILL.md from your current directory or specified skill directory.

Installing Skills

Install skills to .github/skills/<name>/SKILL.md

bash

agentpkg add skill @acme/my-skill

bash

agentpkg add skill @acme/my-skill@1.0.0

Organizations

Create and manage organizations to collaborate with your team.

List Your Organizations

bash

agentpkg orgs list

Create New Organization

bash

agentpkg orgs create

You'll be prompted to enter an organization name. Names must be lowercase, alphanumeric, and can include hyphens.

Inviting Team Members

Team invitations are managed through the web UI. Navigate to your organization settings to invite members via email.

Manage Organizations →

Access Control

Control who can view and install your agents and skills with private and public access levels.

Private (Default)

Only organization members can view and install

Internal company agents
Work-in-progress
Proprietary automation

Public

Anyone can view and install

Open-source agents
Community contributions
Educational examples

Update Access Level

Only organization owners can change access levels.

bash

agentpkg update-access agent

CI/CD Integration

Automate agent and skill publishing with GitHub Actions or other CI/CD platforms.

GitHub Actions Example

Publish agents automatically when you create a new tag:

yaml

name: Publish Agent

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      - run: bun install -g @agentpkg/cli
      - run: |
          agentpkg publish agent \
            --org myorg \
            --name myagent \
            --version ${GITHUB_REF#refs/tags/v} \
            --access private \
            --yes
        env:
          AGENTPKG_API_URL: ${{ secrets.AGENTPKG_API_URL || 'https://api.agentpkg.com' }}
          AGENTPKG_TOKEN: ${{ secrets.AGENTPKG_TOKEN }}

GitHub Secrets

Store your authentication token in GitHub Secrets as AGENTPKG_TOKEN. You can get your token from ~/.agentpkg/config.json after logging in.

File Formats

Learn about the structure of agent and skill files.

Agent File (agent.agent.md)

Agent files use Markdown with YAML frontmatter:

markdown

---
name: my-agent
version: 1.0.0
description: A helpful AI agent
---

# Agent Instructions

You are a helpful AI agent that...

## Guidelines

- Be helpful and polite
- Follow user instructions carefully

## Example Usage

...

Skill File (SKILL.md)

Skills are stored in a directory structure: <skill-name>/SKILL.md

markdown

# Skill: My Awesome Skill

## Description
This skill provides...

## Usage
To use this skill...

## Examples
...

Directory Structure

bash

.
├── agent.agent.md
└── .github/
    ├── agents/
    │   ├── agent1.agent.md
    │   └── agent2.agent.md
    └── skills/
        ├── skill1/
        │   └── SKILL.md
        └── skill2/
            └── SKILL.md

Configuration

Configure the CLI and environment variables.

Configuration File

Configuration is stored in ~/.agentpkg/config.json:

json

{
  "apiUrl": "https://api.agentpkg.com",
  "token": "your-auth-token"
}

Environment Variables

AGENTPKG_API_URL

Override the API base URL (default: https://api.agentpkg.com)

bash

export AGENTPKG_API_URL=http://localhost:4000

Troubleshooting

Common issues and their solutions.

Not logged in

Error: Not logged in. Run 'agentpkg login' first.

Solution: Run agentpkg login to authenticate.

Version already exists

Error: Agent version already exists

Solution: Use a different version number. AgentPKG uses semantic versioning.

Permission denied

Error: You are not a member of this organization

Solution: Contact the organization owner to be added as a member.

Cannot connect to API

Error: Cannot connect to AgentPKG API

Solution: Check your internet connection and verify the API URL is correct.

Need more help?

Open an Issue →Join Discussions →