Where Are Codex Skills Stored Locally? AWS Agent Toolkit Path Guide

Codex skills are stored in ~/.codex/skills/ for global installations or .agents/skills/ for project-relative setups, as defined by the AWS Agent Toolkit directory mapping.

The AWS Agent Toolkit for AWS provides a standardized structure for managing agent-specific skills across your development environment. If you're configuring Codex and need to locate where these skill files reside on your local filesystem, the toolkit defines specific paths depending on whether you prefer a system-wide or repository-local installation. This guide details exactly where Codex skills are stored locally according to the official aws/agent-toolkit-for-aws source code.

Global vs. Project-Relative Storage Locations

The Agent Toolkit maintains a strict mapping between each supported coding agent and the directory where that agent expects to find its skills. For Codex, you have two distinct options for local storage.

Global Installation Path (~/.codex/skills/)

When installing skills globally, Codex expects to find them in the hidden folder ~/.codex/skills/ within your home directory. This directory is created automatically the first time you install a skill using the npx skills add command or when you manually copy skill files to this location. Using the global path makes your skills available across all projects on your local machine.

Repository-Local Path (.agents/skills/)

For project-specific skill management, Codex looks for skills in .agents/skills/ at the root of your repository. This hidden directory allows you to version-control your skill set alongside your application code, ensuring consistent tooling environments across different development machines and CI/CD pipelines. As documented in skills/README.md, this approach is ideal when you want skills committed with your repository rather than installed globally.

How Skills Are Installed

Skills reach these storage locations through two primary installation methods:

• CLI Installation: Running npx skills add <skill-name> automatically places files in the appropriate directory based on your configuration
• Manual Copy: You can manually copy skill directories (such as those found in skills/core-skills/aws-serverless) to either the global or project-relative location

According to the source documentation in skills/README.md, the toolkit handles the routing logic automatically when using the CLI, while manual installation requires you to choose between ~/.codex/skills/ and .agents/skills/ based on your scope requirements.

Locating Your Installed Skills

You can verify where your Codex skills are stored using command-line tools or Python scripts to inspect both potential locations.

Using Bash

List globally installed Codex skills:

ls "$HOME/.codex/skills"

List project-relative Codex skills:

ls .agents/skills

Using Python

Programmatically access both storage locations:

import pathlib

# Global path

global_path = pathlib.Path.home() / ".codex" / "skills"

# Project-relative path

project_path = pathlib.Path.cwd() / ".agents" / "skills"

print("Global Codex skills:", list(global_path.iterdir()))
print("Project Codex skills:", list(project_path.iterdir()))

Key Source File References

The path mappings and storage conventions are documented in several authoritative files within the repository:

• skills/README.md: Contains the complete agent-to-skill-directory mapping, showing Codex paths side-by-side with other supported agents
• README.md (repo root): Provides an overview of supported agents and mentions where Codex skills are located locally
• plugins/aws-core/README.md: Describes how the aws-core plugin bundles skills specifically for agents like Codex, including the expected directory structure

Summary

• Codex skills are stored locally in either ~/.codex/skills/ (global) or .agents/skills/ (project-relative) according to the Agent Toolkit mapping
• The global directory is created automatically on first use when running npx skills add or performing manual installation
• The project-relative path (.agents/skills/) enables version control of skill configurations alongside your repository code
• Official directory mappings are defined in skills/README.md within the aws/agent-toolkit-for-aws repository

Frequently Asked Questions

What is the default global path for Codex skills?

The default global path is ~/.codex/skills/, a hidden directory in your home folder. This location is standardized across the Agent Toolkit and is used when you install skills without the context of a specific repository, making them available system-wide.

Can I version-control Codex skills with my repository?

Yes, by placing skills in the .agents/skills/ directory at your repository root, you can commit them to version control alongside your source code. This ensures consistent skill definitions across team members and deployment environments.

How do I install a Codex skill locally?

You can install skills using the npx skills add <skill-name> command, which automatically routes files to the appropriate directory. Alternatively, manual installation involves copying skill directories (such as those from skills/core-skills/) to either ~/.codex/skills/ or .agents/skills/ depending on whether you want global or project-local access.

Where is the agent-to-directory mapping documented?

The authoritative mapping is documented in skills/README.md within the aws/agent-toolkit-for-aws repository. This file lists the expected local paths for all supported agents including Codex, showing both global (~/.codex/skills/) and project-relative (.agents/skills/) locations side-by-side for easy reference.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}