Skill Package Format

This page summarizes the skill package format. The authoritative source is src/context/skills/FORMAT.md in the processkit repo.

Directory layout

src/context/skills/<category>/<skill-name>/
  SKILL.md              ← required — three-level agent instructions
  INDEX.md              ← optional — human-readable overview
  examples/             ← recommended — example outputs
  templates/            ← recommended — YAML frontmatter entity scaffolds
  references/           ← optional — deep-dive reference material
  mcp/                  ← optional — Python MCP server
    server.py
    mcp-config.json
    README.md

Required frontmatter fields

Field	Purpose
`apiVersion`	Always `processkit.projectious.work/v1` at v0.x.
`kind`	Always `Skill`.
`metadata.id`	`SKILL-<skill-name>`
`metadata.name`	Kebab-case; matches directory name
`metadata.version`	Semver, independent of processkit release
`metadata.created`	ISO 8601 UTC
`spec.description`	One-sentence summary (shown in listings)
`spec.category`	One of the registered categories
`spec.layer`	Integer 0–4, or `null` for non-process skills

Optional fields

Field	Purpose
`spec.uses`	Skills this depends on (strictly lower layer for process skills)
`spec.provides`	What the agent gains: primitive kinds, MCP tools, templates
`spec.when_to_use`	Trigger description for routing
`spec.replaces`	ID of a skill this one overrides (for community forks)

The `provides` block

A promise to consumers — what an agent gains by activating this skill:

provides:
  primitives: [WorkItem]
  mcp_tools: [create_workitem, transition_workitem, query_workitems]
  templates: [workitem, workitem-bug, workitem-story]
  processes: [backlog-grooming]

Installers and release checks can cross-check these promises against the actual files shipped in the skill.

MCP server conventions (v0.3.0+)

Skills ship Python MCP servers as standalone scripts with PEP 723 inline dependencies:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = ["mcp[cli]>=1.0,<2.0"]
# ///
from mcp.server.fastmcp import FastMCP
server = FastMCP("<skill-name>")
...
if __name__ == "__main__":
    server.run(transport="stdio")

Consumers need only Python 3.10 or newer and uv.