Engineer agent skills for real work—not prompt-shaped demos.
English | 简体中文
Skill Creator Pro is a behavior-first, Codex-native toolkit for designing, building, validating, and publishing new agent skills. It extends OpenAI's Skill Creator with explicit behavior contracts, observable workflow gates, collection-level architecture, quality linting, portability checks, and realistic forward testing.
Why this layer matters: a skill creator sets the quality ceiling for every skill built with it.
“Pro” means an independently maintained engineering enhancement. It does not imply an official, paid, or endorsed OpenAI edition.
The original Skill Creator is a strong general introduction to skill anatomy, progressive disclosure, bundled resources, scaffolding, and structural validation. Real production work exposed several places where a more explicit engineering contract was useful:
| Gap observed in the baseline | Risk in real skills | Skill Creator Pro response |
|---|---|---|
| Start from skill contents and scaffolding | A polished folder can still encode the wrong behavior | Establish trigger branches, near misses, state, side effects, evidence, and failure behavior first |
| Invocation described mainly through metadata wording | Skills may under-trigger, over-trigger, or copy fields from the wrong harness | Make implicit/explicit invocation and Codex policy an explicit design decision |
| Resource guidance centered on one skill at a time | Collections duplicate vocabulary, adapters, and durable state | Assign primitives, orchestrators, artifacts, adapters, and routers one owner each |
| Completion described at workflow level | Agents can rush consequential phases or stop after thin investigation | End important steps with checkable and sometimes exhaustive Done when gates |
| Structural validation as the primary automated check | Valid YAML can still contain TODOs, weak pointers, duplication, or platform traps | Add deterministic structural checks plus judgment-oriented quality lint |
| Forward testing recommended without a fixed coverage floor | A happy-path demo can hide trigger, permission, and regression failures | Require trigger, near-miss, alternate branch, blocked-input, and regression coverage when risk warrants it |
| Platform behavior left to the implementation | POSIX assumptions, path conversion, encoding, or symlink permissions can masquerade as skill failure | Treat claimed runtime support as part of the behavior contract |
| No end-to-end publication branch | A locally valid skill can ship with stale identity, missing attribution, broken CI, or an untested installer | Treat repository packaging and first release as observable engineering gates |
The goal is not to make every skill large. It is to make every consequential choice deliberate and every completion claim observable.
Skill Creator Pro deliberately owns only the new-skill lifecycle. The planned Skill Review
owns the existing-skill lifecycle.
| Boundary | Skill Creator Pro | Skill Review |
|---|---|---|
| Starting point | A repeated workflow, new capability, or deliberate fork/rebuild under a new identity | An existing skill with real usage, history, tests, and observed failures |
| Primary question | What behavior contract should this new skill implement and how will it ship? | Why does this existing skill behave as it does, what is sound, and what should change? |
| Primary output | A new validated, forward-tested, installable skill and its first release | An evidence-backed review, architecture model, and optional authorized improvement patch |
| Mutation default | Build the new artifact | Read-only review first; edit only with explicit authority |
| Evolution history | Source evidence only when rebuilding or forking | Required evidence for separating learned invariants from accidental sediment |
| Release ownership | Initial packaging and publication of the skill being created | Audit release drift in an existing project; hand a rebuild or new release contract to Creator Pro |
If the request begins with “why does this existing skill misfire?” or “how should this existing skill be improved?”, use Skill Review. Creator Pro may repair defects found inside its own pre-release loop; that does not make it a general existing-skill reviewer.
Matt Pocock describes his public collection as skills he uses “to do real engineering—not vibe
coding,” and emphasizes that the skills are small, adaptable, and composable. See
mattpocock/skills.
Skill Creator Pro applies that standard one layer earlier: to the system that creates the skills. A production-ready skill should be able to answer:
- Why did it trigger for this request, and why should it reject a near miss?
- Which sources, state, and user decisions control the run?
- What observable gate separates one phase from the next?
- Which artifact proves completion?
- What happens when evidence, authority, or runtime support is missing?
- Can a fresh agent reproduce the intended process without hidden coaching?
The following compact map comes from our repository-wide study of Matt Pocock's public skills. The twelve-part organization is our independent synthesis, not an official list authored or endorsed by Matt Pocock.
| # | Principle | Applied here as |
|---|---|---|
| 1 | Optimize for process predictability | Stable decision and verification paths across runs |
| 2 | Separate primitives from orchestration | One owner for reusable discipline; thin composition elsewhere |
| 3 | Treat the description as a branch index | One trigger per genuine invocation branch |
| 4 | Compress behavior with leading words | Established terms such as fail fast and single source of truth |
| 5 | End consequential steps with observable criteria | Checkable, sometimes exhaustive Done when gates |
| 6 | Put cheap fail-fast gates before expensive work | Validate refs, inputs, links, and permissions before delegation |
| 7 | Separate discoverable facts from user decisions | Inspect the environment; ask only for real choices or authority |
| 8 | Persist state in purpose-built artifacts | Narrow specs, tickets, ledgers, reports, and handoffs |
| 9 | Disclose branch-specific context progressively | Conditional references with explicit firing conditions |
| 10 | Isolate independent judgment axes | Separate contexts and preserve distinct outcomes |
| 11 | Prompt the positive and design the negative space | Name the target behavior and settle consequential omissions |
| 12 | Prune continuously | Remove no-ops, duplication, sediment, and sprawl |
For the complete explanations, evidence labels, and source links, read Matt Pocock-Inspired Skill Writing Guidelines.
Every substantial run begins with concrete examples and records:
- outcome;
- trigger branches and near misses;
- inputs, state, outputs, and side effects;
- observable success evidence;
- failure, fallback, and authority boundaries.
This prevents the common failure of writing an elegant SKILL.md before deciding what behavior it
must stabilize.
Skill Creator Pro distinguishes implicit and explicit invocation using Codex-native metadata. At collection scale, it assigns responsibilities across:
- reusable primitive skills;
- deliberate orchestrators;
- durable artifacts;
- provider adapters;
- human-facing routers;
- promotion and lifecycle boundaries.
The design target is one owner per behavior or fact, not a collection of overlapping prompts.
Content is classified as main-path steps, shared inline reference, conditional reference, deterministic scripts, or output assets. Branch-only knowledge moves behind a pointer that states both when to read it and why it matters.
Large modular skills may use a capability manifest that makes module status, triggers, references, dependencies, fallback behavior, and verification machine-checkable.
The workflow explicitly covers:
- cheap fail-fast preconditions;
- fixed source-discovery order;
- checkable and exhaustive completion criteria;
- stop and fallback behavior;
- independent evaluation axes;
- bounded delegation contracts;
- source, mutation, evidence, and approval negative space.
Stateful or high-risk skills also keep progress, evidence outcome, execution scope, and claim eligibility separate.
When a skill can both judge and modify an artifact, Skill Creator Pro treats them as separate modes. Review stays read-only by default. Edit mode defines an immutable ledger of claims, numbers, citations, identifiers, or other invariants, then verifies the output against it. Stable finding IDs and status tokens survive delta reviews when downstream artifacts depend on them.
init_skill.py now creates a minimal behavior-first skeleton:
Outcome → consequential step → observable Done when → next step
Optional scripts, references, and assets are created only when requested. Example files are explicit replace-or-delete placeholders rather than permanent tutorial sediment.
quick_validate.py checks more than frontmatter:
- skill and folder naming;
- TODO residue;
- a 500-line diagnostic boundary;
- live local Markdown links and path escape, excluding fenced examples;
agents/openai.yamlstructure and UI metadata;short_descriptionlength;- explicit invocation policy;
- default-prompt references;
- YAML block scalars, including
>-and|-.
Repository regression tests lock down fenced-code handling, real broken-link detection, YAML chomping markers, and lint isolation.
quality_lint.py surfaces risks that require author judgment:
- vague completion language;
- weak or missing context pointers;
- duplicated paragraphs;
- scattered negative instructions;
- missing observable criteria;
- Windows-unsafe Node
import.meta.url.pathnameusage; - English and Chinese pointer/negative-language patterns.
Warnings are aggregated so one safety-heavy skill does not bury more important findings under dozens of identical lines.
For complex or previously unreliable skills, the process covers:
- a request that should trigger;
- a near miss that should not trigger;
- the common happy path;
- a materially different branch;
- a missing-input or blocked-permission path;
- the original regression for an existing broken skill.
Fresh evaluators receive raw artifacts and task-local context, not the expected answer or intended fix.
When publication is requested, Creator Pro treats the release as part of the skill contract:
- synchronize skill, folder, UI, repository, router, and installer identity;
- separate the exact runtime artifact from human documentation and test workbenches;
- preserve upstream licenses and mark modified derivative files;
- keep one runtime source language and mirror human translations without adding new rules;
- run structure, mechanics, behavior, documentation, license, and supported-platform CI gates;
- create the remote only with authority, then wait for remote CI;
- clone and install from the public remote, confirm only intended skills are discovered, and compare installed identity with the source;
- preserve an upstream/system skill when a renamed derivative must coexist with it.
The canonical workflow is Skill Release Engineering.
Three independently developed skill repositories were used as design studies while Creator Pro was built. The author confirms that their architecture emerged through repeated iteration rather than from a complete upfront plan. That makes their evolution—not incidental platform defects—the most valuable evidence.
| Repository | Architecture that emerged | Quality control that became explicit | What Creator Pro learned |
|---|---|---|---|
immersive-motion-ui-skill |
Capability graph, Core/optional-Library layering, and audit/redesign modes | Machine-validated manifest, explicit fallback, verifier ownership, and evidence-status tokens | Large modular skills need a checkable capability contract once prose routing stops scaling |
project-verifier-skill |
Four-stage control plane, authorization envelope, and separate state dimensions | Side-effect-free preflight, source-revision-bound approval, receipts, and claim eligibility | High-risk skills must not collapse progress, evidence outcome, execution scope, and permissible claims into one status |
Academic-Paper-Review-Skill |
Mode router, scientific/textual axes, executor/evaluator boundaries, and format-specific adapters | Immutable content ledger, stable finding IDs, exact status tokens, blind evaluation, and forward-test records | Skills that both judge and rewrite artifacts need explicit modes, protected invariants, and traceable rechecks |
The shared lesson is evolutionary: sophisticated architecture often appears only after real failures make an invariant visible. Creator Pro therefore supports incremental construction and evidence gates; the future Skill Review will own reconstructing that evolution in an existing skill before proposing deletion or redesign.
Portability findings—Windows file-URL conversion, POSIX-first runners, UTF-8 boundaries, and symlink privileges—remain useful secondary evidence, but they are not the architectural headline. The studies also corrected Creator Pro itself: YAML block scalars were added, repetitive negative-language warnings were aggregated, Chinese pointers were recognized, and fenced examples were excluded from live-link linting.
See Real-World Evaluation for architecture, evolution, commands, secondary portability evidence, and limitations.
npx skills@latest add Conradgui/skill-creator-proSelect skill-creator-pro and Codex when prompted.
Ask Codex:
Use $skill-installer to install the skill at
https://github.com/Conradgui/skill-creator-pro/tree/main/skills/skill-creator-pro
Copy skills/skill-creator-pro into $CODEX_HOME/skills/skill-creator-pro or
~/.codex/skills/skill-creator-pro when CODEX_HOME is unset.
Restart or begin a new Codex turn after installation so the new skill is discovered.
Create a new skill:
Use $skill-creator-pro to turn this repeated workflow into a production-ready Codex skill.
Package and publish the new skill:
Use $skill-creator-pro to package the skill we just built as an installable public repository, run
the release gates, publish it, and verify remote installation.
Deliberately rebuild an existing workflow as a new skill identity:
Use $skill-creator-pro to treat this existing workflow as source evidence for a new skill. Preserve
named invariants, define a new behavior contract, and release it under a non-conflicting identity.
For an in-place audit or improvement of an existing skill, use the planned Skill Review instead. Creator Pro invokes implicitly for suitable new-skill creation and first-release requests unless the active Codex configuration overrides that policy.
skill-creator-pro/
├── README.md
├── README.zh.md
├── LICENSE
├── NOTICE
├── docs/
│ ├── REAL_WORLD_EVALUATION.md
│ └── REAL_WORLD_EVALUATION.zh.md
├── tests/
│ └── test_validator_regressions.py
└── skills/
└── skill-creator-pro/
├── SKILL.md
├── agents/openai.yaml
├── references/
│ ├── openai_yaml.md
│ ├── predictable-skill-design.md
│ └── release-engineering.md
└── scripts/
├── init_skill.py
├── generate_openai_yaml.py
├── quick_validate.py
├── quality_lint.py
└── _yaml_subset.py
The skill folder contains only runtime material. Human-facing project history and evaluation reports
remain at repository root or under docs/.
- Primary target: Codex Skill format and
agents/openai.yaml. - Runtime: Python standard library; no Python package dependency.
- Tested release gates: Windows and Linux GitHub Actions.
- Other Agent Skills-compatible harnesses may load
SKILL.md, but Codex-specific invocation and UI metadata must be translated rather than assumed portable.
Skill Creator Pro is a derivative of OpenAI's Apache-2.0-licensed Skill Creator, with substantial independent modifications. It is also informed by a repository-wide study of Matt Pocock's public, MIT-licensed skills. Neither OpenAI nor Matt Pocock maintains or endorses this project.
See NOTICE for exact source revisions and modification notices.
Apache License 2.0. See LICENSE.