# Skills

> The skill package format, the category hierarchy, and the shipped catalog.

---

LLMS index: [llms.txt](/processkit/v1.x/llms.txt)

---

A **skill** in processkit is a directory containing agent instructions,
examples, assets, and optionally a Python MCP server. Skills are how processkit
gives agents domain-specific intelligence — not just instructions, but the
conventions, gotchas, and decision rules of a domain expert.

The v1 installer copies skills from the producer payload into the consuming
project's `context/` tree. They remain visible and locally reviewable; Rust
does not compile them into the CLI, and Python remains the implementation
language for skill MCP servers.

## Skill package layout

```
src/context/skills/<category>/<skill-name>/
  SKILL.md              ← agent instructions (Intro / Overview / Gotchas / Full reference)
  examples/             ← example outputs
  assets/               ← templates, reference data, reusable artifacts
  references/           ← optional deep-dive material (keeps SKILL.md under 5 000 words)
  scripts/              ← optional helper scripts
  mcp/                  ← optional Python MCP server
```

## The four-section structure

Every `SKILL.md` is organized so agents can stop reading as soon as they
have enough context:

| Section            | Content                                                                |
|--------------------|------------------------------------------------------------------------|
| **Intro**          | 1–3 sentences — enough to decide "is this skill relevant?"             |
| **Overview**       | Key workflows and common operations — enough to act on typical cases   |
| **Gotchas**        | 7 agent-specific failure modes — where agents most often go wrong      |
| **Full reference** | Edge cases, field-by-field specs, troubleshooting                      |

The Gotchas section is the highest-signal content: 7 provider-neutral failure
modes, each with a bold title, the specific failure pattern, and the specific
countermeasure.

## Frontmatter

Each `SKILL.md` opens with YAML frontmatter:

```yaml
---
name: workitem-management
description: |
  Creates, transitions, and queries WorkItems — the task-tracking primitive
  in processkit. Use when managing backlog items, updating work item state,
  or querying items by status, owner, or priority.
metadata:
  processkit:
    apiVersion: processkit.projectious.work/v1
    id: SKILL-workitem-management
    version: "1.0.0"
    created: 2026-04-06T00:00:00Z
    category: process
    layer: 2
    uses:
      - skill: event-log
        purpose: "records state transitions as auditable log entries"
    provides:
      primitives: [WorkItem]
      mcp_tools: [create_workitem, transition_workitem, query_workitems]
      assets: [workitem, workitem-bug, workitem-story]
---
```

See [Skills → Format](./format) for the complete specification.

## Catalog

The exact catalog is release-generated and validated by the MCP manifest.
Avoid using a static skill count as a maturity claim.

| Category | Count | Examples |
|---|---|---|
| Processkit operations | 40+ | workitem-management, decision-record, processkit-gateway, task-router, skill-gate |
| Engineering and devops | 45+ | python-best-practices, fastapi-patterns, terraform-basics, incident-response |
| Data, AI, and research | 20+ | data-science, rag-engineering, llm-evaluation, research-with-confidence |
| Product, design, and documents | 25+ | prd-writing, user-research, frontend-design, docx-authoring |
| Role and coordination workflows | 10+ | session-handover, standup-context, retrospective, team-manager |

All skills are **Pattern 5 (domain-specific intelligence)**: they encode
what an expert in the domain carries in their head — conventions, gotchas,
and decision rules — so the agent reasons like a specialist, not a generalist.

## Browsing the skill catalog

Three ways to find skills:

**On GitHub** — Browse the source tree directly:
[`src/context/skills/`](https://github.com/projectious-work/processkit/tree/main/src/context/skills/)
is organized into 7 category subdirectories (`processkit/`,
`engineering/`, `devops/`, `data-ai/`, `product/`, `documents/`,
`design/`). Each skill directory contains a `SKILL.md` with the full
description, gotchas, and reference.

**From a release tarball** — Every GitHub release includes a
`processkit-vX.Y.Z.tar.gz` with all `src/` content. Download and unpack
to inspect or diff skills without cloning the full repo. Release assets
live at:
[github.com/projectious-work/processkit/releases](https://github.com/projectious-work/processkit/releases)

**In an installed project** — Skills are installed under
`context/skills/<category>/<skill-name>/SKILL.md`. The `task-router` MCP
server's `route_task(task_description)` call returns the matching skill,
any legacy process override metadata, and the recommended MCP tool in a
single call. `skill-finder` (`find_skill`, `list_skills`) is called
internally by `task-router` and remains available directly. The
index-management MCP server's `search_entities` tool can query skill
metadata from the SQLite index.

## Where to go next

- [Format](./format) — the full skill package format specification
- [Hierarchy](./hierarchy) — the layered skill graph (`uses:` relationships)
- [Catalog → Process](./catalog/process) — start browsing skills by category

---

Section pages:

- [Skill Package Format](/processkit/v1.x/docs/skills/format/)
- [Skill Hierarchy](/processkit/v1.x/docs/skills/hierarchy/)
- [Catalog](/processkit/v1.x/docs/skills/catalog/): Every shipped skill, grouped by category.