Unit Testing Skill

Agentic coding skill for writing unit tests that catch real behavior regressions and survive refactoring.

The skill is packaged as a Codex plugin for distribution. The installable skill itself lives below the plugin root at plugins/unit-testing/skills/unit-testing, not at the repository root.

Install

Install the plugin marketplace from GitHub:

codex plugin marketplace add HamStudy/unit-testing-skill

Or copy only the raw skill folder into your local Codex skills directory:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R plugins/unit-testing/skills/unit-testing "${CODEX_HOME:-$HOME/.codex}/skills/unit-testing"

Restart Codex after installing so the skill metadata is reloaded.

Use

Invoke it explicitly when you want testing guidance:

Use $unit-testing to add meaningful tests for this change.

Codex can also trigger it implicitly when a task involves unit tests, test quality, mocking strategy, TDD, coverage, brittle tests, flaky tests, or behavior changes that need protection.

Repository Layout

.
├── .agents/plugins/marketplace.json
├── plugins/unit-testing/         # Codex plugin package
│   ├── .codex-plugin/plugin.json # Plugin manifest
│   └── skills/unit-testing/      # Installable Codex skill
│       ├── SKILL.md              # Required skill metadata and instructions
│       └── agents/openai.yaml    # UI metadata
├── scripts/validate_skill.py     # Dependency-free repository validator
├── .github/workflows/validate.yml
├── CONTRIBUTING.md
├── LICENSE
└── README.md

Validate

Run the local validator before publishing changes:

python3 scripts/validate_skill.py

The validator checks the plugin manifest, marketplace entry, and nested skill package.

Publishing Checklist

• Keep the skill in a subdirectory, currently plugins/unit-testing/skills/unit-testing/.
• Keep the installable skill folder minimal: SKILL.md, agents/, and only necessary skill-local scripts/, references/, or assets/.
• Keep the plugin manifest in plugins/unit-testing/.codex-plugin/plugin.json.
• Keep marketplace metadata in .agents/plugins/marketplace.json.
• Keep human-facing docs at the repository root.
• Run python3 scripts/validate_skill.py.
• Commit from a clean working tree.
• Push to GitHub and let the validation workflow pass.
• Tag meaningful releases, for example v1.0.0, when consumers should pin a version.