# Quick Start: Codex Skills

Canonical page: https://www.kuudo.com/docs/quick-start/codex-skills/

Install Codex skills when you want Codex to follow a reusable workflow, load task-specific instructions, or bring supporting scripts and references into a session.

For the official reference, see [Agent Skills in the OpenAI Codex docs](https://learn.chatgpt.com/docs/build-skills).

## What a skill is

A skill is a folder with a required `SKILL.md` file and optional supporting files:

```text
my-skill/
  SKILL.md
  scripts/
  references/
  assets/
  agents/
    openai.yaml
```

`SKILL.md` contains the skill metadata and instructions. It must include `name` and `description` frontmatter so Codex can decide when to use it.

```markdown
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.
```

Codex uses progressive disclosure for skills. It starts with each skill's name, description, and file path, then reads the full `SKILL.md` only when the skill is selected.

## Install curated skills

For local setup and experimentation, use the built-in installer from a Codex session:

```text
$skill-installer linear
```

You can also ask `$skill-installer` to install skills from another repository:

```text
$skill-installer install a skill from github.com/{owner}/{repo}
```

Codex detects newly installed skills automatically. If a skill does not appear, restart Codex.

## Install a repo skill

Use repo-scoped skills when the workflow belongs with the codebase and should be shared by the team.

Create the folder under the repository root:

```text
.agents/skills/my-skill/SKILL.md
```

Example:

```bash
mkdir -p .agents/skills/release-checklist
```

Then add `.agents/skills/release-checklist/SKILL.md`:

```markdown
---
name: release-checklist
description: Use when preparing a release branch, verifying changelog entries, and checking release gates.
---

Follow the repository release checklist before marking a release ready.
```

Codex scans `.agents/skills` from the current working directory up to the repository root, so nested projects can have local skills while the root can provide shared team skills.

## Install a user skill

Use user-scoped skills for personal workflows that should be available across repositories.

```text
$HOME/.agents/skills/my-skill/SKILL.md
```

Example:

```bash
mkdir -p ~/.agents/skills/personal-review
```

Then add `~/.agents/skills/personal-review/SKILL.md`.

## Admin and system skills

Codex also reads admin and system-level skills:

| Scope | Location | Use |
| --- | --- | --- |
| Repo | `$REPO_ROOT/.agents/skills` | Team or project workflows checked into a repository. |
| User | `$HOME/.agents/skills` | Personal workflows available across repositories. |
| Admin | `/etc/codex/skills` | Shared machine or container defaults. |
| System | Bundled with Codex | OpenAI-provided default skills. |

Codex supports symlinked skill folders and follows the symlink target when scanning skill locations.

## Enable or disable a skill

Disable a skill without deleting it by adding a `[[skills.config]]` entry to `~/.codex/config.toml`:

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

Restart Codex after changing `~/.codex/config.toml`.

## Optional app metadata

Add `agents/openai.yaml` when you want Codex app metadata, invocation policy, or declared tool dependencies:

```yaml
interface:
  display_name: "Release Checklist"
  short_description: "Release readiness workflow"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Run the release checklist."

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "private-mcp"
      description: "Private MCP server"
      transport: "streamable_http"
      url: "https://{your-private-mcp-host}/mcp"
```

Set `allow_implicit_invocation: false` when the skill should only run after an explicit `$skill-name` mention.

## Skills vs plugins

Use direct skill folders for local authoring, repo-scoped workflows, and personal setup.

Use plugins when you want to distribute reusable skills, bundle multiple skills together, or ship skills alongside app mappings, MCP server configuration, or presentation assets.

## Verify installation

In Codex CLI or the IDE extension:

1. Run `/skills` or type `$` to open the skill selector.
2. Confirm the new skill appears by name.
3. Invoke it directly with `$skill-name`.
4. If it does not appear, restart Codex and check the skill path.

For skills that depend on MCP tools, verify the MCP server separately with `/mcp`. See the [Codex MCP quick start](/docs/quick-start/codex/) for MCP setup.