bug: Codex target does not declare an agents path

[Bongseop-Kim]

Summary

The built-in codex target declares a skills path but no agents path, so Codex is omitted from agent sync/status even though skillshare v0.19 supports first-class agent management.

Current behavior

With a global config that includes both Claude and Codex targets, skillshare target list --json reports an agentPath for Claude but not for Codex:

{
  "name": "claude",
  "path": "/Users/duegosystem/.claude/skills",
  "agentPath": "/Users/duegosystem/.claude/agents"
}

{
  "name": "codex",
  "path": "/Users/duegosystem/.codex/skills"
}

As a result, skillshare status --json lists only Claude under agents.targets, and skillshare target codex --agent-mode merge fails with:

target 'codex' does not have an agents path

Expected behavior

Codex should appear as an agent-capable target when syncing agents, just like Claude and other supported agent targets.

For global mode, adding this explicit config makes it work locally:

targets:
  codex:
    skills:
      path: /Users/duegosystem/.codex/skills
    agents:
      path: /Users/duegosystem/.codex/agents

After that, skillshare target list --json includes:

{
  "name": "codex",
  "path": "/Users/duegosystem/.codex/skills",
  "agentPath": "/Users/duegosystem/.codex/agents",
  "agentMode": "merge",
  "agentSync": "no source agents yet"
}

and skillshare sync agents creates/syncs ~/.codex/agents as expected.

Likely root cause

The embedded built-in target registry appears to define Codex with skills only:

- name: codex
  skills:
    global: "~/.codex/skills"
    project: ".agents/skills"

while Claude declares both skills and agents:

- name: claude
  skills:
    global: "~/.claude/skills"
    project: ".claude/skills"
  agents:
    global: "~/.claude/agents"
    project: ".claude/agents"

Prior art checked

I found related agent/plugin discussions, but not this exact target-registry omission:

• feat: first-class agent support #98 added first-class agent support.
• Feature: adopt/claim workflow for CLI-bundled skills (~/.agents convention) #135 discusses adopting CLI-bundled skills under the ~/.agents convention.
• Add plugin support as a first-class resource type #133 discusses first-class plugin support.
• Add command/prompt sync presets for Claude Code, Cursor, and Codex #146 discusses command/prompt sync presets for Claude/Cursor/Codex.

This issue is narrower: Codex is already a built-in skills target, but it is missing an agents: path, so agent sync skips it.

Environment

skillshare version: 0.19.23
OS: macOS arm64

Open question

agents.global: "~/.codex/agents" works locally. I am less sure what the canonical Codex project-mode agent path should be, so it may be worth confirming before adding agents.project.

[runkids]

Thanks for the thorough write-up. The missing agents path on the codex target is actually intentional rather than an oversight.

skillshare's agent sync works by symlinking agent files into the target's agents directory, and our agent format is Claude-style Markdown. But per the Codex docs you linked (https://developers.openai.com/codex/subagents), Codex subagents are standalone TOML files with required fields name, description, and developer_instructions (plus optional model, sandbox_mode, mcp_servers, etc.).

So if we simply added ~/.codex/agents as an agent target, skillshare would symlink Markdown files into a directory where Codex only loads TOML — Codex wouldn't be able to parse them. The workaround you found "works" only in the sense that the directory gets created; any agents synced there wouldn't actually be valid Codex agents.

Proper Codex agent support needs a Markdown → TOML conversion step (mapping our agent frontmatter/body to Codex's name / description / developer_instructions schema), which is a larger piece of work than a registry path entry. I'll track that as a separate feature rather than a quick path fix, and leave this open as the canonical request for it.

[runkids]

Update for anyone landing here: the Markdown → TOML conversion I mentioned above now exists as of v0.20.0, via the extras extension transforms. A bundled codex-agents transform maps our agent format to Codex's subagent schema:

• frontmatter name (falls back to filename) → name
• frontmatter description → description
• frontmatter model → model
• Markdown body → developer_instructions (multi-line TOML string)

So rather than symlinking Markdown into ~/.codex/agents (which Codex can't parse), point an extra at your agents source and let the transform emit valid .toml:

extras:
  - name: codex-agents
    source: ~/.config/skillshare/agents   # your agent Markdown source
    targets:
      - path: ~/.codex/agents
        extension: codex-agents            # .md → .toml during sync

Then skillshare sync extras writes converted TOML agents into ~/.codex/agents. Install the transform from Config → Extensions in the dashboard, or copy extensions/codex-agents/ and adapt the field mapping.

On making Codex a first-class agent target under sync agents: I'm intentionally not going that route. Codex's agent format diverges from the Claude-style Markdown that the rest of the ecosystem shares, and baking a bespoke converter into core for each vendor that does its own thing would mean carrying per-vendor conversion code in the sync engine indefinitely. The extension mechanism keeps that conversion pluggable and in user space, which is exactly where format-specific quirks belong. If the ecosystem converges on a common agent format — or Codex grows to read Markdown agents — first-class support becomes trivial and I'll happily add it. Until then, the codex-agents transform is the supported path.

Leaving this open as the canonical reference for Codex agent support.