# Paks

## Introduction

### What are Paks?

Paks are the first package manager for [Agent Skills](https://agentskills.io/), they are reusable instruction sets that help agents follow your way of working across agents like Stakpak, Claude Code, Cursor, OpenCode, GitHub Copilot, Goose, and more.

### Why Agent Skills Need Paks?

AI coding agents are powerful, but they need context. Skills provide that context, coding standards, deployment procedures, API patterns, and domain knowledge. while 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 Agents
* **Build on others' work:** Discover and use community created skills
* **Version and iterate:** Semantic versioning for skill updates

## Installation

### 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 from git
paks install https://github.com/user/skill-repo.git

# 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
```

## Configuration

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

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

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

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

### Choosing Your Agent

```
paks agent list              # List configured agents
paks agent add <name> -d <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         | Skills Directory                  |
| ------------- | --------------------------------- |
| `stakpak`     | `~/.stakpak/skills`               |
| `claude-code` | `~/.claude/skills`                |
| `cursor`      | `~/.cursor/skills`                |
| `vscode`      | `~/.vscode/skills`                |
| `copilot`     | `~/.config/github-copilot/skills` |
| `goose`       | `~/.config/goose/skills`          |
| `opencode`    | `~/.config/opencode/skills`       |

#### **Examples:**

```
# Add a custom agent
paks agent add my-agent --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
```

## 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>

## Contribute

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

1. Fork the [repository](https://github.com/stakpak/paks)
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://stakpak.gitbook.io/docs/how-it-works/paks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.