AI Skills With AI Agents: Codex Setup & Best Practices

Introduction

AI skills with AI agents are becoming one of the most useful ways to turn repeated prompting into reliable workflows.

Instead of explaining the same process every time, you package the workflow into a skill. The agent can then discover that skill, read its instructions, use any supporting scripts or references, and complete the task with a more consistent process.

For teams using agents like Codex, skills are especially practical. They can define how to write blog posts, review pull requests, generate reports, prepare release notes, migrate code, test a feature, or follow a company-specific engineering checklist.

This article explains what AI skills are, how to structure them, what each folder and file is for, and how to use them with an AI agent like Codex.

What Are AI Skills With AI Agents?

AI skills with AI agents are reusable workflow packages. A skill tells the agent when it should be used, what steps to follow, what inputs it needs, and what output it should produce.

In Codex, a skill is a directory that contains a required SKILL.md file and optional supporting folders such as scripts/, references/, assets/, and agents/.

The important idea is simple:

• Prompts are good for one-time instructions.
• Skills are better for repeatable work.
• Scripts are useful when a step must be deterministic.
• References are useful when the agent needs detailed supporting documentation.
• Assets are useful when the workflow depends on templates, examples, or media.

The best skills make the agent more reliable without filling the main prompt with too much context.

Why Skills Matter For Professional Teams

Professional teams do not only need smarter models. They need repeatable operating patterns.

An AI agent can be powerful, but if every user gives vague instructions in a different style, the output will vary. Skills reduce that variation by giving the agent a durable process.

Good skills help teams:

• Standardize recurring work.
• Reduce long prompts.
• Keep specialized instructions close to the project.
• Reuse scripts and templates.
• Improve review quality.
• Train agents on internal workflows without changing the model.
• Make agent behavior easier to audit.
• Share workflows across developers and repositories.

For example, a team might create one skill for WordPress blog formatting, another for pull request review, another for release notes, and another for test migration.

Recommended AI Skill Folder Structure

A professional AI skill should be small, focused, and easy for the agent to load only when needed.

.agents/└── skills/    └── blog-post-writer/        ├── SKILL.md        ├── references/        │   ├── style-guide.md        │   ├── shortcode-format.md        │   └── seo-checklist.md        ├── scripts/        │   ├── validate-shortcodes.js        │   └── generate-slug.js        ├── assets/        │   ├── featured-image-template.png        │   └── example-post.txt        └── agents/            └── openai.yaml

This structure gives the agent enough guidance to do serious work without turning every request into a long manual prompt.

What Each Folder And File Does

`.agents/skills/`

This is the repository-level location where Codex can discover skills for a project. Skills placed here can be shared with the team through the codebase.

Use this location when a skill is specific to a project, product, repository, or team workflow.

`blog-post-writer/`

This is the skill folder. Each skill should have a focused job. The folder name should be clear enough that humans understand what it does.

Good examples:

• blog-post-writer
• pull-request-reviewer
• release-notes-generator
• api-migration-helper
• qa-checklist-runner

Avoid broad names like productivity, helper, or general-ai. Broad skills are harder for agents to choose correctly.

`SKILL.md`

SKILL.md is the required file. It contains metadata and instructions.

The metadata tells the agent the skill name and when to use it. The body tells the agent how to perform the workflow.

1---2name: blog-post-writer3description: Use when creating, rewriting, or formatting CodeHills blog posts with SEO metadata, shortcode structure, file structure blocks, and final paste-ready content.4---5 6# Blog Post Writer7 8Goal:9 10Create professional, SEO-optimized blog posts in the CodeHills shortcode format.11 12Inputs to gather:13 14- Topic15- Audience16- Primary keyword17- Secondary keywords18- Search intent19- Category20- Featured image URL or image prompt21- Any source links22 23Workflow:24 251. Identify the primary keyword and search intent.262. Draft a practical article for founders, operators, and technical decision-makers.273. Use descriptive `##` headings for the table of contents.284. Add supported shortcode blocks only when they improve the article.295. Validate that every opened shortcode is closed correctly.306. Return the final content ready to paste into WordPress.31 32Output:33 34Return only the final shortcode content unless the user asks for explanation.

The description is especially important because Codex can use it to decide whether the skill matches a task.

`references/`

The references/ folder stores supporting documents that the agent should read only when needed.

Use it for:

• Style guides.
• API notes.
• Shortcode rules.
• Brand voice examples.
• Compliance requirements.
• Architecture notes.
• Testing policies.
• Known edge cases.

This keeps the main SKILL.md small while still giving the agent access to deeper context.

`scripts/`

The scripts/ folder stores executable helpers.

Use scripts when a step must be reliable and repeatable. For example, a blog-writing skill might include a script that checks whether shortcodes are balanced. A migration skill might include a script that scans deprecated API calls.

Good script use cases:

• Validate output format.
• Generate slugs.
• Parse structured data.
• Run deterministic checks.
• Convert files.
• Produce reports.
• Compare expected and actual output.

Do not add scripts just to make the skill look advanced. If instructions are enough, keep the skill instruction-only.

`assets/`

The assets/ folder stores reusable materials.

Use it for:

• Templates.
• Example outputs.
• Design references.
• Image placeholders.
• CSV examples.
• Prompt examples.
• Brand files.

For a blog skill, assets/example-post.txt can show the agent what a finished article should look like. For a presentation skill, assets might include slide examples, logos, or visual references.

`agents/openai.yaml`

The optional agents/openai.yaml file can configure Codex app metadata and invocation behavior.

It can define details such as display name, short description, icons, brand color, default prompt, invocation policy, and tool dependencies.

For example, a skill that depends on an OpenAI docs MCP server can declare that dependency so the interface can present it more clearly.

1interface:2  display_name: "Blog Post Writer"3  short_description: "Create SEO-ready CodeHills blog shortcode content."4  icon_small: "./assets/icon-small.svg"5  icon_large: "./assets/icon-large.png"6  brand_color: "#2563EB"7  default_prompt: "Write a CodeHills blog post using this skill."8 9policy:10  allow_implicit_invocation: true11 12dependencies:13  tools:14    - type: "mcp"15      value: "openaiDeveloperDocs"16      description: "Official OpenAI Docs MCP server"17      transport: "streamable_http"18      url: "https://developers.openai.com/mcp"

This file is optional. Start with SKILL.md; add agents/openai.yaml when you need better app presentation, tool dependencies, or invocation policy.

Where Codex Looks For Skills

Codex can read skills from several locations. The most common project-level location is .agents/skills/.

Use repository skills when the workflow belongs to a project:

my-product/├── .agents/│   └── skills/│       ├── api-reviewer/│       │   └── SKILL.md│       └── release-notes/│           └── SKILL.md├── AGENTS.md└── src/    └── index.ts

Use personal skills when the workflow belongs to a developer across many repositories:

$HOME/└── .agents/    └── skills/        ├── personal-research-assistant/        │   └── SKILL.md        └── weekly-status-writer/            └── SKILL.md

Use repository skills for team standards. Use user skills for personal productivity.

How Codex Uses A Skill

Codex can use a skill in two main ways.

First, the user can invoke it explicitly. In Codex CLI or IDE workflows, users can mention a skill directly, use /skills, or type $ to select one.

Second, Codex can invoke it implicitly. If the user asks for something that matches the skill description, Codex can decide to load that skill.

That is why the skill description matters. It should clearly say when the skill should trigger and what it should not be used for.

For example:

1description: Use when writing or formatting CodeHills WordPress blog posts with shortcode blocks, SEO metadata, source cards, command blocks, code blocks, and file-structure sections. Do not use for generic website copy or unrelated WordPress theme development.

This description is better than:

1description: Helps with writing.

The strong version gives Codex enough signal to choose the skill correctly.

How To Create A Skill Manually

You can create a skill manually by adding a folder and a SKILL.md file.

$mkdir -p .agents/skills/blog-post-writer/references$mkdir -p .agents/skills/blog-post-writer/scripts$mkdir -p .agents/skills/blog-post-writer/assets$mkdir -p .agents/skills/blog-post-writer/agents$touch .agents/skills/blog-post-writer/SKILL.md

Then write the metadata and instructions in SKILL.md.

1---2name: blog-post-writer3description: Use when writing SEO-optimized CodeHills blog posts in the required shortcode format.4---5 6# Blog Post Writer7 8Goal:9 10Create paste-ready CodeHills blog shortcode content.11 12Workflow:13 141. Gather topic, audience, keyword, search intent, category, sources, and media details.152. Draft a practical article with useful examples.163. Use CodeHills-supported shortcodes only.174. Validate shortcode closure and SEO keyword placement.185. Return the final content in a file when requested.

Codex can detect skill changes automatically in many cases. If the new skill does not appear, restart Codex.

How To Use The Skill With Codex

Once the skill exists, you can use it with a direct prompt.

$codex "Use the blog-post-writer skill to create a blog about AI workflow automation for SaaS teams."

In the Codex app or IDE extension, you can also mention the skill by name when writing the request:

1Use the blog-post-writer skill.2 3Topic: Creating AI skills with AI agents4Audience: founders, operators, and technical decision-makers5Primary keyword: AI skills with AI agents6Include: folder structure, SKILL.md example, how to use with Codex, and best practices7Output: write the final shortcode content into a file

Codex will first see the skill name, description, and file path. When the task matches, it loads the full SKILL.md and follows the workflow.

AI Skills vs AGENTS.md

Skills and AGENTS.md files solve related but different problems.

Use AGENTS.md for broad project guidance:

• How to run tests.
• Which package manager to use.
• Coding style.
• Pull request expectations.
• Project setup notes.
• Security rules.

Use skills for repeatable task workflows:

• Write a CodeHills blog post.
• Review a pull request.
• Generate release notes.
• Migrate an API integration.
• Analyze a CSV file.
• Create a customer support summary.

In Codex, AGENTS.md gives the agent project context before work begins. A skill gives the agent a specialized workflow when a particular task needs it.

Example: A Skill For Pull Request Review

A professional engineering team might create a pull request review skill.

.agents/└── skills/    └── pull-request-reviewer/        ├── SKILL.md        ├── references/        │   ├── review-policy.md        │   └── security-checklist.md        └── scripts/            ├── changed-files-summary.js            └── risk-score.js

The SKILL.md might instruct the agent to:

• Read the changed files.
• Identify behavior changes.
• Prioritize bugs, regressions, and missing tests.
• Check security-sensitive code carefully.
• Avoid summarizing before listing findings.
• Cite file paths and line numbers.
• Run available tests when possible.
• Return a concise review with severity levels.

This skill improves consistency. Every review follows the same pattern, even when different developers invoke the agent.

Example: A Skill For Blog Writing

A marketing or engineering content team might create a blog-writing skill.

.agents/└── skills/    └── codehills-blog-writing/        ├── SKILL.md        ├── references/        │   ├── shortcode-format.md        │   ├── seo-rules.md        │   └── brand-voice.md        └── assets/            └── example-post.txt

This skill can define:

• The required WordPress shortcode wrapper.
• SEO metadata rules.
• Supported inner shortcodes.
• Heading structure.
• Voice and audience.
• Final output checks.
• Image prompt rules.

That turns blog creation from an ad hoc prompt into a repeatable publishing workflow.

Best Practices For Creating AI Skills

Good AI skills are specific, readable, and testable.

Follow these principles:

• Keep one skill focused on one job.
• Put the most important trigger words in the description.
• Write clear imperative steps.
• Define required inputs and expected outputs.
• Keep SKILL.md concise.
• Move long references into references/.
• Use scripts only when deterministic checks are valuable.
• Include examples when output format matters.
• Avoid broad "do everything" skills.
• Test the skill with realistic prompts.
• Update skills when the team's process changes.

The best skill feels like a trusted internal playbook, not a pile of vague suggestions.

Common Mistakes To Avoid

The most common mistake is making the skill too broad.

If a skill says it helps with "engineering work," the agent has little signal about when to use it. A better skill says it helps with "reviewing React pull requests for regressions, missing tests, accessibility issues, and state-management bugs."

Avoid these mistakes:

• Writing a vague description.
• Putting too much content directly in SKILL.md.
• Hiding required steps in long reference files.
• Adding scripts before they are needed.
• Forgetting to define the output format.
• Creating many overlapping skills with the same trigger words.
• Not testing whether Codex chooses the right skill.
• Treating skills as a replacement for human review.

Skills should reduce ambiguity. If a skill makes the agent less predictable, simplify it.

Practical Workflow For Teams

Here is a simple rollout plan for using AI skills with AI agents like Codex:

1. Pick one repeated workflow.
2. Write the manual process in plain language.
3. Turn that process into SKILL.md.
4. Add references only when the agent needs them.
5. Add scripts only for deterministic checks.
6. Test the skill with three realistic prompts.
7. Ask Codex to explain when it would use the skill.
8. Commit the skill into .agents/skills/.
9. Let the team use it for one week.
10. Refine the description, workflow, and examples based on real output.

Start small. A focused skill that handles one workflow well is more valuable than a large skill that tries to cover every possible task.

Conclusion

AI skills with AI agents help teams move from repeated prompting to reusable workflows.

For Codex, a skill is a practical package: SKILL.md for instructions and metadata, optional references/ for deeper documentation, optional scripts/ for deterministic helpers, optional assets/ for templates, and optional agents/openai.yaml for app metadata and dependencies.

Use AGENTS.md for broad project instructions. Use skills for specific repeatable workflows. Keep each skill focused, test it with real prompts, and refine it as your process matures.

Done well, skills make AI agents more useful because they teach the agent how your team actually works.

Useful References