OpenAI Skills
Prompt, script, skill or plugin? Choosing a workflow boundary after openai/skills
Compare reusable instructions, deterministic programs and packaged distribution using one CI-diagnosis task, without treating the deprecated catalog as a universal solution.
What you will learn
- Compare the same task, not the labels
- Separate workflow format from distribution
- Run a small selection experiment
Before you start
- Basic Git, Python and command-line concepts
- An explicit boundary for permitted repository inspection and changes
Explain the chapter’s source behavior and apply its acceptance checklist without confusing a catalog with its host.
Key takeaways
- Use the same acceptance contract for all alternatives.
- A skill organizes a workflow; a plugin adds distribution responsibilities.
- Prefer maintainability and correct scope over the number of packaged features.
Compare the same task, not the labels
Use one acceptance contract: diagnose an authorized pull request, cite the relevant failure evidence and stop before changes. A one-off prompt may be enough if the task is rare and the operator already knows the tools. A deterministic script is preferable for stable parsing or repeated checks whose inputs and outputs can be tested without model interpretation.
A skill becomes useful when the repeatable value lies in the workflow: when to gather evidence, which branches to inspect, what output to produce and when to ask for approval. The gh-fix-ci example combines those instructions with a Python helper. It does not eliminate the need to maintain the helper or to test that the host selects the workflow appropriately.
Separate workflow format from distribution
The catalog’s deprecation notice directs new users toward the OpenAI Plugins repository. Within the pinned snapshot, the plugin-creator material already distinguishes a plugin manifest, optional skill and connector folders, and marketplace entries. Packaging is therefore another responsibility beyond writing a good SKILL.md; a reusable distribution can contain more than the workflow text.
Do not infer current marketplace approval, account availability or automatic installation from a historical scaffolding example. The current official guide is the place to verify the target host’s distribution behavior. For an existing team, the practical comparison also includes rollout ownership, dependency setup, revision tracking and how a bad update can be withdrawn without losing local work.
Run a small selection experiment
Prepare both positive prompts that should use CI diagnosis and negative prompts that merely mention a check while asking for something else. Test the same evidence and tool permissions across the candidate approaches. Score correct selection, evidence quality, stopping behavior and correction effort. A more elaborate package is not better if it selects too broadly or grants a larger action surface than the task needs.
The record below is a proposed comparison matrix, not a published benchmark. It deliberately contains no winner or invented success rate. Choose the smallest maintainable boundary that meets the acceptance contract, and document why the remaining complexity is justified. Keep the old catalog’s learning value separate from the choice of a current supported distribution.
Implementation steps
- 1
Define one task and its stop condition.
- 2
Try the smallest prompt or script that can satisfy it.
- 3
Add reusable workflow instructions only where they help.
- 4
Evaluate distribution and rollback separately.
Copy-ready example
{"candidates":["one-off prompt","deterministic script","skill workflow","plugin distribution"],"acceptance":"evidence-backed diagnosis without unapproved edits","winner":null,"liveComparisonRuns":0}Frequently asked questions
Must every useful script become a skill?
No. If the operation is deterministic and already easy to invoke, a tested script may be the most maintainable solution.
Does a plugin replace the skill format?
The workflow and its distribution are different concerns. Evaluate how the target host packages reusable skills and dependencies using current guidance.
Sources
- README.mdSource checked 2026-09-08
- skills/.system/skill-installer/SKILL.mdSource checked 2026-09-08
- skills/.system/skill-installer/LICENSE.txtSource checked 2026-09-08
- skills/.system/skill-installer/scripts/install-skill-from-github.pySource checked 2026-09-08
- skills/.system/skill-installer/scripts/github_utils.pySource checked 2026-09-08
- skills/.system/skill-installer/scripts/list-skills.pySource checked 2026-09-08
- skills/.system/skill-creator/scripts/quick_validate.pySource checked 2026-09-08
- skills/.system/skill-creator/references/openai_yaml.mdSource checked 2026-09-08
- skills/.curated/gh-fix-ci/SKILL.mdSource checked 2026-09-08
- skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.pySource checked 2026-09-08
- skills/.curated/gh-fix-ci/agents/openai.yamlSource checked 2026-09-08
- skills/.system/plugin-creator/SKILL.mdSource checked 2026-09-08
- Current official skills guideSource checked 2026-09-08