How to Publish Paks (Agent Skills)

Overview

Paks are reusable instruction sets that enhance AI coding agents. This guide covers the complete workflow from creation to publishing on the Paks registry, with emphasis on writing high-quality content that agents can effectively use.

Prerequisites

• paks CLI installed (brew tap stakpak/stakpak && brew install paks)
• Stakpak API key for publishing
• Git repository for your skill

Workflow / Instructions

Step 1: Create Skill Structure

# Create a new skill with the paks CLI
paks create my-skill

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

This generates:

my-skill/
├── SKILL.md          # Required: Manifest + instructions
├── scripts/          # Optional: Helper scripts
├── references/       # Optional: Reference documentation
└── assets/           # Optional: Static files

Step 2: Write SKILL.md with Frontmatter

The SKILL.md file uses YAML frontmatter for metadata:

---
name: my-skill                    # Required: 1-64 chars, lowercase + hyphens
description: |                    # Required: 1-1024 chars
  What this skill does and when to use it.
license: MIT                      # Optional: License type
tags:                             # Recommended: For discoverability
  - keyword1
  - keyword2
metadata:
  author: Your Name <email@example.com>
  version: "1.0.0"                # Semantic version (must match git tag)
---

# Skill Title

## Instructions

Your skill instructions go here...

Frontmatter Fields:

Field	Required	Description
name	Yes	Skill identifier (lowercase, hyphens only)
description	Yes	What the skill does, when to use it
license	No	License type (MIT, Apache-2.0, etc.)
tags	No	Keywords for search/discovery
metadata.version	Yes	Semantic version matching git tag
metadata.author	No	Author name and email

Writing a Good Description:

The description helps agents know what this skill is about, its scope, and when to use it. Keep it short and outcome-oriented.

• Bad: "This skill is about Kubernetes."
• Good: "This skill helps you deploy and scale applications on Kubernetes with production-grade configuration."

Writing Good Tags:

Create at least three tags to help agents find this skill via keyword search. Use specific, relevant terms.

Step 3: Write Skill Content

After the frontmatter, structure your content with clear goals and actionable workflows:

# Skill Title

## Goals
Explain the outcome the user will achieve by following this skill.
Write as clear, outcome-oriented sentences.

## Prerequisites
Required tools, files, or context.

## Workflow / Instructions

### Step 1: First Action
**Action:** Imperative instruction (e.g., "Install the CLI tool")
**Reasoning:** Why this step is required (optional but recommended)
**Examples:** Code samples, commands, or configuration snippets

### Step 2: Next Action
Continue with clear, atomic steps.

## Troubleshooting
Common issues and solutions.

## References
- [Official Documentation](https://example.com)
- Related skills

Step 4: Apply Content Quality Guidelines

Structure & Style:

• Use clear structure and concise text
• Use short, direct sentences
• Keep steps atomic (one action per step)
• Include necessary context but avoid unnecessary details
• Keep under 5,000 words (~800 lines)
• Reference external files for detailed content

Writing for Agents:

• Use imperative language ("Analyze code for...") not second person
• Avoid hard-coded values - maximize reusability
• Only include new information and insights that complement agent knowledge
• Don't repeat knowledge the agent already has - this reduces quality
• Include code examples and configuration snippets

What to Include:

• Good patterns discovered through experience
• Information learned from web research
• References to external files for detailed content

Optional Enhancements:

• Add prerequisites with conditions (e.g., "only run if there is Terraform code")
• Reference established standards and guidelines:
  • Principle of least privilege
  • OWASP Guidelines (specify which ones)
  • AWS Well-Architected Framework
  • Internal company guidelines from other skills (with reference)

Step 4: Validate the Skill

# Validate skill structure and frontmatter
paks validate my-skill

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

Step 5: Authenticate with Registry

# Login with API token
paks login --token <your-api-token>

# Verify login
paks login

Step 6: Publish to Registry

Important: The git tag version must match metadata.version in SKILL.md.

# Dry run first (see what would be published)
paks publish my-skill --dry-run

# Publish with automatic version bump
paks publish my-skill --bump patch   # 1.0.0 → 1.0.1
paks publish my-skill --bump minor   # 1.0.0 → 1.1.0
paks publish my-skill --bump major   # 1.0.0 → 2.0.0

# Publish using existing git tag (non-interactive)
paks publish my-skill --tag v1.0.0 --yes

Version Management

The paks registry uses git tags for versioning. The workflow:

1. Update metadata.version in SKILL.md
2. Commit changes
3. Create matching git tag: git tag v1.0.0
4. Push tag: git push origin v1.0.0
5. Publish: paks publish my-skill --tag v1.0.0 --yes

Common Version Errors:

Error	Cause	Solution
"Tag does not match version"	Tag and SKILL.md version mismatch	Update SKILL.md version to match tag
"Tag already exists"	Trying to reuse existing tag	Create new tag with bumped version
"No SKILL.md found at path"	Tag points to commit without SKILL.md	Create new tag after adding SKILL.md

Multi-Skill Repository

For repositories with multiple skills:

my-repo/
├── skill-one/
│   └── SKILL.md
├── skill-two/
│   └── SKILL.md
└── skill-three/
    └── SKILL.md

Publish each skill separately:

paks publish skill-one --tag v1.0.0 --yes
paks publish skill-two --tag v1.0.0 --yes

CLI Reference

Command	Description
paks create <name>	Create new skill from template
paks validate <path>	Validate skill structure
paks publish <path>	Publish to registry
paks login	Authenticate with registry
paks search <query>	Search published skills
paks info <skill>	Show skill details

Troubleshooting

Issue	Solution
"not a terminal" error	Use --yes flag for non-interactive mode
Version mismatch	Ensure SKILL.md version matches git tag
Validation fails	Check frontmatter YAML syntax
Login fails	Verify API token is correct
Publish fails	Ensure you're logged in and tag exists

References

• Paks CLI Documentation
• Agent Skills Specification
• Paks Registry