role-creator

Create and update Codex custom agents using standalone custom-agent TOML files.

Quality

58%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/role-creator/SKILL.md

Quality

Discovery

40%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear, distinctive niche (Codex custom agent TOML files) but is too terse. It lacks an explicit 'Use when...' clause and could benefit from listing more specific actions and natural trigger terms users might employ.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, edit, or configure a Codex custom agent, or mentions agent TOML files.'

Expand the list of concrete actions beyond 'create and update', such as 'validate TOML syntax, configure agent parameters, set system prompts, define tool access'.

Include natural keyword variations like 'agent configuration', 'agent setup', '.toml files', 'custom agent definition' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (Codex custom agents) and two actions (create and update), but doesn't list more granular capabilities like configuring specific TOML fields, validating agent configs, or managing agent properties.	2 / 3
Completeness	Describes what it does (create and update custom agents via TOML files) but has no explicit 'Use when...' clause or trigger guidance, which per the rubric caps completeness at 2, and the 'what' is also fairly thin, placing this at 1.	1 / 3
Trigger Term Quality	Includes relevant terms like 'Codex', 'custom agents', and 'TOML files', but misses natural variations users might say such as 'agent configuration', 'agent setup', '.toml', or 'define an agent'.	2 / 3
Distinctiveness Conflict Risk	The combination of 'Codex custom agents' and 'TOML files' is a very specific niche that is unlikely to conflict with other skills. The domain is narrow and clearly defined.	3 / 3
	Total	8 / 12 Passed

Implementation

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a well-structured, actionable skill with clear workflows and concrete examples. Its main strengths are the executable shell commands, explicit validation steps, and the strict input-confirmation gate before writing. Minor weaknesses include some verbosity in explaining concepts and referencing external files (templates/) that aren't provided in the bundle.

Suggestions

Tighten the 'Non-Negotiable Inputs' section into a compact checklist format rather than a bulleted list with explanatory parentheticals

Either include the referenced templates/ directory in the bundle or remove the reference to avoid dead-end navigation

Dimension	Reasoning	Score
Conciseness	Generally efficient but has some redundancy—e.g., restating 'name is the spawn identifier and source of truth' after already establishing it, and the 'Non-Negotiable Inputs' section is somewhat verbose for what could be a simple checklist. The 'Default policy for optional settings' section states things Claude would naturally do if told to keep files minimal.	2 / 3
Actionability	Provides concrete shell commands with full flag examples, specific file paths, a ready-to-run JSON invocation example, and explicit validation steps (tomlq). The workflow is copy-paste ready with real commands and realistic parameter values.	3 / 3
Workflow Clarity	The workflow is clearly sequenced (collect inputs → resolve path → write file → validate → return example call) with an explicit validation step (step 4: validate TOML parse and required keys) and guardrails for error recovery (check syntax with tomlq, verify scope if unknown agent_type). The execution rule 'do not write until required inputs are explicitly confirmed' acts as a checkpoint.	3 / 3
Progressive Disclosure	References external docs and a templates/ directory, but no bundle files are provided to support these references. The content is reasonably structured with clear sections, but some content (like the full role file contract) could potentially be split out. The references to external URLs and templates/ are present but unverifiable without bundle support.	2 / 3
	Total	10 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: am-will/codex-skills
Commit: d3983b1

Reviewed: 24 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.