📦 Paks

The package manager for AI Agent Skills

Create, install, publish, and share skills across AI coding agents.

Installation • Quick Start • CLI Reference • Registry • Contributing

⭐ Help us reach more developers and grow the Paks community. Star this repo!

What is Paks?

Paks is a CLI-first package manager for Agent Skills — reusable instruction sets that enhance AI coding agents like Stakpak, Claude Code, Cursor, OpenCode, GitHub Copilot, Goose, and more.

The CLI is your primary interface for:

🛠️ Creating new skills with proper structure
📥 Installing skills from the registry, git repos, or local paths
🚀 Publishing skills to share with the community
🔍 Managing skills across multiple AI agents

The Web Registry provides a browsable interface to discover and explore published skills.

Why Paks?

AI coding agents are powerful, but they need context. Skills provide that context — coding standards, deployment procedures, API patterns, and domain knowledge. Paks makes it easy to:

Share expertise — Package your team's best practices as installable skills
Stay consistent — Install the same skills across all your AI agents
Build on others' work — Discover and use community-created skills
Version and iterate — Semantic versioning for skill updates

Installation

Homebrew (macOS & Linux)

brew tap stakpak/stakpak
brew install paks

Download Binary

Pre-built binaries are available for all major platforms on the Releases page:

Platform	Architecture	Download
macOS	Apple Silicon (M1/M2/M3)	`paks-darwin-aarch64.tar.gz`
macOS	Intel	`paks-darwin-x86_64.tar.gz`
Linux	x86_64	`paks-linux-x86_64.tar.gz`
Linux	ARM64	`paks-linux-aarch64.tar.gz`
Windows	x86_64	`paks-windows-x86_64.zip`

# Example: Download and install on Linux x86_64
curl -L https://github.com/stakpak/paks/releases/latest/download/paks-linux-x86_64.tar.gz | tar xz
sudo mv paks /usr/local/bin/

From Source (Rust)

# Clone the repository
git clone https://github.com/stakpak/paks.git
cd paks

# Build the CLI
cargo build --release -p paks-cli

# The binary will be at ./target/release/paks
# Move it to your PATH
cp ./target/release/paks ~/.local/bin/

Verify Installation

paks --version
paks --help

Quick Start

1. Create Your First Skill

# Create a new skill
paks create my-awesome-skill

# Or with optional directories
paks create my-awesome-skill --with-scripts --with-references

This generates:

my-awesome-skill/
├── SKILL.md          # Skill manifest and instructions
├── scripts/          # (optional) Helper scripts
├── references/       # (optional) Reference documentation
└── assets/           # (optional) Static assets

2. Edit Your Skill

The SKILL.md file is the heart of your skill. It uses YAML frontmatter for metadata and Markdown for instructions:

---
name: my-awesome-skill
description: A skill that helps with awesome things
version: 0.1.0
license: MIT
keywords:
  - awesome
  - productivity
---

# My Awesome Skill

## When to use this skill

Describe when this skill should be activated.

## Instructions

Add your instructions here. The AI agent will follow these
when the skill is active.

3. Validate Your Skill

paks validate my-awesome-skill

# Strict mode (warnings become errors)
paks validate my-awesome-skill --strict

4. Install Skills

# Install from registry
paks install kubernetes-deploy

# Install for a specific agent
paks install kubernetes-deploy --agent claude-code

# Install to project directory (instead of global)
paks install kubernetes-deploy --scope project

# Install from GitHub (just paste the URL from your browser)
paks install https://github.com/user/repo/tree/main/path/to/skill

# Install specific version
paks install kubernetes-deploy --version 1.2.0

# Force reinstall
paks install kubernetes-deploy --force

5. Publish Your Skill

# Dry run first
paks publish my-awesome-skill --dry-run

# Publish with version bump
paks publish my-awesome-skill --bump patch

# Publish (requires login)
paks login
paks publish my-awesome-skill

CLI Reference

Core Commands

Command	Description
`paks create <name>`	Create a new skill from template
`paks install <source>`	Install a skill
`paks publish [path]`	Publish a skill to the registry
`paks validate [path]`	Validate skill structure
`paks list`	List installed skills
`paks remove <name>`	Remove an installed skill
`paks search <query>`	Search the registry
`paks info <skill>`	Show skill details

Create Command

paks create <name> [OPTIONS]

Options:
  -o, --output <DIR>       Output directory (defaults to ./<name>)
  -t, --template <TYPE>    Template type: basic, devops, coding
      --with-scripts       Include scripts/ directory
      --with-references    Include references/ directory
      --with-assets        Include assets/ directory

Examples:

# Basic skill
paks create my-skill

# DevOps skill with all directories
paks create deploy-helper --template devops --with-scripts --with-references

# Specify output location
paks create my-skill --output ~/skills/my-skill

Install Command

paks install <source> [OPTIONS]

Options:
  -a, --agent <AGENT>      Target agent (stakpak, claude-code, cursor, vscode, copilot, goose, opencode)
  -s, --scope <SCOPE>      Installation scope: global or project
  -d, --dir <PATH>         Custom install directory (overrides agent and scope)
  -v, --version <VERSION>  Specific version to install
  -f, --force              Force reinstall if exists

Scope:

global (default): Installs to user directory (e.g., ~/.claude/skills)
project: Installs to project directory (e.g., ./.claude/skills)

Examples:

# Install from registry (global scope by default)
paks install terraform-best-practices

# Install for Claude Code
paks install terraform-best-practices --agent claude-code

# Install to project directory (scope: project)
paks install terraform-best-practices --scope project

# Install from GitHub/GitLab (just paste the browser URL)
paks install https://github.com/org/repo/tree/main/skills/my-skill

# Install to custom directory
paks install my-skill --dir ~/custom/skills

Publish Command

paks publish [path] [OPTIONS]

Options:
      --bump <LEVEL>       Version bump: patch, minor, major
      --skip-validation    Skip validation before publishing
      --dry-run            Show what would be published

Examples:

# Validate and show what would be published
paks publish --dry-run

# Publish with patch version bump (0.1.0 → 0.1.1)
paks publish --bump patch

# Publish with minor version bump (0.1.0 → 0.2.0)
paks publish --bump minor

# Publish specific directory
paks publish ./my-skill --bump patch

List Command

paks list [OPTIONS]

Options:
  -a, --agent <AGENT>      List skills for specific agent
  -s, --scope <SCOPE>      Scope to list from: global or project
      --all                List skills from all agents
  -f, --format <FORMAT>    Output format: table, json, yaml

Examples:

# List skills for default agent (global scope by default)
paks list

# List project-scoped skills
paks list --scope project

# List all skills across all agents
paks list --all

# List as JSON
paks list --format json

# List for specific agent
paks list --agent cursor

Agent Management

paks agent list              # List configured agents
paks agent add <name> -d <dir> [-p <project-dir>]  # Add custom agent
paks agent remove <name>     # Remove custom agent
paks agent default <name>    # Set default agent
paks agent show [name]       # Show agent details

Built-in Agents:

Agent	Global Directory	Project Directory
`stakpak`	`~/.stakpak/skills`	`.stakpak/skills`
`claude-code`	`~/.claude/skills`	`.claude/skills`
`cursor`	`~/.cursor/skills`	`.cursor/skills`
`vscode`	`~/.vscode/skills`	`.vscode/skills`
`copilot`	`~/.copilot/skills`	`.copilot/skills`
`goose`	`~/.config/goose/skills`	`.goose/skills`
`opencode`	`~/.config/opencode/skill`	`.opencode/skill`

Examples:

# Add a custom agent with both global and project directories
paks agent add my-agent --dir ~/my-agent/skills --project-dir .my-agent/skills

# Set as default
paks agent default my-agent

# View all agents
paks agent show

Authentication

paks login [--token <TOKEN>]  # Login to registry
paks logout                    # Logout from registry

Skill Structure

SKILL.md Frontmatter

The SKILL.md file uses YAML frontmatter following the Agent Skills specification:

---
# Required fields
name: my-skill                    # 1-64 chars, lowercase + hyphens
description: What this skill does # 1-1024 chars

# Optional (Agent Skills spec)
license: MIT
compatibility: Requires Node.js 18+
metadata:
  author: Your Name
  website: https://example.com
allowed-tools: |                  # Experimental
  - read_file
  - write_file

# Paks extensions (for package management)
version: 1.0.0                    # Semantic version
authors:
  - Your Name <you@example.com>
repository: https://github.com/you/skill
homepage: https://your-skill.dev
keywords:
  - devops
  - kubernetes
categories:
  - deployment
dependencies:
  - name: base-skill
    version: ">=1.0.0"
---

Directory Structure

my-skill/
├── SKILL.md              # Required: Manifest + instructions
├── scripts/              # Optional: Helper scripts
│   ├── deploy.sh
│   └── validate.py
├── references/           # Optional: Reference docs
│   ├── api-docs.md
│   └── examples/
└── assets/               # Optional: Static files
    └── templates/

Registry

Web Interface

The Paks Registry web interface provides:

🔍 Browse — Discover skills by category, keyword, or popularity
📖 Read — View skill documentation and instructions
📊 Stats — See download counts and version history
👤 Profiles — View publisher profiles and their skills

Visit the registry at: http://localhost:3001 (development)

API

The registry exposes a REST API for programmatic access:

# Search skills
GET /api/skills?q=kubernetes

# Get skill details
GET /api/skills/:name

# Get specific version
GET /api/skills/:name/:version

Configuration

Global Configuration

Paks stores global configuration at ~/.paks/config.toml:

# Default agent when --agent is not specified
default_agent = "stakpak"

# Default installation scope: "global" or "project"
default_scope = "global"

# Custom agents
[agents.my-custom-agent]
name = "My Custom Agent"
skills_dir = "/path/to/skills"
project_skills_dir = ".my-agent/skills"  # Relative to project root
description = "Custom agent for my workflow"

# Registry configuration
[registries.default]
url = "https://registry.paks.dev"

Project Configuration

You can also create a project-level configuration at .paks/config.toml in your project root:

# Project-level config overrides global config
default_scope = "project"  # Make project scope the default for this project
default_agent = "claude-code"

Configuration priority (highest to lowest):

CLI flags (--scope, --agent, --dir)
Project config (.paks/config.toml)
Global config (~/.paks/config.toml)
Built-in defaults

This allows teams to standardize skill installations across all developers by committing .paks/config.toml to version control.

Project Structure

paks/
├── apps/
│   ├── cli/              # Rust CLI application
│   │   ├── src/
│   │   │   ├── commands/ # CLI command implementations
│   │   │   │   ├── create.rs
│   │   │   │   ├── install.rs
│   │   │   │   ├── publish.rs
│   │   │   │   ├── validate.rs
│   │   │   │   └── ...
│   │   │   └── main.rs
│   │   └── Cargo.toml
│   ├── web/              # Registry web interface
│   │   └── src/
│   │       ├── routes/   # TanStack Router pages
│   │       └── components/
│   └── docs/             # Documentation site
├── packages/
│   ├── core/             # Shared Rust library
│   └── config/           # Shared TypeScript config
├── Cargo.toml            # Rust workspace
├── package.json          # Node.js workspace
└── turbo.json            # Turborepo config

Development

Prerequisites

Rust 2024 edition (nightly)
Node.js 18+
pnpm 8+

Setup

# Install dependencies
pnpm install

# Build everything
pnpm run build

# Development mode
pnpm run dev

Available Scripts

Script	Description
`pnpm run dev`	Start all apps in development mode
`pnpm run build`	Build all applications
`pnpm run dev:web`	Start only the web application
`pnpm run check-types`	TypeScript type checking
`pnpm run check`	Run Oxlint and Oxfmt

Rust Development

# Build CLI
cargo build -p paks-cli

# Run CLI
cargo run -p paks-cli -- --help

# Run tests
cargo test

# Format code
cargo fmt

# Lint
cargo clippy

Need Support Creating Your First Pak?

If this is your first time writing a Pak, you don’t have to figure it out alone. Our community is actively building and sharing skills, and we’re happy to help you:

Write your first SKILL.md
Review structure and metadata
Decide what belongs in a Pak (and what doesn’t)
Validate and publish with confidence

Join the Stakpak Discord to ask questions, get feedback, and see how others are using Paks

Join the community: https://discord.gg/QTZjETP7GB

Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Guidelines

Follow the existing code style
Add tests for new functionality
Update documentation as needed
Keep commits atomic and well-described

License

Apache 2.0 License — see LICENSE for details.

Built with ❤️ by Stakpak

Website • Documentation • Discord

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
.github/workflows		.github/workflows
apps		apps
packages		packages
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
amplify.yml		amplify.yml
bts.jsonc		bts.jsonc
cliff.toml		cliff.toml
clippy.toml		clippy.toml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
release.sh		release.sh
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

📦 Paks

What is Paks?

Why Paks?

Installation

Homebrew (macOS & Linux)

Download Binary

From Source (Rust)

Verify Installation

Quick Start

1. Create Your First Skill

2. Edit Your Skill

3. Validate Your Skill

4. Install Skills

5. Publish Your Skill

CLI Reference

Core Commands

Create Command

Install Command

Publish Command

List Command

Agent Management

Authentication

Skill Structure

SKILL.md Frontmatter

Directory Structure

Registry

Web Interface

API

Configuration

Global Configuration

Project Configuration

Project Structure

Development

Prerequisites

Setup

Available Scripts

Rust Development

Need Support Creating Your First Pak?

Contributing

Guidelines

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 14

Contributors

Uh oh!

Languages