An independent study of how to write predictable, composable agent skills, inspired by the public
mattpocock/skillsrepository.This project is not created, maintained, or endorsed by Matt Pocock.
English | 简体中文
Agent skills are programs written in natural language. They need more than good prose: they need clear invocation, observable gates, deliberate context boundaries, durable state, and a pruning discipline.
This repository turns patterns observed across all 39 SKILL.md files in Matt Pocock's public
repository—not only one showcase skill—into twelve practical principles for writing skills whose
process is predictable even when their output is not.
Matt's source README describes skills used for “real engineering—not vibe coding.” Its answer to process-heavy systems that reduce user control is a collection of small, adaptable, composable skills that can work with any model.
It connects four engineering failures to durable practices:
| Engineering failure | Source response | Consequence for skill design |
|---|---|---|
| The agent did not understand the intent | Grill the idea before building | Preserve user decisions and make intent explicit |
| The agent is too verbose | Build a shared domain language | Give vocabulary one owner and reuse it across runs |
| The code does not work | Use tight feedback loops, TDD, and diagnosis | Make executable evidence part of the workflow |
| The codebase becomes a ball of mud | Invest continuously in design and deep modules | Treat architecture as ongoing behavior, not a one-time plan |
This study asks what the same standard means for the skills themselves. The answer is not “write a longer prompt.” It is to engineer both a small behavioral system and the repository that carries it.
| # | Principle | What it prevents |
|---|---|---|
| 1 | Optimize for process predictability | A skill that sounds complete but behaves differently on every run |
| 2 | Separate primitives from orchestration | Rewriting the same discipline inside every end-to-end workflow |
| 3 | Treat the description as a branch index | Missed triggers, false triggers, and synonym-heavy metadata |
| 4 | Compress behavior with leading words | Long explanations that fail to anchor a stable decision pattern |
| 5 | End consequential steps with observable criteria | Premature completion and thin legwork |
| 6 | Put cheap fail-fast gates before expensive work | Parallel or costly work launched with invalid inputs |
| 7 | Separate discoverable facts from user decisions | Unnecessary questions and blurred authority boundaries |
| 8 | Persist state in purpose-built artifacts | Conversation memory becoming the system of record |
| 9 | Disclose branch-specific context progressively | Main workflows buried under irrelevant detail |
| 10 | Isolate independent judgment axes | One evaluation frame contaminating another |
| 11 | Prompt the positive and design the negative space | Negation rebound and consequential defaults left to model priors |
| 12 | Prune continuously | Duplication, sediment, sprawl, and no-op instructions |
The same decision discipline every run—not the same words every run.
- Start from concrete runs and failure cases, not from an outline of topics.
- Define what evidence makes a step or the whole run complete.
- Let creative outputs vary while keeping source order, gates, and verification stable.
- Judge every instruction by whether it reduces behavioral variance.
Reusable disciplines should have one owner; end-to-end skills should compose them.
- Put a reusable interview, testing, review, or modeling discipline in its own skill.
- Let orchestration skills own order, handoffs, and the final outcome.
- Do not duplicate a primitive's rules inside each orchestrator that calls it.
- Add a small router when humans can no longer remember the explicit entry points.
A model-facing description is invocation logic, not a miniature README.
- Front-load the skill's core action or leading term.
- Write one trigger for each genuinely different branch.
- Remove synonyms that merely restate the same branch.
- Pay the always-loaded context cost only when autonomous discovery is valuable.
Use a compact, established concept that recruits the model's existing priors.
- Prefer terms such as red-green, seam, tracer bullet, tight loop, or fog of war when they precisely fit the behavior.
- Define a coined term once; do not make the agent reconstruct it from scattered prose.
- Reuse the same vocabulary in descriptions, workflows, and artifacts.
- Keep the term only if it changes behavior; a weak slogan is still a no-op.
“Be thorough” is not a finish line.
- State what the agent can inspect to distinguish done from not done.
- Make the criterion exhaustive where omissions are a common failure.
- Require a command already run, a diff inspected, a source accounted for, or an artifact produced.
- Sharpen the criterion before splitting a workflow to combat rushing.
Validate shared preconditions once, before delegation or deep analysis.
- Resolve refs, inputs, permissions, and non-empty worksets early.
- Stop at the first invalid gate with a precise recovery action.
- Do not make multiple workers rediscover the same broken prerequisite.
- Treat early exit as a successful diagnosis when the workflow is unnecessary.
The agent investigates; the user decides.
- Read the repository and environment before asking factual questions.
- Treat the user's observed symptom as high-value evidence; verify any proposed cause against files, history, tests, traces, and callers.
- Ask one focused question when values, priorities, or authority genuinely belong to the user.
- Make assumptions explicit only when evidence cannot settle them safely.
- Leave silence as pending when approval is required; it is not consent.
Conversation context is working memory, not durable project memory.
- Give each artifact a narrow job: glossary, ADR, spec, ticket, map, handoff, or research note.
- Store a decision in one authoritative place; indexes point to it instead of copying it.
- Create an artifact when the first real content exists, not as empty ceremony.
- Keep provider-specific operations behind an adapter or a precise context pointer.
Keep the main path legible and load detail only when its branch fires.
- Inline rules every run needs.
- Move branch-only detail to a named reference.
- Write context pointers that say both when to read and why it matters.
- Co-locate a concept's definition, rules, and caveats once the reference is opened.
Independent questions deserve independent contexts.
- Separate standards compliance from specification fidelity, or any axes that can bias each other.
- Give each evaluator its own sources and evidence contract.
- Aggregate findings without silently converting distinct axes into one score.
- Preserve disagreement when it is meaningful information.
Name the target behavior; explicitly settle consequential omissions.
- Prefer “cite primary sources” to a list of sources not to use.
- Keep hard prohibitions for real guardrails and pair them with the safe action.
- Decide who owns source authority, mutation scope, stop conditions, and approval.
- Leave flexibility only where variation is intentional.
Deletion is part of skill design, not a final cleanup pass.
- Delete sentences that do not change a capable model's behavior.
- Keep each meaning in one source of truth.
- Remove stale branches and obsolete rationale instead of layering new text over them.
- Move live but conditional detail down the information hierarchy.
The strongest pattern in the source repository is not a sentence-level trick. It is responsibility ownership across a collection:
| Responsibility | Best home |
|---|---|
| Reusable discipline and vocabulary | Small, independently reachable primitive skill |
| Deliberate end-to-end flow | Explicit orchestrator |
| Cross-session facts and decisions | Narrow durable artifact |
| Platform-specific commands | Adapter or conditional reference |
| Human discoverability | Router |
| Release confidence | Promoted / in-progress / deprecated lifecycle |
That behavioral architecture is accompanied by a parallel repository-engineering layer:
| Mechanism observed in the fixed snapshot | What it controls |
|---|---|
39 SKILL.md files with 39 matching agents/openai.yaml files |
Runtime behavior versus Codex-native UI and invocation metadata |
| 22 promoted skills matching 22 plugin entries and 22 docs pages | Curated promotion and distribution |
| Promoted, in-progress, deprecated, misc, and personal buckets | Lifecycle and portability claims |
Explicit plugin allow-list plus editable skills.sh installation |
Managed subscription versus user-owned copy |
| Setup skill, provider pointers, and hard/soft dependency ADR | Project configuration and platform adaptation |
| Human docs that orient without copying runtime steps | Discovery without a second behavioral authority |
| Changesets, changelog, plugin metadata, and release workflow | Version intent and released identity |
The evidence boundary matters. This Matt snapshot contains no Python files, Python compilation,
repository-wide skill validator, universal lint/test gate, or numeric SKILL.md limit. Those
stronger mechanisms were later implemented as an independent extension in Skill Creator Pro; they
must not be retroactively attributed to Matt.
This repository now applies that independent extension to itself with a dependency-free validator and Windows/Linux CI for manifest/version agreement, installable-skill identity, English runtime sources, bilingual documentation parity, local links, script compilation, and regression tests.
Read REPOSITORY_ENGINEERING.md for the complete engineering analysis and its eight derived repository principles. See METHODOLOGY.md for the full behavioral architecture and EVIDENCE.md for attribution labels and source links.
Lifecycle evidence shows not just what the repository contains, but how its design pressure was resolved:
| Earlier form | Mature direction | Lesson |
|---|---|---|
ubiquitous-language |
domain-modeling |
Move from one-time extraction to active maintenance of shared language |
design-an-interface |
codebase-design plus conditional design references |
Turn a standalone recipe into shared vocabulary and on-demand depth |
request-refactor-plan |
to-spec plus to-tickets |
Separate the behavior contract, implementation slices, and provider publication |
qa |
triage |
Replace direct issue filing with a recoverable, evidence-aware state machine |
| Long procedural TDD | Reference-only tdd |
Delete model-known procedure and retain high-value constraints |
decision-mapping |
wayfinder |
Use one coherent leading-word system and make planning scope explicit |
The in-progress bucket is equally important: it lets stateful, executable, writing, harness-bound, and architecture-enforcement experiments evolve without silently entering the promoted release. These relationships are classified as recorded evolution or structural interpretation in EVOLUTION.md; in-progress work is not presented as a prediction.
This method was applied to OpenAI's Skill Creator baseline, then calibrated against three iterated real-world skills: Immersive Motion UI, Project Verifier, and Academic Paper Review. The work added behavior contracts, collection architecture, stronger validation and lint, forward testing, and a conditional first-release workflow. The real repositories also corrected the measuring tool itself.
The full chain—including attribution, exact validation results, Windows/Linux CI, fresh-clone and installation evidence, architecture-first findings, and limitations—is kept in the separate Skill Creator Pro case study so this README remains a map rather than a project diary.
- METHODOLOGY.md — the complete design method behind the twelve principles.
- REPOSITORY_ENGINEERING.md — collection structure, lifecycle, distribution, configuration, documentation, and release engineering.
- EVOLUTION.md — deprecated, in-progress, promoted, merged, and deleted evidence.
- EVIDENCE.md — source links and direct/pattern/interpretation labels.
- EXAMPLES.md — concrete source-backed skill-design examples.
- CASE_STUDY_SKILL_CREATOR_PRO.md — the applied evidence chain.
npx skills@latest add Conradgui/matt-pocock-inspired-skill-writingSelect skill-writing-guidelines and the agent environments where you want it installed.
/plugin marketplace add Conradgui/matt-pocock-inspired-skill-writing
/plugin install matt-pocock-inspired-skill-writing@skill-writing-guidelines
- Read the method: start with this README, then METHODOLOGY.md.
- Apply a single-file guide: copy GUIDELINES.md into your agent instructions or link to it from them.
- Copy the Agent Skill: copy
skills/skill-writing-guidelinesinto your agent's skills directory.
The packaged skill is intentionally a writing and review discipline. It does not copy Matt Pocock's skill collection or pretend to be an official replacement for it.
The guidelines are helping when you see:
- fewer invocation misses and accidental triggers;
- fewer steps declared complete without observable evidence;
- shorter main skill files with stronger conditional pointers;
- less duplicated guidance across a skill collection;
- decisions and state surviving across sessions without relying on chat history;
- smaller edits when a skill's behavior changes;
- experimental skills staying outside promoted manifests until their release contract is ready;
- source, released, CI, and installed state being reported separately.
The study snapshot is
mattpocock/skills@66898f6,
reviewed on 2026-07-14. It contains 39 SKILL.md files across promoted, in-progress, personal,
miscellaneous, and deprecated areas, plus directly linked references, repository-level routing,
ADRs, changelog evidence, per-harness metadata, plugin manifests, Changesets, human docs, and release
automation.
This repository distinguishes:
- Direct principle — explicitly documented by the source repository.
- Repository pattern — repeatedly demonstrated across independent skills.
- Interpretation — our synthesis from those patterns, labeled as such.
See EVIDENCE.md before quoting a principle as Matt Pocock's own wording.
For concrete source-backed cases, see EXAMPLES.md.
These guidelines optimize for predictable behavior and maintainability. Tiny, low-risk skills may not need every mechanism. A three-step local helper does not need a router, a capability manifest, or a library of references merely because larger systems do.
Use the smallest evidence set that can change the diagnosis, action, or claim. Expand only when impact, reach, side effects, or uncertainty justify it. Stop when the next plausible check cannot change the decision, and state skipped checks when their absence limits what can be claimed.
- Matt Pocock and the public
mattpocock/skillsrepository are the primary inspiration and evidence source. - The presentation is inspired by
multica-ai/andrej-karpathy-skills: a compact set of principles in the README, backed by directly usable files.
No affiliation or endorsement is implied. See NOTICE.md for attribution details.
MIT. See LICENSE.