Create a skill package

This guide walks you through creating a skill package from scratch. By the end you will have a working skill that reviews pull requests for common issues — ready to share with your team or publish to the registry.

Prerequisites

APKG CLI installed — see Installation if you haven’t set it up yet.
A default tool configured — see Quick Start to set up tool auto-configuration.

What is a skill package?

A skill gives an AI coding assistant a focused capability — code review, test generation, documentation writing, bug detection, and so on. Skills are the most common package type because they map naturally to discrete tasks you already ask your assistant to do.

A skill package contains:

An apkg.json manifest that identifies the package.
One or more .md definition files that tell the AI assistant what the skill does and how to behave.

When someone installs the package, APKG copies the definition files into the tool’s configuration directory (e.g. .claude/skills/ for Claude Code) so the assistant can use them automatically.

Initialize the package

Create a directory and scaffold the manifest:

mkdir pr-reviewer && cd pr-reviewer
apkg init

Answer the prompts:

Prompt	Value
Package name	`@<your-username>/pr-reviewer`
Version	`0.1.0`
Package type	`skill`
Description	`Reviews pull requests for bugs, style issues, and missing tests`
License	`MIT`
Keywords	`code-review, pull-request`

This creates an apkg.json:

{
  "name": "@alice/pr-reviewer",
  "version": "0.1.0",
  "type": "skill",
  "description": "Reviews pull requests for bugs, style issues, and missing tests",
  "license": "MIT",
  "keywords": ["code-review", "pull-request"]
}

Write the definition file

The definition file is the core of your skill. It is a Markdown file with YAML frontmatter that declares metadata, followed by a prompt body that instructs the AI assistant.

Create pr-reviewer.md in the package root:

---
name: pr-reviewer
description: Reviews pull request diffs for bugs, style issues, and missing tests
tools: Read, Grep, Glob, Bash
---

You are a pull request reviewer. When asked to review a PR or a set of
changes, follow these steps:

1. **Read the diff** — Use the available tools to read the changed files
   and understand what was modified.

2. **Check for bugs** — Look for logic errors, off-by-one mistakes,
   null/undefined risks, race conditions, and unhandled edge cases.

3. **Check for style issues** — Flag inconsistent naming, overly complex
   functions, duplicated code, and missing or misleading comments.

4. **Check for missing tests** — If the change adds or modifies behavior,
   verify that corresponding tests exist. If not, suggest what tests to add.

5. **Check for security issues** — Watch for SQL injection, XSS, command
   injection, hardcoded secrets, and other OWASP Top 10 vulnerabilities.

6. **Summarize your findings** — Present a clear, actionable summary:
   - List each issue with its file and line number.
   - Categorize issues as **bug**, **style**, **test**, or **security**.
   - Suggest a concrete fix for each issue.
   - If the code looks good, say so explicitly.

Keep feedback constructive and specific. Do not nitpick formatting that a
linter would catch.

Frontmatter fields

Field	Purpose
`name`	Identifier shown in the tool’s skill list.
`description`	Short summary the assistant uses to decide when this skill is relevant.
`tools`	Comma-separated list of tools the skill needs. The assistant uses this to know which capabilities to request.

Prompt body tips

Be specific. Vague prompts produce vague results. Tell the assistant exactly what to check and in what order.
Use structured output. Numbered steps, categories, and bullet points help the assistant produce consistent results.
Set boundaries. Tell the assistant what not to do (e.g. “do not nitpick formatting”) to avoid noise.
Reference tools explicitly. Mention tool names like “Use Read to open the file” so the assistant knows how to execute each step.

Add capabilities metadata

The optional skill.capabilities field in apkg.json declares what the skill can do. This helps users discover your package and helps the assistant select the right skill when multiple are installed.

Update your apkg.json:

{
  "name": "@alice/pr-reviewer",
  "version": "0.1.0",
  "type": "skill",
  "description": "Reviews pull requests for bugs, style issues, and missing tests",
  "license": "MIT",
  "keywords": ["code-review", "pull-request"],
  "skill": {
    "capabilities": ["code-review", "bug-detection", "security-review", "test-coverage"]
  }
}

Add a README

A README.md helps humans understand your package on the registry. It is not used by the AI assistant directly — the definition file handles that.

# @alice/pr-reviewer

Reviews pull request diffs for bugs, style issues, security vulnerabilities,
and missing tests.

## Usage

```bash
apkg add @alice/pr-reviewer

Then ask your AI assistant to review a PR:

Review the changes in this PR for bugs and missing tests.

What it checks

Logic errors and edge cases
Style and readability
Missing test coverage
OWASP Top 10 security issues

Tell APKG about the README by adding the `readme` field to `apkg.json`:

```json
{
  "readme": "README.md"
}

Use multiple definition files

A skill package can contain more than one .md definition file. This is useful when a skill covers several related capabilities that benefit from separate prompts.

For example, you could split the PR reviewer into focused files:

pr-reviewer/
  apkg.json
  README.md
  pr-reviewer.md          # Main review skill
  security-review.md      # Deep security-focused review
  test-coverage-check.md  # Focused test coverage analysis

Each file has its own frontmatter and prompt body. When the package is installed, all definition files are copied into the tool’s configuration directory.

Add dependencies

If your skill builds on other APKG packages, declare them as dependencies:

apkg add @acme/utils

This adds the dependency to apkg.json:

{
  "dependencies": {
    "@acme/utils": "^1.0.0"
  }
}

When someone installs your package, APKG resolves and installs the dependencies automatically.

Test your skill locally

Before publishing, test the skill in your own project by installing it from the local directory.

From a separate project where you want to try the skill:

apkg add ../pr-reviewer

This installs the package from the local path and runs tool setup. Open your AI coding tool and verify that the skill works as expected.

Iterate on the definition file until you are happy with the results — you can re-run apkg add ../pr-reviewer after each change.

Publish

Once the skill works well locally, publish it to the registry:

apkg login   # if not already logged in
apkg publish

See Publish your first package for the full publishing walkthrough.

Package structure recap

Here is the final layout of the skill package:

pr-reviewer/
  apkg.json        # Package manifest
  README.md        # Human-readable documentation
  pr-reviewer.md   # Skill definition file (prompt + frontmatter)

And the final apkg.json:

{
  "name": "@alice/pr-reviewer",
  "version": "0.1.0",
  "type": "skill",
  "description": "Reviews pull requests for bugs, style issues, and missing tests",
  "license": "MIT",
  "keywords": ["code-review", "pull-request"],
  "readme": "README.md",
  "skill": {
    "capabilities": ["code-review", "bug-detection", "security-review", "test-coverage"]
  }
}

Next steps

Skill package type — Reference for skill-specific fields and tool setup behavior.
apkg.json reference — Complete reference for every manifest field.
Publish your first package — Publishing workflow, authentication, and verification.
Create an agent package — If your skill needs autonomy and tool bindings, consider making it an agent instead.