Creating Your First Skill

Welcome to Codex Skill Engineering! In the previous course, you learned how to configure Codex using config.toml - setting up your model preferences, managing context, and defining your project structure. Now we're taking it to the next level by teaching Codex specialized procedures called skills.

Skills help Codex behave consistently for repeatable tasks in your repository. Think of skills as teaching Codex domain-specific expertise that it can apply autonomously whenever the situation calls for it.

Skills are reusable, structured procedures written in Markdown that teach Codex how to perform specific tasks. Unlike the general configuration you set in config.toml, skills define task-specific behaviors - they're like expert recipes that Codex can follow when it detects certain patterns in your requests.

A skill defines:

• When to activate (trigger patterns)
• What role to assume (persona and expertise)
• What steps to follow (systematic procedure)
• What format to output (structure and constraints)

The key difference from what you've learned before: skills enable autonomous activation. Codex doesn't need to be told "use this skill" - it recognizes when a skill applies and invokes it automatically.

You might be wondering: "How is this different from using slash commands?" Here is the distinction:

Slash commands (like /edit or /test):

• Manually invoked by you
• User-directed - you choose when to use them
• General-purpose operations

Skills:

• Automatically triggered by Codex
• Intent-based - Codex detects when they're needed
• Specialized procedures for specific tasks

For example, if you type "How is this repo organized?", Codex can automatically recognize this matches a repository analysis skill and invoke it without you needing to run a manual command first. Skills make Codex proactive, not just reactive.

Skills are organized in your repository's .codex/ directory alongside your configuration:

.codex/
  config.toml          # Global configuration (you know this!)
  skills/
    hello/
      SKILL.md         # Hello skill definition
    repo-navigator/
      SKILL.md         # Repo navigator skill

Each skill gets its own directory with a SKILL.md file. This organization keeps skills modular, version-controllable, and easy to share across projects.

Let's build a minimal skill to understand the structure. We'll create a "Hello Skill" that introduces Codex whenever a user greets it or asks what it can do.

Create a file at .codex/skills/hello/SKILL.md:

---
name: hello
description: Introduces Codex and explains its capabilities in this repository
trigger: When the user greets Codex or asks what it can do (e.g., "hello", "introduce yourself", "what can you do?")
---

# Hello Skill

## Role
You are a friendly AI assistant introducing yourself to a new user.

## Task
Provide a warm welcome and explain your core capabilities.

## Constraints
- Keep the response concise (under 100 words total)
- Don't mention internal repo details unless asked.

## Output Format
Use a conversational tone with the following structure:
1. Greeting
2. Brief self-introduction
3. List 3 main things you can help with
4. Invitation to ask questions

## Examples
Hello! I'm Codex, your AI pair programming assistant. I'm here to help you navigate this codebase, write and review code, and answer questions about the project. I can assist with debugging, documentation, testing, and architectural discussions. What would you like to work on today?

That's it! This is a complete, working skill that Codex will automatically use when it detects a greeting.

Every skill follows this consistent structure:

1. Metadata Header (YAML front matter between ---):

name: hello
description: Brief summary of what the skill does
trigger: Intent pattern with example phrases

The trigger is crucial - it defines the intent patterns that activate this skill. Notice we provide concrete examples like "hello", "introduce yourself", "what can you do?" This helps Codex understand when to use the skill.

2. Role Section:

## Role
You are a friendly AI assistant introducing yourself to a new user.

Establishes the persona Codex should adopt. The role shapes how Codex approaches the task - an "analyst" behaves differently than a "friendly assistant."

3. Task Section:

## Task
Provide a warm welcome and explain your core capabilities.

Defines the concrete, measurable objective. This should be specific enough that you can verify if it's complete.

4. Constraints Section:

## Constraints
- Keep the response concise (under 100 words total)
- Don't mention internal repo details unless asked.

Sets boundaries for the AI. This is vital for safety and honesty—it tells Codex what not to do or sets hard limits on length and scope.

5. Output Format Section:

## Output Format
Use a conversational tone with the following structure:
1. Greeting
2. Brief self-introduction
3. List 3 main things you can help with
4. Invitation to ask questions

Specifies exactly how the output should be structured. This ensures consistency across invocations.

6. Examples Section (optional but powerful):

## Examples
[Sample output showing exactly what good looks like]

Provides a reference implementation. This is one of the most effective ways to guide Codex's behavior.

When you interact with Codex, here's what happens:

1. You make a request: "Hello!"
2. Codex analyzes the intent behind your request
3. Codex checks if any skill triggers match the intent
4. If a match is found (hello skill), Codex follows that skill's procedure
5. If no match, Codex uses its general capabilities

This means skills augment Codex without limiting it. They add specialized expertise while keeping general functionality available.

Create a skill when you have a task that is:

• Repeatable - You'll need to do it multiple times
• Procedural - It has clear, defined steps
• Context-specific - It's relevant to your project or domain
• Worth automating - Manual execution is tedious or error-prone

Examples of good skill candidates:

• Analyzing repository structure
• Checking code style compliance
• Generating documentation from code
• Reviewing PRs for common issues
• Setting up new project components

Examples of what NOT to make a skill:

• One-off questions about code
• Exploratory conversations
• Tasks that change constantly
• General knowledge questions

When building your own skills, ensure they have:

✅ Clear trigger - Intent-based pattern with concrete example phrases

✅ Focused role - Appropriate persona for the specific task

✅ Measurable task - Objectives you can verify were completed

✅ Constraints - Boundaries to ensure safe, focused output

✅ Explicit output format - Structure that's clearly defined

✅ Examples - Reference implementations showing good output

Following this checklist ensures your skills are reliable and maintainable.

Once you've created the skill file, try it out! Simply start a conversation with Codex:

You: Hello!

Codex: Hello! I'm Codex, your AI pair programming assistant. I'm here to help you navigate this codebase, write and review code, and answer questions about the project. I can assist with debugging, documentation, testing, and architectural discussions. What would you like to work on today?

Notice how Codex automatically recognized the greeting and followed the skill's structure. No slash commands needed!

In this lesson, you explored how to extend Codex's capabilities using skills. Skills are specialized, markdown-based procedures stored in your repository's .codex/skills/ directory that define task-specific behaviors. Unlike slash commands which require manual invocation, skills allow Codex to proactively detect intents and trigger automatically based on the patterns you define. We walked through creating a complete SKILL.md file, breaking down essential components like the YAML metadata header, specific roles, tasks, constraints, and output formats. Finally, we established that skills are best used for repeatable, procedural tasks that benefit from strict consistency, allowing you to automate expert workflows within your codebase.