make-skill
Turn a project, tool, API, workflow, SOP, documentation set, or library into an installable Codex Skill. Use when the user asks to create, update, package, scaffold, or evaluate a Skill from a GitHub
Файлы18
Открыть в GitHubSKILL.mdskill/make-skill/SKILL.md
GitHubMake Skill
Turn reusable procedural knowledge into a small, installable Skill. Optimize for modern Codex: assume the model is capable, keep instructions lean, and bundle deterministic scripts or references only where they reduce repeated work.
Core Judgment
A good Skill does one or more of these:
- Preserves domain knowledge the model cannot reliably know.
- Provides a repeatable workflow with fragile sequencing.
- Bundles scripts, templates, or assets that avoid rewriting boilerplate.
- Documents project-specific APIs, schemas, commands, or constraints.
- Improves trigger reliability for a recurring class of user requests.
Do not create a Skill for generic advice that a mature model already performs well without extra context.
Pipeline
- Research the source.
- Decide convertibility.
- Choose Skill type and structure.
- Generate or update
SKILL.mdand resources. - Generate
agents/openai.yaml. - Validate and forward-test when risk justifies it.
- Package as
.skillwhen requested. - Present install path and usage examples.
If the user only asks whether something can be a Skill, stop after the convertibility verdict.
Phase 1: Research
Prefer local files over web search when the source is already in the workspace. Browse current official docs or repositories when the source is external or may have changed.
| Source | Minimum research |
|---|---|
| GitHub repo | README, docs/ or examples/, install command, license, activity |
| CLI tool | install command, top commands/flags, examples, common errors |
| Library/package | install command, core API, I/O formats, version constraints |
| REST/GraphQL API | auth, base URL, key endpoints, rate limits, examples |
| MCP server | startup command, transport, tool list, required env vars |
| Internal workflow/SOP | trigger, inputs, decision points, outputs, failure modes |
| Methodology/docs | core process, edge cases, output format, when not to use |
Research limits:
- Start with at most three high-value documents or pages.
- Extract facts before fetching more.
- Put large reference material in
references/rather thanSKILL.md. - Ask the user only for missing private details that cannot be discovered.
Minimum evidence before building:
- What task the Skill enables.
- At least two realistic trigger prompts.
- Inputs, outputs, and required tools/dependencies.
- Known credentials, costs, or destructive operations.
For a local project, run the bundled inspector before making the convertibility decision:
python scripts/inspect_project.py path/to/project --output project-analysis.json
The inspector detects the ecosystem and likely Skill type, extracts package
metadata and environment-variable names, and checks installed Skill directories
for likely duplicates. For Markdown READMEs it also records installation commands
and ranks up to three source-backed usage examples with section and line evidence.
Sensitive-looking example values are redacted. Treat the conversion score as a
transparent heuristic, not as the final decision. Inspector output omits absolute
local paths by default; use --include-local-paths only for private diagnostics.
For a high-value local project with no strong duplicate, generate a concrete review-required draft:
python scripts/bootstrap_from_project.py path/to/project --output ./skill-src
The bootstrapper creates a source-informed SKILL.md, agents/openai.yaml,
evals/evals.json, and references/project-analysis.json. Extracted README setup
commands and two or three high-confidence examples are inserted into the draft;
package metadata is used only as a clearly labeled setup fallback. It stops on
high-similarity duplicate Skills unless --allow-duplicate is explicitly used.
Extraction is not execution verification, so run every retained example before
release and add examples manually when the README provides none.
Phase 2: Convertibility Verdict
Read references/blockers.md when the source may need a GUI, daemon, hardware,
root access, OAuth/browser login, or large dependencies.
Use this verdict format:
Can be converted: yes/no/partial
Type: [CLI/library/API/MCP/knowledge/workflow/template]
Value: [high/medium/low]
Reason: [one paragraph]
Planned files: [SKILL.md, scripts/x.py, references/y.md, assets/...]
Risks: [credentials, cost, fragility, current docs needed, etc.]
High value means the Skill adds durable knowledge, scripts, templates, or a fragile procedure. Low value means the content is mostly generic prompting.
If inspect_project.py reports a duplicate candidate, inspect that Skill before
creating anything. Prefer extending a compatible existing Skill over publishing
a second Skill with overlapping triggers.
Phase 3: Choose Structure
Use the smallest structure that works.
| Type | Use when | Typical files |
|---|---|---|
| CLI wrapper | Repeated shell commands, flags, conversions | SKILL.md, optional scripts/ |
| Library | Repeated code imports/patterns | SKILL.md, helper scripts, examples |
| API | HTTP service with auth/endpoints | SKILL.md, references/api.md, scripts |
| MCP server | Skill teaches how to install/use MCP server | SKILL.md, references/tools.md |
| Knowledge | Domain framework or SOP | SKILL.md, optional references |
| Workflow | Multi-tool sequence | SKILL.md, scripts, references |
| Template | Reusable artifact format/assets | SKILL.md, assets/, references |
Scaffold when helpful:
python scripts/scaffold.py --name my-skill --type workflow --output ./skill-src
Phase 4: Write The Skill
Frontmatter
Use only:
---
name: kebab-case-name
description: >
Action-oriented trigger description. Include what the Skill does and the
concrete situations where Codex should use it.
---
Name rules:
- Lowercase letters, digits, and hyphens only.
- Folder name must exactly match
name. - Keep under 64 characters.
- Avoid generic names like
helper,workflow, oranalysis.
Description rules:
- Include trigger phrasings the user might actually type.
- Keep it specific enough to avoid triggering on unrelated tasks.
- Avoid angle brackets and placeholder text.
- Keep under 1024 characters unless the local platform explicitly allows more.
Body
Keep SKILL.md concise. Default target: under 250 lines unless the workflow is
genuinely complex.
Recommended sections:
- Overview: what this Skill enables.
- When to use / when not to use.
- Workflow or core commands.
- Resource routing: which references/scripts/assets to use and when.
- Validation: how to know the work succeeded.
- Edge cases and safety boundaries.
Move detailed docs to references/. Add scripts when the same code would be
rewritten repeatedly or deterministic behavior matters.
Phase 5: Generate UI Metadata
Create or refresh agents/openai.yaml after writing SKILL.md:
python scripts/generate_openai_yaml.py path/to/skill
Override generated values when the default wording is too generic:
python scripts/generate_openai_yaml.py path/to/skill \
--display-name "GitHub Check" \
--short-description "Audit GitHub repo trust signals" \
--default-prompt "Use $github-check to evaluate whether this GitHub repository is trustworthy."
The default prompt must mention $skill-name.
Phase 6: Validate
Run the bundled validator:
python scripts/quick_validate.py path/to/skill
Before release, generate evals and run strict validation:
python scripts/generate_evals.py path/to/skill \
--happy "[real common request]" \
--edge "[real missing-input or auth case]" \
--negative "[nearby request that should not trigger]"
python scripts/quick_validate.py path/to/skill --strict
Validation must pass before packaging. Then do a content review:
- Trigger description is specific and useful.
SKILL.mdreferences only files that exist.- No unfinished placeholder markers, secrets, full tokens, cookies, or private data.
- Scripts have argument parsing and can be run from the command line.
- The Skill does not duplicate existing system/global instructions unless it adds a concrete workflow or asset.
- Large references have headings and are only loaded when needed.
Phase 7: Forward-Test
Forward-test when the Skill is complex, newly created, likely to trigger often, or changes behavior beyond formatting. Use fresh context if possible. Do not pass your intended answer; pass the Skill path and a realistic user request.
Suggested prompts:
Use $skill-name at path/to/skill-name to solve: [realistic task]
Test at least:
- Happy path: the most common request.
- Edge path: missing input, private docs, auth, rate limit, or unsupported source.
- Mis-trigger path: a nearby request where the Skill should not be used.
Record only concise results in the final delivery:
Forward-test:
- happy path: pass/fail, key observation
- edge path: pass/fail, key observation
- mis-trigger path: pass/fail, key observation
Skip forward-testing only when the edit is trivial or no safe isolated test is available. Explain the reason.
Phase 8: Package
Package only the Skill folder itself, not a parent directory containing multiple skills.
python scripts/package_skill.py path/to/skill ./dist
The output is dist/<skill-name>.skill.
Phase 9: Deliver
Report:
- Skill name.
- What changed or what was generated.
.skilloutput path.- Two or three trigger examples.
- Any remaining risks, credentials, or manual install steps.
Do not tell the user to manually recreate files already present in the workspace.
Resources
references/convertible-patterns.md: templates and examples by Skill type.references/blockers.md: hard and soft blockers.references/skill-spec.md: validation and packaging rules.