Creating Your First Skill

Introduction

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.

What Are Skills?

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.

Skills vs Slash Commands

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.

Where Skills Live

Skills are organized in your repository's .codex/ directory alongside your configuration: text .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.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Creating Your First Skill: Hello Skill

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:

Markdown

---
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?

---
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.

Breaking Down the Skill Structure

Every skill follows this consistent structure:

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

YAML

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

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:

Markdown

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

## 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:

Markdown

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

## 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:

Markdown

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

## 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:

Markdown

## 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

## 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):

Markdown

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

## 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:

You make a request: "Hello!"
Codex analyzes the intent behind your request
Codex checks if any skill triggers match the intent
If a match is found (hello skill), Codex follows that skill's procedure
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?

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.

Introduction

What Are Skills?

Skills vs Slash Commands

Where Skills Live

Join the 1M+ learners on CodeSignal

Creating Your First Skill: Hello Skill

Breaking Down the Skill Structure

How Skill Triggering Works

When to Create a Skill

Skill Creation Checklist

Testing Your Hello Skill

Summary