---

name: agent-skills-toolkit description: Create, link, and manage shared skills across Claude Code and OpenAI Codex. Use when creating new skills, adding shared skills, converting agent-specific skills to shared, or checking skill status. user-invocable: true

Agent Skills Toolkit

Unified skill management for Claude Code and OpenAI Codex.

Two Types of Skills

Type	Location	Scope	Use Case
Global	~/.agent-skills/	All projects	Utilities, patterns, reusable workflows
Project	<project>/.agent-skills/	Single project	PR reviews, deploy scripts, project-specific workflows

Architecture

Global Skills (user-wide)

Copied from source to agent directories (symlinks inside ~/.claude/skills/ are not followed by Claude Code).

~/.agent-skills/                    # SOURCE OF TRUTH
├── agent-skills-toolkit/
├── api-design-principles/
└── ...

~/.claude/skills/                   # COPIES (not symlinks)
├── agent-skills-toolkit/           # <- copied
├── api-design-principles/          # <- copied
└── keybindings-help/               # Claude-only (not shared)

~/.codex/skills/                    # COPIES (not symlinks)
├── agent-skills-toolkit/           # <- copied
├── api-design-principles/          # <- copied
└── swiftui-architecture/           # Codex-only (not shared)

After editing global skills: run sync-skills.py to copy changes.

Project Skills (per-project)

Copied from source to agent directories (same as global, for consistency).

my-project/
├── .agent-skills/                  # SOURCE OF TRUTH
│   ├── pr-review/
│   └── deploy-helper/
├── .claude/
│   └── skills/
│       ├── pr-review/              # <- copied
│       └── deploy-helper/          # <- copied
└── .codex/
    └── skills/
        ├── pr-review/              # <- copied
        └── deploy-helper/          # <- copied

After editing project skills: run sync-skills.py --project to copy changes.

Quick Start

Global skill (available everywhere)

# Create
~/.agent-skills/agent-skills-toolkit/scripts/create_skill.py my-skill --desc "Description"

# Edit ~/.agent-skills/my-skill/SKILL.md

# Sync to agents
python ~/.agent-skills/agent-skills-toolkit/scripts/sync-skills.py

# Restart agent session to see skill

Project skill (only in this project)

cd /path/to/project

# Create (sets up .agent-skills/ and copies to agents)
~/.agent-skills/agent-skills-toolkit/scripts/create_skill.py pr-review --project --desc "PR review for this repo"

# Edit .agent-skills/pr-review/SKILL.md

# Sync to agents
python ~/.agent-skills/agent-skills-toolkit/scripts/sync-skills.py --project

# Restart agent session in this project to see skill

Commands Reference

All scripts in ~/.agent-skills/agent-skills-toolkit/scripts/.

Create Skills

# Global skill (available in all projects)
create_skill.py <skill-name>
create_skill.py <skill-name> --desc "Description here"
create_skill.py <skill-name> --resources scripts,references

# Project skill (only in current project)
create_skill.py <skill-name> --project
create_skill.py <skill-name> --project --desc "Description"
create_skill.py <skill-name> --project --resources scripts

Options:

• --project — Create in ./.agent-skills/ instead of ~/.agent-skills/
• --desc — Skill description (important for triggering!)
• --resources — Create directories: scripts, references, assets
• --examples — Add placeholder files to resource dirs

Sync Management

After editing skills in source directories, run sync to copy changes to agent directories. On Windows, prefer the Python versions (below).

# Global skills
sync-skills.py              # Sync all global skills
sync-skills.py <skill-name> # Sync specific global skill
sync-skills.py --status     # Check global sync status

# Project skills
sync-skills.py --project              # Sync all project skills
sync-skills.py --project <skill-name> # Sync specific project skill
sync-skills.py --project --status     # Check project sync status

Important: Agents read skills at session start. After syncing, restart the agent session to see changes.

Other Commands

# List skills
list-skills.py              # List global skills
list-skills.py --project    # List project skills
list-skills.py --all        # List both global and project

# Remove shared skill from agents (keeps source)
unlink-skill.py <skill-name>

# Convert agent-specific to shared
share-skill.py codex <skill-name>
share-skill.py claude <skill-name>

When to Use What

Use Global Skills for:

• Reusable patterns (API design, code review checklists)
• Personal utilities (commit helpers, formatting)
• Skills you want in every project

Use Project Skills for:

• Repository-specific workflows (PR review for this repo)
• Deploy/release scripts tied to project
• Team-shared skills (commit .agent-skills/ to git)

Creating Skills Manually

Global Skill

# 1. Create directory
mkdir -p ~/.agent-skills/my-skill

# 2. Create SKILL.md
cat > ~/.agent-skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and WHEN to use it
user-invocable: true
---

# My Skill

Instructions for the agent...
EOF

# 3. Sync to agents
python ~/.agent-skills/agent-skills-toolkit/scripts/sync-skills.py my-skill

# 4. Restart agent session

Project Skill

cd /path/to/project

# 1. Create directory
mkdir -p .agent-skills/my-skill

# 2. Create SKILL.md (same format as global)
cat > .agent-skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and WHEN to use it
user-invocable: true
---

# My Skill

Instructions for the agent...
EOF

# 3. Sync to agents
python ~/.agent-skills/agent-skills-toolkit/scripts/sync-skills.py --project my-skill

# 4. Restart agent session in this project

Skill Locations Summary

Location	Role	Notes
~/.agent-skills/<skill>/	Global source	Edit here, then sync-skills.py
~/.claude/skills/<skill>/	Claude target	Copies from source (or Claude-only if created directly)
~/.codex/skills/<skill>/	Codex target	Copies from source (or Codex-only if created directly)
<project>/.agent-skills/<skill>/	Project source	Edit here, then sync-skills.py --project

Troubleshooting

Skill not visible after creation

1. Global skills: Run sync-skills.py, then restart agent
2. Project skills: Run sync-skills.py --project, then restart agent
3. Agents scan skills at session start — always restart after changes

Check sync status

# Global skills
sync-skills.py --status

# Project skills
sync-skills.py --project --status

Skill not in autocomplete

# Check if copied (not symlinked)
file ~/.claude/skills/<skill-name>
# Should say "directory", not "symbolic link"

# Re-sync if needed
sync-skills.py              # for global
sync-skills.py --project    # for project

Writing Good Skills

See references/ directory:

• best-practices.md — Core principles, what to include/avoid
• description-examples.md — How to write descriptions that trigger correctly
• structure-patterns.md — Workflow, Task, Reference patterns
• project-skill-example.md — Example of a project-level skill