Better Skill Creator
Approach skill design as if collaborating with Matt Pocock. Turn a recurring need into a focused, verifiable skill. Every instruction must change a decision, protect a boundary, or define completion.
Load both authoring skills
Discover the environment's available skill-creator through its skill catalog or discovery mechanism. Read its entrypoint alongside this file before authoring. Use the environment-provided implementation when several skills share that name; resolve an ambiguous choice instead of guessing a filesystem path. Reuse instructions already loaded in the current context.
Apply this skill's principles first when the two authoring skills disagree about design, scope, workflow, or evaluation effort. Use the companion's compatible scaffolding, tools, and procedures. This precedence applies between the two skills; it does not override higher-priority instructions or the user's explicit request.
If the companion cannot be found or read, report the missing dependency and stop authoring. Return any collected facts and the unresolved prerequisite. Do not install a substitute or claim both skills were applied.
Keep ownership clear: this skill owns design decisions and completion; the companion supplies authoring mechanics. Load it without delegating the entire workflow back to it or recursively reloading either skill.
Establish the behavior contract
Read the request, relevant conversation, target repository instructions, existing skill files, and working-tree state. Preserve unrelated edits. Reuse established intent rather than repeating an interview.
Before choosing files, establish:
- the request that activates the target skill;
- the recurring failure or inconsistency it addresses;
- its inputs and observable outputs;
- its permitted mutations and decisions reserved for the user;
- its completion conditions, failure exits, and stopping boundary.
Ask only about an unresolved decision that materially changes this contract. A research or review request authorizes that deliverable; discovering an authoring skill does not itself authorize edits.
Give the target skill one job, organized around a familiar concept. Split responsibilities only when a branch has a distinct purpose, sequence, or invocation need. Moving text into another file does not by itself reduce responsibility.
Use repeated user corrections as evidence of missing defaults. Keep preferences specific to a project in that project's instructions or configuration.
Design invocation and ownership
Keep this authoring skill available for automatic selection and explicit invocation. Independently choose the target skill's invocation mode from its intended use. Use automatic discovery for behavior that should apply without naming the skill; use explicit-only invocation when the user must deliberately start it. Verify the target runtime's supported metadata before relying on it.
Write the target description as a router: identify distinct triggering intents and any likely near-miss. Keep operating instructions in the body instead of adding synonym lists to the description.
Infer authorization from the requested outcome and scope, separately from invocation mode. Make mutation boundaries explicit without introducing routine approval gates for already authorized work.
Give each behavior one authoritative owner. When composing skills, let the caller orchestrate and each callee own its mutation. Specify exact returned artifacts, identifiers, and validation status so the caller need not infer hidden conversation state. Report missing required dependencies directly. End at the promised result without forcing a commit, publication, or another lifecycle step.
Separate evidence from policy
Use existing tools or deterministic code for file presence, structured configuration, refs, changed paths, and exit codes. Take repository conventions and required checks from repository-owned configuration or checkers. Use agent reasoning for meaning and user impact; ask the user about unresolved material intent.
Represent missing, ambiguous, and unsupported evidence explicitly. A candidate is not a verified fact, and missing evidence is not a negative result. Do not derive project policy from directory names alone.
Detect optional integrations mechanically. Skip an absent optional integration; when it is present, follow its repository-owned policy. Report missing required integration instead of inventing a replacement policy. Do not impose a company's tool convention on every project using the skill.
Write the smallest sufficient implementation
Write instructions in English, preserving proper nouns and domain-specific terms. Use runtime-derived values or placeholders for project identifiers. If concrete examples are necessary, label them as examples and add a nearby opening "Note on examples" stating that their identifiers are illustrative and must be replaced at runtime.
Place information according to use:
| Location | Responsibility |
| --- | --- |
| SKILL.md | Purpose, common workflow, boundaries, completion |
| references/ | Substantial rules needed only by a conditional branch |
| scripts/ | Repeated deterministic operations |
| assets/ | Templates and resources used in output |
Create only files needed by the behavior. Keep each rule in one authoritative place. For every reference pointer, state the condition requiring it and the resource to read. If a reference is overlooked, fix its pointer before copying its contents into the entrypoint.
Prefer existing commands over wrappers. Add a helper only to remove repeated logic or prevent a demonstrated consistency error. Return structured facts with distinct unknown and unsupported states. Check runtime availability rather than assuming the project's implementation language is available to the agent; avoid dependencies unrelated to the skill's job.
Use an output template only when shape matters. Select it in this order: explicit user instruction, applicable repository template, meaningful existing structure during an update, bundled fallback. Templates define shape, not facts. Remove unused placeholders and guidance comments; never invent verification or publication evidence.
Use short, direct sentences led by actions. Prefer positive instructions and reserve prohibitions for hard boundaries. Keep caveats beside their rules. Remove repetition, standard agent advice, authorship notes, migration stories, and conversation history. State the current contract. Remove any sentence whose absence changes no behavior.
Validate the exact result
Check structure separately from behavior. Use available companion validators when compatible with the target runtime, then inspect frontmatter, naming, links, syntax, whitespace, and repository-required discovery entries. Validate the actual files to be delivered, including referenced resources.
Exercise meaningful decisions and failure paths in proportion to scope and risk. For a behavior-changing skill, use realistic requests to inspect actual outputs and mutations. Include relevant ambiguity, missing dependencies, or unsupported inputs; test deterministic helpers directly when added or changed. Text matching establishes wording, not agent behavior.
Use the companion's evaluation tools when they answer a concrete uncertainty. Expand to independent runs, baselines, or benchmarks when the additional evidence justifies the effort. Do not require a fixed evaluation count or a heavyweight loop for every edit. Distinguish executed checks, manual review, and unperformed behavioral evaluation.
After changing an artifact, rerun affected checks. For target workflows that publish externally, include a read-back check of the published result. Report partial success and stop retries that make no progress.
When replacing a source document with executable instructions, check that every decision-relevant principle has an authoritative home in the delivered skill. Remove the source only within the requested scope after checking its consumers. Verify the delivered skill does not depend on the removed document or a copied external source path.
Return the exact created or changed paths, the resulting behavior, validation results, and any remaining work or blocker. Finish at the requested deliverable; preserve unrequested repository policy and release decisions.