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. The runtime fetches and caches the body. Use this for skills published by skill ecosystems you trust.

For github_ref skills, the cached body is the snapshot Pathrule served last. If the upstream skill changes, the workspace picks it up on the next refresh.

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 is a workspace level object. It is attached to nodes through a small join, the same way rules are. One skill can be attached to many paths.

In practice you attach a skill to the node where the procedure is most relevant. The replay webhook skill goes on services/billing/webhooks. The release skill goes at the workspace root.

The assistant discovers skills through the hook supervisor (same way it discovers memories and rules) or via the pathrule_list_memories and related MCP tools.

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.

It is designed to fail safe:

• If the name matches no skill, or matches more than one, Pathrule does nothing rather than guess.
• It ignores code-like uses of :: such as button::before or std::vector, so ordinary prompts are never 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. Open Pathrule Web or Pathrule Studio, create a new skill at the right node, paste the SKILL.md body, save.
• 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 can also call pathrule_suggest_skill instead of writing directly. The suggestion lands in the Suggestions tab in Pathrule Web for a human to approve.

Versioning and concurrent edits

Skills carry a version token like memories and rules. Two teammates editing the same skill conflict cleanly. The same three way merge UI applies.

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.

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.