How to Create Custom Skills for Claude Code and Codex

You can generate custom skills for Claude Code and OpenAI Codex manually by creating a SKILL.md file in .claude/skills/ or .codex/skills/, or automatically by prompting the agent at the end of a session to review repetitive workflows and package them into standard skill directories. The CLI indexes metadata at startup and activates the complete instructions only when relevant user requests trigger the skill description.

Before you start

Install Claude Code (v2.0+) or OpenAI Codex CLI.
Initialize Git in your project repository.
For OpenAI Codex, enable skills by launching with codex --enable skills.

How it works

flowchart LR
  A[Start CLI session] --> B[Read name and description metadata]
  B --> C{"Does task match description?"}
  C -- Yes --> D[Load full SKILL.md into context]
  D --> E[Execute instructions and bundled scripts]
  C -- No --> F[Keep skill unloaded]

Step 1: Create the target skill directory

Claude Code resolves skills from .claude/skills/ locally or ~/.claude/skills/ globally. OpenAI Codex resolves skills from .codex/skills/ or .github/skills/ locally, and ~/.codex/skills/ globally. Create a directory whose folder name matches your skill identifier:

mkdir -p .claude/skills/git-release-tagger/references

Step 2: Write the SKILL.md specification

Create SKILL.md inside your skill folder. Define YAML frontmatter with a keyword-rich description so the model triggers activation reliably, followed by Markdown instructions for the CLI to run.

---
name: git-release-tagger
version: 1.0.0
description: Automates software release preparation. Use when the user asks to release, tag a version, generate release notes, or prepare a changelog.
compatibility: Claude Code, Codex CLI
---

# Git Release Tagger

## Instructions
1. Run `git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline` to inspect commits since the last tag.
2. Read `references/changelog-template.md` and format the commits under Features, Bug Fixes, and Maintenance.
3. Write the categorized output to `CHANGELOG.md`.
4. Ask the user for the release version, update `"version"` in `package.json`, and run:
   ```bash
   git add package.json CHANGELOG.md
   git commit -m "chore: release vVERSION"
   git tag vVERSION
   ```

Step 3: Add supporting reference templates

Isolate long documentation, formatting templates, or schemas into a references/ subdirectory. Keeping reference materials outside SKILL.md avoids loading unnecessary tokens during the activation step.

Write your format structure to references/changelog-template.md:

# Release vVERSION (DATE)

## Features
- List new features here

## Bug Fixes
- List bug fixes here

## Maintenance
- List chore and refactor changes here

Step 4 (optional): Generate skills automatically

Instead of writing skill directories manually, use built-in generation tools, community package managers, or slash commands.

To generate interactively inside Claude Code or Codex, prompt the built-in creator:

Use the skill-creator to help me build a skill for git releases.

To install community skills from the terminal, use skill-cli:

npm install -g @kotrotsos/skill-cli
skill install code-reviewer

To install native plugins directly inside Claude Code:

/plugin marketplace add anthropics/skills

Skills can also orchestrate Model Context Protocol (MCP) servers or connect through multi-CLI delegation plugins to hand off sub-tasks across tools.

Step 5: Automate skill creation with session review commands

Automate skill generation by configuring instructions in CLAUDE.md (Claude Code) or AGENTS.md (Codex), or prompting your LLM at the end of a session to review recent context. The agent inspects repetitive operations performed during the session, extracts the workflow logic, and packages it into a standard skill directory.

To ensure the generated skill is complete and functional, draft the prompt with four structural constraints:

Trigger specificity: Require a descriptive, keyword-rich description field in the frontmatter that defines exact invocation phrases so the skill does not trigger unexpectedly.
Deterministic instructions: Direct the LLM to output explicit shell commands, parameter flags, and file modifications in sequential order.
Resource isolation: Instruct the model to move templates, schemas, and extensive documentation into a references/ subfolder, keeping SKILL.md concise.
Directory parity: Explicitly mandate that the created directory matches the name field in the frontmatter.

Add the command prompt to your project CLAUDE.md (Claude Code) or AGENTS.md (Codex), or run it directly in your CLI at session wrap-up:

Review our current session. Identify any repetitive workflow we performed and generate a reusable skill:
1. Target directory: Create `.claude/skills/<name>/SKILL.md` where <name> matches the frontmatter name.
2. Frontmatter: Write YAML frontmatter with `name`, `version: 1.0.0`, and a trigger-focused `description` with exact keywords.
3. Instructions: Provide step-by-step imperative shell commands and file update steps.
4. References: Move large templates or schemas into `references/` so SKILL.md stays under 500 lines.

Step 6: Test the skill in a new session

CLIs index skill directories upon session initialization. Start a new session to register the updated folder, then prompt the agent using keywords specified in your frontmatter description:

claude "Prepare the release and tag the next version."

Common mistakes

Folder name mismatch. The parent directory name must match the name field in SKILL.md. A discrepancy causes skill validation to fail.
Vague frontmatter descriptions. If the description is generic, the agent will fail to activate the skill during task evaluation.
Incorrect filename casing. The specification requires SKILL.md in all capitals. Lowercase filenames are ignored on case-sensitive filesystems.
Inlining large references. Putting extensive manuals directly in SKILL.md bloats context windows on every activation. Store templates in references/.