Writing skills

A skill is a named procedure the assistant can invoke instead of re deriving the steps every time. Memories tell the assistant what is true. Rules tell it what not to do. Skills tell it how to do a specific job, step by step.

This page covers when to write a skill, what goes inside one, and how skills are stored and attached.

When to write a skill

Reach for a skill when you notice the same pattern repeating. The signal is "the assistant keeps walking through the same set of steps and sometimes misses one".

• Operational procedures. "Replay a Stripe webhook locally." "Regenerate the seed fixtures." "Run the pre release checklist."
• Custom workflows. "Open a draft PR with the right labels and the right reviewers." "Bump the version, tag, and push."
• Domain specific guidance. "Build a new analytics event end to end: column, type, dashboard."

If the pattern is one or two lines, a memory is enough. Reach for a skill when the procedure has more than three steps or carries any "do this in this order" requirement.

Sources

A skill record carries a source value that tells Pathrule where its body lives.

• manual. The body is authored directly in Pathrule and stored as is. The default. Use this when you want the procedure to be fully owned by the workspace.
• template. A Pathrule provided starter skill, copied into the workspace and editable from there.
• github_ref. The skill points at an external GitHub URL. Use this for skills published by skill ecosystems you trust.

For github_ref skills, the workspace keeps a snapshot of the body taken from that source, and the skill is read-only in the workspace: VS Code tells you to edit the source instead.

SKILL.md structure

A skill is a small markdown file with frontmatter followed by the procedure body.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

Frontmatter must include name and description. Everything below is the body the assistant follows. The body can be as short or as long as it needs to be.

Attachment

A skill lives at one workspace path, the same way a rule does. Put it at the path where the procedure is most relevant. The replay webhook skill goes on services/billing/webhooks. The release skill goes at the workspace root. A new skill whose name matches an existing skill in the workspace is refused, so update the existing one instead of adding a second copy.

The assistant discovers skills through the context Pathrule delivers for a path (the same way it discovers memories and rules), through pathrule_get_context, and reads one in full with pathrule_read_skill.

Invoke a skill on demand with ::skill-name

Usually the assistant picks the right skill on its own. When you want to force a specific one, type :: followed by the skill name anywhere in your prompt, for example ::release-check or ::replay-stripe-webhook. For that turn the assistant treats the named skill as a mandatory workflow to follow, with no long instructions to write. In Claude Code and Codex the prompt hook picks the marker up before the agent acts; in other clients the assistant receives the same instruction when it requests context through MCP.

It is designed to fail safe:

• If the name matches more than one skill, no skill is invoked rather than a guess being made.
• If the name matches no skill, the assistant is told to stop and resolve it with you before editing anything. It can suggest published candidates, and it waits for your approval before adding one to the workspace.
• It ignores code-like uses of :: such as button::before or std::vector, so ordinary prompts are not misread.

That makes ::skill-name a quick, path-independent way to pull a known team procedure into the current turn.

Authoring flow

Two flows land in the same place.

• Manual authoring. In VS Code, use New Skill… at the right path and write the SKILL.md body. In a Local workspace you can also write it in the Local Console. The CLI reads skills (pathrule skill list, pathrule skill read) but does not write them.
• Assistant authoring. In Claude Code (or any MCP client) the user asks the assistant to "make this into a skill". The assistant uses a small skill creator pattern: capture intent, interview the user, draft the SKILL.md, then call pathrule_write_skill with the full body.

For low commitment scenarios the assistant drafts the skill in the conversation and waits for approval before calling pathrule_write_skill. The persisted record is therefore the reviewed draft, not a silent background write.

Versioning and concurrent edits

Skills carry a version token like memories and rules. Two teammates editing the same skill conflict cleanly rather than overwrite each other, with the same conflict choices in VS Code as for a memory.

Anti patterns

• Skills that are really memories. If the body is "this is true about how we work", make it a memory.
• Skills that are really rules. If the body is "never do X", make it a rule.
• One skill that does too much. Split into two named skills if the procedure has two distinct entry points.
• Pulling external skills you do not trust. A github_ref skill is code that runs in your assistant's instructions. Treat it like a dependency.

Local and Cloud authoring

The CLI does not write knowledge in either edition: your agent writes through Pathrule's MCP tools. In a Local workspace you also create and edit entries in the Local Console or VS Code, and for a Cloud workspace the Pathrule Cloud console shows them. The CLI's knowledge commands list, read and search them in both.

What to read next

• Writing memories for facts and decisions.
• Writing rules for constraints.
• MCP tools reference for the tools the assistant uses to write skills.