evaluate-skill — Codex skill: what it does, how to install
Audits a local skill, explains the score, and points to the first fixes. Use it before benchmarking or measuring token usage.
npx skills add openai/plugins --skill evaluate-skill -a codexWhat evaluate-skill does
This skill works with a local skill directory or a SKILL.md file. It can route a natural-language request with plugin-eval start, run plugin-eval analyze, and guide the review of At a Glance, Why It Matters, Fix First, and Recommended Next Step. A local skill path or SKILL.md is required for the workflow.
The review covers frontmatter, the quality of name and description, progressive disclosure, relative links, oversized files or descriptions, and helper code in TypeScript or Python. Findings are separated into structural, budget, and code-related issues. When the request asks for an analysis, the skill also runs plugin-eval init-benchmark and presents questions for refining the starter benchmark scenarios.
What it helps with
- audit a local skill before benchmarking it
- spot frontmatter and link problems
- explain why a skill received its score
- decide which fix comes first
- prepare benchmark scenarios
Example prompts for the agent
- Evaluate the local skill in
~/.codex/skills/game-devand explain the first fix. - Audit
SKILL.md, then separate structural, budget, and code findings. - Show the setup questions for refining this skill’s starter benchmark scenarios.
How to install evaluate-skill
1Skills CLI (Vercel)
npx skills add openai/plugins --skill evaluate-skill -a codex2Manually: put the files in place
.agents/skills/evaluate-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add openai/plugins --skill evaluate-skill -a claude-code2Manually: put the files in place
~/.claude/skills/evaluate-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/evaluate-skill/
Manually: put the files in place
.cursor/skills/evaluate-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install openai/plugins evaluate-skill2Manually: put the files in place
.github/skills/evaluate-skill/SKILL.mdPlatform CLI
gemini skills install https://github.com/openai/plugins --path plugins/plugin-eval/skills/evaluate-skillManually: put the files in place
.devin/skills/evaluate-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: Codex skills: how to install, where they live, how to call them
Questions about evaluate-skill
How do I install evaluate-skill in Codex?
Run npx skills add openai/plugins --skill evaluate-skill, then run npx skills add openai/plugins --skill evaluate-skill -a codex. The skill file will be at .agents/skills/evaluate-skill/SKILL.md.
What does evaluate-skill do?
It audits a local skill, explains findings across structure, budget, and code, and identifies the next step. An analysis request also starts benchmark setup.
What does the skill check?
It reviews frontmatter, name, description, progressive disclosure, relative links, file and description size, plus helper files written in TypeScript or Python.
Source text
SKILL.md · MIT
--- name: evaluate-skill description: Evaluate a local Codex skill in engineer-friendly terms. Use when the user says "evaluate this skill", "give me an analysis of the game dev skill", "audit this skill", "why did this score that way", "what should I fix first", or asks for a skill-specific report before benchmarking it. --- # Evaluate Skill Use this skill when the target is a local skill directory or `SKILL.md` file. ## Workflow 1. Treat "Evaluate this skill." as the default entrypoint. 2. If the user names a skill instead of giving a path, resolve it locally first, preferring `~/.codex/skills/<skill-name>` and then repo-local `skills/<skill-name>`. 3. If the user says the request in natural language first, use `plugin-eval start <skill-path> --request "<user request>" --format markdown` to show the routed path clearly. 4. Run `plugin-eval analyze <skill-path> --format markdown`. 5. Review `At a Glance`, `Why It Matters`, `Fix First`, and `Recommended Next Step` before drilling into details. 6. Explain which findings are structural, which are budget-related, and which are code-related. 7. If the user asks for an "analysis" of the skill, do not stop at the report. Also run `plugin-eval init-benchmark <skill-path>` and show the setup questions for refining the starter scenarios in `.plugin-eval/benchmark.json`. 8. If the user wants real usage numbers, switch to "Measure the real token usage of this skill." and run the benchmark flow. 9. After observed usage is available, use `plugin-eval measurement-plan <skill-path> --observed-usage <usage.jsonl> --format markdown` to recommend what to instrument or improve next. 10. If the user wants a rewrite plan, route to `../improve-skill/SKILL.md`. ## Skill-Specific Priorities - frontmatter validity - `name` and `description` quality - progressive disclosure and reference usage - broken relative links - oversized `SKILL.md` or descriptions - helper script quality for TypeScript and Python files ## Chat Requests To Recognize - `Evaluate this skill.` - `Give me an analysis of the game dev skill.` - `Audit this skill.` - `Why did this skill score that way?` - `What should I fix first?` - `Measure the real token usage of this skill.` ## Commands ```bash plugin-eval start <skill-path> --request "Evaluate this skill." --format markdown plugin-eval analyze <skill-path> --format markdown plugin-eval explain-budget <skill-path> --format markdown plugin-eval measurement-plan <skill-path> --format markdown plugin-eval init-benchmark <skill-path> plugin-eval benchmark <skill-path> --dry-run ``` ## Reference - `../../references/chat-first-workflows.md`
© OpenAI Codex · MIT · openai/plugins
