Arsyn for Codex

Guide for using Arsyn with OpenAI Codex via native skill discovery.

Manual Installation

Prerequisites

• OpenAI Codex CLI
• Git

Steps

1. Clone the repo:

   git clone <your-arsyn-repo-url> ~/.codex/arsyn
   

2. Create the skills symlink:

   mkdir -p ~/.agents/skills
   ln -s ~/.codex/arsyn/skills ~/.agents/skills/arsyn
   

3. Restart Codex.

4. For subagent skills (optional): Skills like parallelizing and orchestrating require Codex's multi-agent feature. Add to your Codex config:

   [features]
   multi_agent = true
   

Windows

Use a junction instead of a symlink (works without Developer Mode):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\arsyn" "$env:USERPROFILE\.codex\arsyn\skills"

How It Works

Codex has native skill discovery — it scans ~/.agents/skills/ at startup, parses SKILL.md frontmatter, and loads skills on demand. Arsyn skills are made visible through a single symlink:

~/.agents/skills/arsyn/ → ~/.codex/arsyn/skills/

The bootstrapping skill is discovered automatically and enforces skill usage discipline — no additional configuration needed.

Usage

Skills are discovered automatically. Codex activates them when:

• You mention a skill by name (e.g., "use ideating")
• The task matches a skill's description
• The bootstrapping skill directs Codex to use one

Personal Skills

Create your own skills in ~/.agents/skills/:

mkdir -p ~/.agents/skills/my-skill

Create ~/.agents/skills/my-skill/SKILL.md:

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

The description field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.

Updating

cd ~/.codex/arsyn && git pull

Skills update instantly through the symlink.

Uninstalling

rm ~/.agents/skills/arsyn

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.agents\skills\arsyn"

Optionally delete the clone: rm -rf ~/.codex/arsyn (Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\arsyn").

Troubleshooting

Skills not showing up

1. Verify the symlink: ls -la ~/.agents/skills/arsyn
2. Check skills exist: ls ~/.codex/arsyn/skills
3. Restart Codex — skills are discovered at startup

Windows junction issues

Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator.