Skills in OpenAI Codex: Writing Prompts as Code with Markdown and Frontmatter

Mar 27, 2026

I used to write prompts in chat interfaces. They were scattered, unversioned, and hard to share with my team. Then I discovered OpenAI Codex Skills—prompts written as code.

This changed how I think about prompt engineering.

What Are Skills?

Skills are workflow prompts written in Markdown with YAML frontmatter. They live in directories, get version-controlled, and can be packaged for distribution.

Think of them as functions for AI interactions. I write them once, test them, and reuse them across projects.

The Structure

A Skill has two parts: frontmatter (metadata) and body (the prompt itself).

skill-name/
├── skill.md          # Markdown + frontmatter
└── related-files/    # Optional supporting files

The frontmatter tells Codex when to use the Skill. The body tells it what to do.

Writing the Frontmatter

The frontmatter is YAML at the top of the file. Here’s what I include:

---
name: generate-api-tests
description: Generate comprehensive API test suites from OpenAPI specs
triggers:
  - openapi
  - api-testing
  - test-generation
version: 1.2.0
---

Key fields:

name: Identifier for the Skill
description: Critical—this determines if Codex finds your Skill at the right time
triggers: Keywords that activate the Skill
version: Track changes like any other code

The description matters more than the prompt itself. Codex uses progressive discovery—it searches Skills by description quality, not just by trigger words.

Writing the Prompt Body

After the frontmatter, I write the actual prompt in Markdown. I keep it structured and explicit.

# Generate API Tests

You are a test generation specialist. When given an OpenAPI specification:

1. Parse all endpoints and their parameters
2. Generate positive and negative test cases
3. Include edge cases for boundary values
4. Output in the project's test framework format

## Example Output Format

Use this structure for the generated tests.

I use headers to organize sections. Numbered lists make steps clear. Examples show expected output.

A Complete Example

Here’s a full Skill I use for code review:

---
name: review-code
description: Review code for security issues, performance problems, and best practices
triggers:
  - code-review
  - review
  - security
version: 1.0.0
---

# Code Review

You are a senior code reviewer. Analyze the provided code for:

## Security

- SQL injection vulnerabilities
- XSS risks
- Hardcoded secrets
- Authentication issues

## Performance

- Unnecessary loops
- Memory leaks
- Inefficient algorithms

## Best Practices

- Naming conventions
- Code organization
- Error handling

## Output Format

Provide findings in this structure:

1. **Critical**: Must fix before merge
2. **Warning**: Should address
3. **Suggestion**: Consider improving

Why This Matters

Before Skills, my prompts lived in chat history. I’d copy-paste the same instructions repeatedly. Version control meant saving text files with names like prompt_v2_final_real.txt.

Now prompts are first-class code artifacts.

I can:

Review changes in pull requests
Roll back to previous versions
Share Skills across my team
Package them as plugins

This is prompt engineering as software engineering.

Getting Started

Create a .codex/skills/ directory in your project
Add a skill.md file with frontmatter and prompt
Write a clear description—this is your discovery mechanism
Test it with Codex
Iterate and version

The paradigm shift is simple: treat prompts like code, and you get all the benefits of code.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 OpenAI Codex Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!