Skill Patterns

This is a living reference. Add a pattern when a new shape proves itself over many sessions.

Contents

• The patterns at a glance
• Project hub
• Big-build hub
• Ownership catalog
• Learning runbook
• Personal queue / daily driver
• Handover
• Thinking document
• Skill that runs itself (scout)
• House-style skill
• Bridge skill
• Cross-cutting techniques
• Picking and combining

The patterns at a glance

Project hub

A hub for one area of work. An agent starts a session with “resume work”, reads where things stand, does the work in the repo or product, and writes back what changed. The skill is the memory, and the memory is readable: anyone can open the skill and see what the agents believe is true.

Typical layout:

The session loop the body describes:

1. Load the skill. Read HANDOVER.md and the backlog index.
2. Do the work where it belongs (code, product, queries), not in the skill.
3. At the end, file new issues or ideas, update open-prs.md, add one changelog line, and overwrite your own handover section.

The most important part of the body is a rule for where each fact goes. Without it, an agent writes durable detail into whichever file it was already editing, usually the changelog.

Pitfalls:

• One hub for everything. Make one hub per area, and add a Companions section that says what each sibling hub owns.
• A handover that turns into a log. It is a clobber file: each session replaces its own section, and a section goes when its work lands.
• A changelog that turns into an archive. Trim it as you append to it.

Big-build hub

A project hub scaled up for one large feature with many moving parts. Every person or agent that touches the feature loads one skill and gets the full picture.

Files that earn their place in addition to the project hub layout:

• design.md: the spec, trust boundaries, open questions, the options ruled out, and a dated decision log. The body tells agents to check the log before they reopen a question.
• TODO.md: the backlog, split by when each item can happen (now, after the current stack lands, blocked on a decision). PRs and review replies cite items by id.
• stack-plan.md: how a large branch splits into reviewable PRs, with per-PR checks.
• reviewer-brief.md: a one-page entry point you can hand to a reviewer as-is.
• local-testing.md: how to run the thing end to end, including the failure modes that produce silently wrong output.
• scripts/: helpers for repetitive mechanics, such as slicing or replaying stack layers.

When a reviewer asks “why this way?”, the answer is a dated decision-log entry, not a person.

Ownership catalog

An index of PostHog objects a team owns, with the context that the objects themselves cannot hold: what each one is for, how it connects to the rest, and the gotchas that bite when you read it. Good subjects are warehouse views, dashboards, alerts, Replay Vision scanners, and endpoints.

Shape:

• The body is a short index: the two or three rules an agent gets wrong if it skips them, then a map from object group to reference file.
• references/ holds one file per group (for example, one per view family).
• recipes/ holds queries that are known to work, so agents copy instead of re-deriving.

The catalog also drives changes to the objects. Before an agent creates a new alert or view, it reads the catalog to check for an existing one, then adds the new object to the catalog as part of the same change. When something fires or breaks, the agent loads the catalog first to get the object’s purpose, baseline, and history.

Pair a catalog with a steward scout that checks the objects on a schedule and updates the skill when it fixes something. See the maintainer / steward pattern in authoring-scouts.

Learning runbook

A read-only diagnostic runbook that gets better every time it is used.

Shape:

• Rules before queries. The body opens with the few rules that cause wrong answers when skipped, such as time zones, identity resolution across accounts, or which data source is fresh.
• Pick an avenue. A list that routes each symptom to one reference file and its recipes.
• investigations/. A dated write-up for each new class of issue.

The maintenance contract is the part that makes it learn. The body says: every time an investigation finds a new class of issue, write it up in investigations/ and extend the matching reference. The next agent then starts from the last agent’s findings instead of from zero.

Personal queue / daily driver

A skill that answers “what needs me next?” for one person, across the inbox, GitHub, tickets, or accounts. It renders one line per item with its state and a next action.

Shape:

• scripts/ do the mechanical work: fetch from the APIs, rank, and render a table. Scripts give the same output every run, which prose instructions do not.
• working-set.md records only the items the person chose to own.
• The body puts live data first, memory second: the API is the truth, and the working set is a list of commitments. Never report status from the file alone.

A queue skill often pairs with a scout that runs it on a schedule and keeps one living report current, so the answer is ready before the person asks. The community store has a generic starting point, my-inbox.

Handover

When work passes to someone else, write the handover as links to skills rather than as prose. Each bullet names a skill (the project hub, the runbook, the catalog) and says when to use it.

This works because the store is shared. The handover reaches the person and their agent at the same time. They do not need to paste context into their own agent: they say “use the skill in the PostHog MCP to help here”, and their agent gets the same context the author’s agent had.

Thinking document

A skill does not have to be instructions. A plan, a quarterly draft, or a research note that evolves over weeks with an agent’s help also fits well:

• The agent reads it on any surface and edits it with small edits.
• Every revision is a version you can diff.

Keep it as one body until it outgrows one screen, then split sections into references/.

Skill that runs itself (scout)

Every Signals scout is a skill with a schedule. When a skill describes a job you do regularly (check a catalog, sweep a queue, audit a fleet), turning it into a scout is a small step. Some useful scouts maintain other skills: a steward that keeps a catalog current, or a reviewer that checks recently changed skills against the house style.

See authoring-scouts for the scout format, and working-with-scouts to delegate a watch without writing one.

House-style skill

A team that maintains many skills benefits from one skill that says how skills are written: the spec floor, the team’s patterns, a smell checklist, and a refactoring workflow. Tell agents to load it before they create or edit a skill. It should follow its own rules: a thin body and the substance in bundled files.

The community store has skills-best-practices as a starting point, and skills-spec, which is the Agent Skills specification as a skill.

Bridge skill

If an agent supports local skill files, a tiny local skill can point at the skills-store skill so a short command (for example /phs) loads the store. Keep the bridge thin, so updates to the store skill reach everyone without a local change. The PostHog AI plugin already includes skills-store, so plugin users do not need a bridge.

Cross-cutting techniques

• Give every agent-maintained skill a convention. A skill with no rule for where things go is a blank page, and agents fill blank pages with noise. State where each kind of fact goes and what the end-of-session write looks like.
• Keep the body to about one screen. The body is an index: what this is, the gotchas that bite hardest, the file map, companions, and the maintenance contract. New detail goes in a bundled file, and the body gains only a pointer.
• Bound every growing file. Rolling windows for changelogs, clobber sections for handovers, one file per issue. Anything that only grows eventually costs more to load than it saves.
• Keep every file reachable from the body. A file that no index links is invisible to progressive disclosure.
• Link instead of copying. A Companions section or a Related skills footer costs one line. A copied paragraph drifts.
• Dogfood in the same session. Use the skill for its real job. Where the agent stumbled or you had to supply context by hand, fix the skill before you finish.
• Use the smallest write. edits and file_edits with a chained base_version, as the main skill body describes. A full-body rewrite for a small change can silently drop content.

Picking and combining

Most real skills combine two or three patterns. A big-build hub is a project hub with a design doc. A catalog is often paired with a runbook for the same objects, and both are often kept current by a steward scout. A personal queue becomes a scout once its output is worth having before you ask.

If no pattern fits, start with the smallest skill that holds the context you keep re-explaining. Add structure when you see the same kind of fact written in the wrong place twice.