Claude Skills vs Codex Skills: What Should You Put Where?

The confusing part about AI skills is not the idea. The idea is simple: package a repeatable workflow so an AI agent can use it again.

The confusing part is where to put everything.

Should your code review checklist live in a Claude Skill, a Codex Skill, AGENTS.md, CLAUDE.md, Cursor rules, or GitHub Copilot custom instructions? Should SEO article formatting rules be a skill or a project instruction? Should a refactor process be a prompt or a reusable workflow?

The answer is not “Claude wins” or “Codex wins.” The better answer is workflow-based: different tools are better for different kinds of context.

OpenAI describes Codex skills as an authoring format for reusable workflows. Anthropic describes skills for Claude as folders of instructions, scripts, and resources that Claude loads dynamically for specialized tasks. Cursor also documents Agent Skills, Rules, MCP, and agent workflows, while GitHub Copilot uses custom instructions and prompt files for persistent guidance and reusable tasks.

This article compares Claude Skills vs Codex Skills and explains what should go where: skills, project instructions, repo rules, prompts, examples, scripts, and review checklists.

The Short Version

Use skills for repeated procedures.

Use project instructions for stable repository rules.

Use prompts for one-time tasks.

Use Cursor or Copilot when the workflow is mostly editor or IDE assistance rather than a full packaged skill.

A simple decision table:

Do not try to put everything into one file. The best setup separates stable facts from repeatable procedures.

What Is a Skill?

A skill is a packaged capability for an AI agent.

In practical terms, a skill usually contains:

• a SKILL.md file;
• instructions;
• a description that helps the agent know when to use it;
• examples;
• optional reference files;
• optional scripts;
• output rules;
• quality checks.

The goal is repeatability. Instead of telling the agent the same process every time, you save the process once and let the agent reuse it.

A skill is useful when the task has a stable procedure:

• review a code diff;
• write regression tests;
• audit an article;
• check SEO metadata;
• summarize a support ticket;
• prepare a weekly report;
• clean CRM records;
• audit a landing page.

A skill is not just a long prompt. A long prompt is still disposable. A skill is a reusable workflow asset.

Claude Skills: Where They Fit Best

Claude Skills are especially strong when the workflow benefits from instructions plus supporting files.

Anthropic’s skills materials describe a skill as a folder containing instructions, scripts, and resources that Claude can load for specific tasks or workflows. The official Anthropic skills repository describes skills as folders of instructions, scripts, and resources that Claude loads dynamically to improve specialized tasks.

Claude Skills are a good fit for:

• writing or reviewing documents;
• article editing;
• brand or style guide workflows;
• spreadsheet or data workflows;
• code review checklists;
• Claude Code task workflows;
• business process instructions;
• repeated analysis patterns;
• workflows with examples and templates.

A Claude Skill might look like this:

txtCopy
skills/
  article-review/
    SKILL.md
    resources/
      editorial-checklist.md
      seo-rules.md
    examples/
      strong-intro.md
      weak-intro.md

Claude Skills feel natural when the agent needs to load a small package of domain knowledge, examples, and process instructions.

Codex Skills: Where They Fit Best

Codex Skills are strongest when the repeated workflow is tied to coding work.

OpenAI’s Codex docs describe skills as the authoring format for reusable workflows, with plugins as the installable distribution unit for reusable skills and apps in Codex. The same Codex docs explain that Codex reads AGENTS.md files before doing work, giving it project-specific context.

Codex Skills are a good fit for:

• code review;
• refactoring;
• writing tests;
• PR descriptions;
• migration planning;
• article formatting in a code-based blog;
• lint/build validation workflows;
• repo-specific automation procedures;
• coding tasks that need repeatable steps.

A Codex Skill might look like this:

txtCopy
skills/
  code-review/
    SKILL.md
    resources/
      review-rubric.md
  write-tests/
    SKILL.md
    resources/
      testing-patterns.md
  article-seo-check/
    SKILL.md
    resources/
      metadata-checklist.md

Codex Skills are useful when you want the agent to follow the same engineering procedure every time: inspect files, plan, edit, run checks, summarize the diff, and list risks.

Claude Skill vs Codex Skill

The folder structure may look similar, but the workflow context is different.

The key distinction is not the file name. It is where the skill lives in your working process.

What Goes in AGENTS.md?

AGENTS.md should hold stable project guidance for coding agents.

Use it for:

• setup commands;
• build commands;
• test commands;
• repo map;
• code style;
• architecture rules;
• safety rules;
• high-risk folders;
• definition of done.

Example:

mdCopy
# AGENTS.md

## Commands
- Type check: npm run typecheck
- Lint: npm run lint
- Test: npm test
- Build: npm run build

## Rules
- Use strict TypeScript.
- Do not use `any` to hide errors.
- Do not edit auth, billing, migrations, CI, or deployment files unless asked.
- Add tests when business logic changes.

## Final response
Report files changed, checks run, risks, and manual verification needed.

AGENTS.md is not the place for a full code review checklist. It can mention that code review is required, but the detailed review process belongs in a skill.

What Goes in CLAUDE.md?

CLAUDE.md is useful for Claude Code project memory and project-specific guidance.

Use it for:

• how this repo works;
• commands Claude Code should know;
• safety boundaries;
• file areas requiring approval;
• links to deeper docs;
• reminders to plan before editing.

Example:

mdCopy
# CLAUDE.md

Read `AGENTS.md` before editing.
Use the commands listed there for validation.
Before making broad changes, propose a plan and wait for approval.
Do not edit `.env*`, auth, billing, migrations, or CI unless the task explicitly asks for it.

When reviewing article objects, follow the article formatting skill.

If both AGENTS.md and CLAUDE.md exist, avoid contradictions. Let one file be the source of truth and let the other reference it.

What Goes in a Skill?

A skill should describe a repeatable procedure.

Put these inside a skill:

• when to use it;
• step-by-step process;
• required inputs;
• examples;
• output format;
• quality rules;
• refusal or escalation rules;
• scripts or resources needed for the task;
• final checklist.

Do not put general repository facts inside every skill. A code review skill does not need the entire repo map. It can say: “Follow project rules from AGENTS.md.”

Example code review skill:

mdCopy
---
name: code-review
description: Review the current diff for bugs, missing tests, type safety issues, and risky files.
---

# Code Review Skill

## Process
1. Inspect changed files.
2. Identify the goal of the change.
3. Look for unrelated edits.
4. Check missing tests.
5. Check type safety.
6. Flag security-sensitive files.

## Output
Return findings by severity:
- blocker
- major
- minor
- question
- suggested test

Do not modify files unless asked.

That procedure can be used by Claude Code, Codex, or another skill-aware agent with small adjustments.

What Goes in Cursor Rules?

Cursor rules are useful for persistent editor/project behavior.

Cursor’s official docs describe Project, Team, and User Rules, plus AGENTS.md. Cursor also documents Agent Skills, MCP, and agent workflows.

Use Cursor rules for:

• coding style inside the editor;
• project-specific rules;
• file-glob-based guidance;
• team-wide conventions;
• reminders that should apply during everyday editing.

Example:

mdCopy
---
description: TypeScript project rules
globs:
  - "**/*.{ts,tsx}"
alwaysApply: true
---

Follow `AGENTS.md` for project commands and safety rules.
Do not loosen types with `any`.
Prefer existing components and utilities.
Keep diffs small and reviewable.

Use Cursor rules when the guidance should be active inside the editor across many small interactions. Use skills when the task has a full repeatable procedure.

What Goes in GitHub Copilot Instructions?

GitHub Copilot custom instructions are useful for repository-wide guidance inside GitHub and supported IDEs.

GitHub’s docs say repository custom instructions can be stored in .github/copilot-instructions.md, and Copilot can also use custom instructions and prompt files for reusable tasks in supported IDEs.

Use Copilot instructions for:

• repository conventions;
• build and test guidance;
• framework choices;
• style preferences;
• how Copilot should understand, build, test, and validate changes.

Example:

mdCopy
# GitHub Copilot Instructions

Follow `AGENTS.md` for project conventions.
Use strict TypeScript.
Do not add dependencies without explaining why.
Add tests for changed business logic.
Do not edit auth, billing, migrations, or CI unless the issue asks for it.

Use Copilot when your workflow is strongly tied to GitHub issues, pull requests, review, and multi-IDE team usage.

Decision Table: What Should You Put Where?

The goal is not to choose one universal file. The goal is to put each kind of context where it creates the least repetition and the least confusion.

Where Claude Code Is Better

Claude Code is a strong fit when you want an agent working closely with your local codebase and terminal workflow.

Claude Code is especially useful for:

• exploring a codebase;
• planning changes before editing;
• writing or editing across files;
• running commands and reading failures;
• using skills with instructions/resources/scripts;
• document and analysis-heavy workflows;
• workflows where Claude’s writing and reasoning quality matters.

Use Claude Skills when the task benefits from rich instructions, examples, and supporting resources.

Good Claude Skill candidates:

• article review;
• landing page audit;
• content style guide;
• technical documentation review;
• code review checklist;
• frontend QA process;
• business workflow analysis.

Claude Skills are often excellent for workflows that mix coding, writing, reasoning, and structured review.

Where Codex Is Better

Codex is a strong fit when the workflow is primarily coding-focused and needs repeatability inside a repository.

Use Codex Skills when the task is:

• code review;
• small-scope refactor;
• test generation;
• PR description;
• repo cleanup;
• migration planning;
• formatting a code-based blog object;
• running a repeated validation workflow.

Codex also pairs naturally with AGENTS.md, because project guidance can live in one predictable file and skills can focus on procedures.

A strong Codex setup looks like this:

txtCopy
AGENTS.md = project commands, repo map, rules, safety
skills/code-review/SKILL.md = review procedure
skills/write-tests/SKILL.md = test procedure
skills/article-seo-check/SKILL.md = editorial QA procedure
prompt = the specific task today

That separation makes the agent more predictable.

When Cursor or Copilot Is Enough

You do not always need a full skill system.

Cursor may be enough when:

• you want AI-native editor assistance;
• you need fast codebase navigation;
• project rules and agent chat cover the workflow;
• the task is local and interactive;
• a full packaged skill would be overkill.

GitHub Copilot may be enough when:

• the team already uses multiple IDEs;
• the workflow lives in GitHub issues and PRs;
• repository custom instructions provide enough guidance;
• prompt files cover repeated tasks;
• the organization prefers GitHub-native governance.

Do not build skills just to feel advanced. If rules and prompts are enough, keep the system simple.

How to Port a Workflow Between Tools

A good workflow can be moved between Claude, Codex, Cursor, and Copilot if you separate the stable parts.

Portable parts:

• task description;
• process steps;
• examples;
• output format;
• quality checklist;
• safety rules;
• test expectations.

Tool-specific parts:

• exact folder location;
• invocation syntax;
• project memory file name;
• plugin or extension packaging;
• CLI commands;
• IDE-specific rules;
• permission model.

A portable skill starts like this:

mdCopy
# Code Review Workflow

## Goal
Review the current diff for correctness, missing tests, type safety, and risky changes.

## Process
1. Inspect changed files.
2. Identify the intended behavior.
3. Compare diff against task requirements.
4. Check tests.
5. Flag risky files.
6. Return findings by severity.

## Output
- blocker
- major
- minor
- question
- suggested test

Then adapt the packaging for the tool you use: Claude Skill, Codex Skill, Cursor Skill, Copilot prompt file, or a plain Markdown checklist.

Limitations and Risks

Skills make agents more consistent, but they do not guarantee correctness.

Common risks:

• outdated skill resources;
• vague skill descriptions;
• duplicated instructions across tools;
• conflicting AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions;
• skills that are too broad;
• agents using a skill when a simple prompt would be better;
• no tests or review after the skill runs;
• false confidence because the process looks formal.

A bad skill can make the same mistake repeatedly. That is worse than a one-off bad prompt because the error becomes reusable.

Review skills like code. Keep them short, test them on real tasks, and delete or rewrite them when they stop matching the workflow.

Common Mistakes

Avoid these mistakes:

• putting project setup in every skill;
• putting full workflow checklists in AGENTS.md;
• creating separate conflicting rules for Claude, Codex, Cursor, and Copilot;
• using skills for rare one-time tasks;
• writing skills with no output format;
• letting agents edit high-risk files without approval;
• treating skills as a replacement for tests;
• accepting AI summaries without reviewing diffs.

The fix is simple: project facts go in project instructions, repeated procedures go in skills, and one-time requests stay as prompts.

A Practical Setup for a Developer Blog

For a code-based AI blog, a strong setup could be:

txtCopy
AGENTS.md
CLAUDE.md
.github/copilot-instructions.md
.cursor/rules/project.mdc
skills/
  article-review/
    SKILL.md
  article-seo-check/
    SKILL.md
  articles-ts-formatting/
    SKILL.md
  code-review/
    SKILL.md
  write-tests/
    SKILL.md
  landing-page-audit/
    SKILL.md

Use AGENTS.md for project structure, commands, and safety rules.

Use CLAUDE.md to tell Claude Code how to behave in this repo and where to find the main rules.

Use Copilot instructions if you use GitHub Copilot in your IDE or PR workflow.

Use Cursor rules if you use Cursor as your primary editor.

Use skills for repeated article, code, SEO, and QA workflows.

That setup gives each tool enough guidance without turning every prompt into a giant manual.

Final Recommendation

Start with the smallest system that solves your real workflow.

If you only use one tool, start there.

If you use Claude Code, create CLAUDE.md plus one skill for your most repeated workflow.

If you use Codex, create AGENTS.md plus one Codex Skill for code review or tests.

If you use Cursor, add project rules before building a large skill library.

If you use GitHub Copilot, add .github/copilot-instructions.md and consider prompt files for repeated tasks.

Then expand only after you see repeated friction.

The goal is not to have the most configuration. The goal is to make AI work repeatable without making the system confusing.

Conclusion: Put the Workflow Where It Belongs

Claude Skills and Codex Skills are both useful, but they are not the same as project instructions.

Skills are for repeatable procedures. AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions are for stable guidance. Prompts are for the specific task in front of you.

If you separate those layers, agents become easier to control:

txtCopy
Stable project facts → project instructions
Repeated task process → skill
One-time request → prompt
Tool-specific behavior → tool rules

That is the real answer to Claude Skills vs Codex Skills. Do not ask which one wins. Ask where the workflow belongs.