Skip to content
How it learnsFrom coding sessions, reviews, Slack and docs.Only what fitsEach session gets the few rules its task needs.Pull request reviewEvery PR checked against your team’s rules.Keep it trueA gate, conflicts, disputes and stale rules, handled.HandoffsCarry the work to another session or a teammate.SecurityWhat it sends, what it changes and how to leave.
Engineering teamsOne agent or several: what one person learns, every session uses.PR review onlyInstall the GitHub App. Nothing on anyone’s machine.Teams that mix agentsClaude Code, Cursor, Codex and Copilot, the same rules.On your ownYour corrections follow you across repos, machines and agents.Book a call30 minutes with Roei, if you want a hand. Never required.
DocsPricingSign in
Connect your agents →
For teamsOn your ownPR review onlyHow it learnsOnly what fitsPull request reviewKeep it trueSecurityDocsPricingSign inConnect your agents →
Home/Blog

Blog

AGENTS.md, Cursor rules and Copilot instructions

  • AGENTS.md vs CLAUDE.md
  • Sync rules across repos
  • Why Codex ignores it
  • Keep rule files in sync
  • 3,905 files checked
  • Why Copilot ignores it
  • Cursor Team Rules
  • Cursor rules
  • copilot-instructions.md
  • Claude Code and AGENTS.md
  • AGENTS.md research

CLAUDE.md and context engineering

  • Why Claude ignores it
  • Test a CLAUDE.md rule
  • One CLAUDE.md for all projects
  • Context engineering, Claude 5
  • CLAUDE.md length
  • Which rules got used
  • Context rot, stale rules
  • Growing CLAUDE.md
  • Claude Code best practices
  • Karpathy CLAUDE.md
  • Committing CLAUDE.md

Built-in agent memory

  • Agent memory compared
  • Claude Code auto memory
  • GitHub Copilot Memory
  • Make Claude Code remember
  • Claude Tag vs Claude Code
  • Codex memories
  • Cursor memories
  • Memory or documentation?

Team knowledge and shared conventions

  • Claude Code team memory
  • Who owns CLAUDE.md
  • Claude Code second brain
  • Shared memory across agents
  • Stop repeated mistakes
  • Hand off between agents
  • Company brain
  • Slack decisions
  • Memory poisoning
  • Karpathy's LLM wiki
  • ADRs for agents

Skills, hooks and permissions

  • Rules vs skills
  • Claude Code hooks
  • Codex skills
  • Auto mode
  • CLAUDE.md vs skills vs hooks
  • Claude Code skills

AI code review and PR guardrails

  • PR review against AGENTS.md
  • Review comments to rules

Memory tools and alternatives

  • Best company brain tools
  • Unblocked alternatives
  • claude-mem alternatives
  • Supermemory alternatives
  • Mem0 alternatives
  • claude-mem
  • Best MCP memory servers
  • Supermemory Company Brain alternatives

Blog

Codex skills: SKILL.md, the .agents/skills folder, and $name

Published October 6, 2026 · Updated October 30, 2026

A Codex skill is a folder with a SKILL.md file. Codex lists your skills by name and description, and reads the full file only when a task matches or you type $name. It looks in .agents/skills from your folder up to the repository root. Claude Code does not read that folder, so a team on both needs one symlink per skill.

Facts about Codex are from OpenAI's skills docs and the Codex 0.160.1 source, read 2026-10-06. The ones marked tested were run on Codex 0.155.1 in a scratch repository.

What is a Codex skill?

A packaged, repeatable job: the steps, and any scripts or reference files they need. The folder holds a SKILL.md with two required fields, name and description, and can add scripts/, references/, assets/ and an agents/openai.yaml for Codex-only settings. Skills follow the Agent Skills open standard, so the format is the same one Claude Code, Cursor and Copilot read.

At the start of a session the model sees only a list: each skill's name, description and path. The list gets at most 2 percent of the model's context window, or 8,000 characters when the window is unknown. When there are more skills than fit, the docs say Codex “shortens skill descriptions first” and may leave some skills out. The full SKILL.md is read only when the skill is used.

Where does Codex look for skills?

ScopeFolderUse it for
Repository.agents/skills in every folder from where you start Codex up to the repository rootSkills the team checks in, per repo or per service
User~/.agents/skillsYour own skills, in every repo
Admin/etc/codex/skillsDefaults for every user of a machine or container
SystemBundled with Codexskill-creator, skill-installer and a few more

Four details decide whether a skill shows up. A skill in services/payments/.agents/skills is listed only when you start Codex in that service, not at the root (tested). Codex still reads the older ~/.codex/skills, and in our test also a project .codex/skills, which the docs do not list; do not build on that. Two skills with the same name are not merged, and both can appear. And unlike AGENTS.md, skills still load in a project marked untrusted (tested), which does not hold for AGENTS.md.

How do you write a SKILL.md for Codex?

A skill that adds a payments webhook handler:

.agents/skills/add-webhook-handler/
├── SKILL.md
└── scripts/
    └── scaffold.sh

---
name: add-webhook-handler
description: Scaffold a payments webhook handler with its job and test.
  Use when asked to handle a new webhook event.
---

1. Run scripts/scaffold.sh <event-name>.
2. Put the work in jobs/<event-name>.ts. The handler only checks
   the signature, enqueues the job and returns 200.
3. Run pnpm test payments.

The description does the routing, so say what the skill does and when to use it, in the words a request would use. Codex uses name and description and ignores keys it does not know, including Claude Code's. Keep the name lowercase with hyphens, at most 64 characters, and the same as the folder: Codex does not require the match, but the standard and Cursor do.

How do you run a skill in Codex?

Two ways. Codex picks a skill on its own when the task matches the description. Or you name it: type $ and the skill name, use /skills, or since 0.140.0 type @ for the menu of files, plugins and skills.

To keep Codex from choosing a skill by itself, set this in the skill's agents/openai.yaml:

policy:
  allow_implicit_invocation: false

That takes the skill off the list the model sees (tested). The docs say $name still works; open issue #23454 reports cases where it does not. To switch a skill off entirely, add a [[skills.config]] entry with its path and enabled = false to ~/.codex/config.toml, and restart Codex.

Can Codex, Claude Code and Cursor share one skills folder?

Not as one folder. Each tool reads its own list, and no folder is on all four lists:

ToolProject folders it readsRun one by name
OpenAI Codex.agents/skills$name, /skills, @
Claude Code.claude/skills only/name
Cursor.agents/skills, .cursor/skills, and for compatibility .claude/skills and .codex/skills/ in Agent chat
GitHub Copilot.github/skills, .claude/skills, .agents/skills/name in the CLI

Sources: Claude Code skills, Cursor skills, Copilot agent skills. Claude Code is the gap: the request to read .agents/skills, #31005, has been open since 2026-03-05 (an earlier one, #16345, was closed as its duplicate on 2026-10-22). Codex does not read .claude/skills (tested).

So keep the skills in .agents/skills and link each one into .claude/skills. Claude Code's docs say a skill folder can be a symlink, and Codex follows symlinks too:

mkdir -p .claude/skills
for s in .agents/skills/*/; do
  ln -s "../../$s" ".claude/skills/$(basename "$s")"
done

Two traps remain. Cursor and Copilot read both folders, so check that each skill shows up once. And the tools do not share their extra settings. Codex ignores Claude's disable-model-invocation: true, so a skill you hid from Claude's model is on Codex's list (tested); give it the agents/openai.yaml above as well. More on the Claude side in Claude Code skills.

Why won't my Codex skill trigger?

CauseCheckFix
Wrong folderIs it in .agents/skills on the path from your folder to the root?Move it, or start Codex where it lives
Description too vague or cutMany skills? Descriptions are shortened firstName the task and the trigger words in the first sentence
Implicit use is offallow_implicit_invocation in agents/openai.yamlCall it with $name
Disabled[[skills.config]] in ~/.codex/config.tomlRemove the entry and restart
Change not picked up/skillsRestart Codex

To see the list exactly as the model gets it, run codex debug prompt-input "hi" from your usual folder and search the output for the skill's name.

How should a team share Codex skills?

In the repository, in .agents/skills, reviewed like code. To distribute skills beyond one repository, OpenAI's docs say “prefer plugins”, and its openai/skills catalog has carried a deprecation notice since June pointing to the plugins repository. Keeping copies current is the open problem. In the Ask HN thread on managing skills files (320 points, September), one engineer put it as “The biggest problem is keeping skills up to date across users”.

Part of that problem is what goes into a skill. Look at step 2 of the example: “The handler only checks the signature, enqueues the job and returns 200.” That is not a step. It is a decision the team made in #eng-payments, copied into a skill. When the team changes it, every skill, AGENTS.md and prompt that carries a copy is wrong until someone finds it. A skill is the right home for how to do a job. What the team decided needs a home with an owner and a date.

Where Harbor fits

Harbor is that home for engineering decisions. It reads them where they are made, in Slack threads, pull request reviews and docs. A person approves each one, or a policy you set approves the routine ones, and Harbor serves the ones that apply to the task to Codex, Claude Code and Cursor at session start. A skill can then say “follow the team's webhook rule” and stay correct when the rule changes. Each rule shows how often it was served and how often an answer cited it; a cite is evidence that a rule was used, not proof that it was obeyed. The method is in served vs cited.

Related. Claude Code skills, why Codex ignores AGENTS.md, CLAUDE.md vs skills vs hooks, rules vs skills, and Codex memories.

Questions

Where does Codex look for skills?

In .agents/skills in every folder from where you start Codex up to the repository root, in ~/.agents/skills for your own skills, in /etc/codex/skills for a whole machine, and in the skills bundled with Codex. It still reads the older ~/.codex/skills.

How do I use a skill in Codex?

Codex picks a skill when the task matches its description, or you name it: type $ and the skill name, run /skills, or use the @ menu. Setting allow_implicit_invocation: false in the skill's agents/openai.yaml stops Codex choosing it on its own.

Does Claude Code read Codex skills?

Not from .agents/skills, the folder Codex uses; Claude Code reads .claude/skills. Keep skills in .agents/skills and symlink each skill folder into .claude/skills. Cursor and Copilot read both folders.

Why is my Codex skill not triggering?

Usually it sits in a folder Codex does not scan, such as .claude/skills or a service folder below where you started, its description is vague or was shortened because many skills share a small budget, or implicit use is turned off. Restart Codex if a change does not show up.

What is the difference between a Codex skill and AGENTS.md?

AGENTS.md is loaded at the start of every session. A skill is listed by name and description and read in full only when it is used. Put facts that are always true in AGENTS.md and repeatable jobs in skills, and keep each team decision in one place rather than copied into both.

More on Skills, hooks and permissions

  • Rules vs skills: Cursor, Claude Code, Copilot and Codex
  • Claude Code hooks: a practical guide with examples
  • Claude Code auto mode vs --dangerously-skip-permissions
  • CLAUDE.md vs skills vs hooks vs rules vs subagents

How Harbor reaches each agent →

Your team’s rules, in every agent, checked on every PR.

Harbor is shared memory for your team’s Claude Code, Cursor, Codex and Copilot. Free for you and one teammate. No card. No end date.

Start free →

Product

  • How it learns
  • Only what fits
  • Pull request review
  • Keep it true
  • Handoffs
  • The result
  • Security
  • For coding agents
  • Pricing

Developers

  • Docs
  • Quickstart
  • Install
  • CLI
  • MCP server
  • Served and cited
  • Rule-file checker
  • Blog

Guides

  • Why Claude ignores CLAUDE.md
  • AGENTS.md vs CLAUDE.md
  • Share Claude Code memory with a team
  • Why Codex ignores AGENTS.md
  • Why Cursor ignores rules
  • Copilot instructions vs AGENTS.md
  • Shared memory across agents
  • Copilot Memory and Dreaming

Compare

  • All comparisons
  • vs Mem0
  • vs Zep
  • vs Unblocked
  • vs ByteRover
  • vs Cognee
  • vs Hindsight
  • vs OpenViking
  • vs Supermemory
  • vs Glen
  • vs MemPalace
  • vs Sentra
  • vs Trail-code

Company

  • Questions
  • Contact
  • X
  • LinkedIn
  • Privacy Policy
  • Terms of Service
  • Data Processing Agreement
  • Refund Policy
© 2026 HarborConnect your agents