Switch codex skills from deprecated custom prompts to ~/.agents/skills SKILL.md (#390)

Custom prompts (~/.codex/prompts/) are deprecated upstream and are only user-typed
slash commands — the model never discovers them, so a codex task cannot self-advance
its workflow. Switch to codex's model-discoverable skills mechanism:
~/.agents/skills/<name>/SKILL.md (user scope, so nothing reaches the working tree).

Adds write_agent_skills / write_agent_operation_skills to container/skills.py with the
name+description frontmatter the skills surface requires; updates CodexAgentCLI to
call them; removes the now-unused PROMPTS_SUBDIR; updates test_codex.py path pins.

Co-authored-by: Panopticon Agent <agent@panopticon.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

src/panopticon/container/cli/codex.py

@@ -3,8 +3,9 @@
 Codex satisfies the same seams as claude against its own surface (ADR 0014 §5 mapping table):
 
 - **config dir** ``~/.codex`` (``CODEX_HOME``), config file ``config.toml``;
-- **skills / operations** → custom prompts under ``~/.codex/prompts/<name>.md`` (same
-  ``---\\ndescription: …\\n---`` frontmatter claude uses, so the body renderers are shared);
+- **skills / operations** → ``~/.agents/skills/<name>/SKILL.md`` (codex's model-discoverable
+  skills mechanism; user scope so nothing reaches the task's working tree; ``---\\nname: …\\n
+  description: …\\n---`` frontmatter, body renderers shared with claude);
 - **MCP** → a ``[mcp_servers.panopticon]`` table in ``config.toml`` over streamable **HTTP** (ADR
   flag 1: codex supports remote HTTP MCP; older builds need ``experimental_use_rmcp_client``);
 - **workflow overview** → ``$CODEX_HOME/AGENTS.md`` (our config dir — *never* the repo's
@@ -37,7 +38,7 @@
 from panopticon.container.cli.base import AgentCLI, _Client
 from panopticon.container.config import update_toml_config
 from panopticon.container.hooks import HOOK_COMMAND
-from panopticon.container.skills import write_commands, write_operation_commands
+from panopticon.container.skills import write_agent_operation_skills, write_agent_skills
 from panopticon.core.models import Skill
 
 #: The control plane's abstract model **tiers** mapped to codex's concrete model ids (ADR 0014 §3a).
@@ -67,23 +68,19 @@ class CodexAgentCLI(AgentCLI):
     #: codex's single config file, under the config dir. MCP, trust, and the unattended posture all
     #: merge into it (each adapter method touches only its own keys, via :func:`update_toml_config`).
     CONFIG_FILE: ClassVar[str] = "config.toml"
-    #: Where the skill/operation custom prompts go, relative to the config home.
-    PROMPTS_SUBDIR: ClassVar[tuple[str, ...]] = (".codex", "prompts")
     #: The workflow overview file inside the config dir — ``$CODEX_HOME/AGENTS.md`` (ADR 0014 §5).
     WORKFLOW_OVERVIEW_FILE: ClassVar[str] = "AGENTS.md"
     #: Session transcripts live here under the config dir; their presence means "resume" (§ launch).
     SESSIONS_DIRNAME: ClassVar[str] = "sessions"
 
     def render_skills(self, client: _Client, task_id: str, home: Path) -> list[Path]:
-        """Render the workflow's skills to ``~/.codex/prompts/`` (codex's custom-prompt surface)."""
+        """Render the workflow's skills to ``~/.agents/skills/`` (codex's model-discoverable surface)."""
         skills = [Skill(**s) for s in client.list_skills(task_id)]
-        return write_commands(skills, home, task_id, self.PROMPTS_SUBDIR)
+        return write_agent_skills(skills, home, task_id)
 
     def render_operations(self, client: _Client, task_id: str, home: Path) -> list[Path]:
-        """Render the workflow's declared core operations (advance/drop/…) as codex custom prompts."""
-        return write_operation_commands(
-            client.list_operations(task_id), home, task_id, self.PROMPTS_SUBDIR
-        )
+        """Render the workflow's declared core operations (advance/drop/…) as codex agent skills."""
+        return write_agent_operation_skills(client.list_operations(task_id), home, task_id)
 
     def write_settings(self, home: Path) -> Path:
         """Wire codex's turn-flip hooks into ``config.toml``; return the path (ADR 0014 §5, M3.6).

src/panopticon/container/skills.py

@@ -1,12 +1,15 @@
 """Render a workflow's :class:`~panopticon.core.models.Skill` specs to an agent CLI's command surface.
 
-The Skill spec is agent-CLI-agnostic (core, ADR 0004); the rendered **body** (frontmatter + the
-agent procedure) is CLI-agnostic too — claude and codex both read a ``---\\ndescription: …\\n---``
-markdown file. Only the destination dir differs: claude's ``.claude/commands/<name>.md`` slash-command
-vs codex's ``.codex/prompts/<name>.md`` custom prompt. So the writers take the ``subdir`` under the
-config home (defaulting to claude's), letting both adapters share the text. Pure — no LLM; it just
-writes files. The in-container harness fetches the active workflow's skills (over REST) and renders
-them before launching the agent (Slice 6c).
+The Skill spec is agent-CLI-agnostic (core, ADR 0004). The rendered body (frontmatter + the agent
+procedure) is shared across CLIs; only the destination and frontmatter format differ:
+
+- **claude** — ``.claude/commands/<name>.md``, ``---\\ndescription: …\\n---`` frontmatter.
+- **codex** — ``~/.agents/skills/<name>/SKILL.md``, ``---\\nname: …\\ndescription: …\\n---``
+  frontmatter (codex's model-discoverable skills mechanism; written to user scope so nothing reaches
+  the task's working tree).
+
+Pure — no LLM; it just writes files. The in-container harness fetches the active workflow's skills
+(over REST) and renders them before launching the agent (Slice 6c).
 """
 
 from __future__ import annotations
@@ -16,8 +19,7 @@
 
 from panopticon.core.models import Skill
 
-#: The default destination (relative to the config home) — claude's slash-command dir. Codex passes
-#: its own (``(".codex", "prompts")``).
+#: The default destination (relative to the config home) — claude's slash-command dir.
 CLAUDE_COMMANDS_SUBDIR: tuple[str, ...] = (".claude", "commands")
 
 
@@ -81,9 +83,7 @@ def write_operation_commands(
     task_id: str,
     subdir: Sequence[str] = CLAUDE_COMMANDS_SUBDIR,
 ) -> list[Path]:
-    """Write each core operation (verb → target state) to ``<root>/<subdir>/<verb>.md``.
-
-    ``subdir`` defaults to claude's ``.claude/commands``; codex passes ``(".codex", "prompts")``."""
+    """Write each core operation (verb → target state) to ``<root>/<subdir>/<verb>.md``."""
     commands_dir = root.joinpath(*subdir)
     commands_dir.mkdir(parents=True, exist_ok=True)
     written = []
@@ -92,3 +92,59 @@ def write_operation_commands(
         path.write_text(render_operation(name, target_state, task_id))
         written.append(path)
     return written
+
+
+# -- codex skills surface (model-discoverable; ~/.agents/skills/<name>/SKILL.md) ----------------
+
+
+def render_agent_skill(skill: Skill, task_id: str) -> str:
+    """The rendered ``SKILL.md`` body for a skill on the codex agent-skills surface.
+
+    Adds ``name:`` to the frontmatter (required by the skills mechanism) alongside ``description:``.
+    The instructions body and task-id note are the same as :func:`render_command`.
+    """
+    return (
+        f"---\nname: {skill.name}\ndescription: {skill.description}\n---\n"
+        f"{skill.instructions}\n{_task_id_note(task_id)}"
+    )
+
+
+def render_agent_operation(name: str, target_state: str, task_id: str) -> str:
+    """The rendered ``SKILL.md`` body for a core operation on the codex agent-skills surface."""
+    return (
+        f"---\nname: {name}\ndescription: Apply the workflow's '{name}' operation.\n---\n"
+        f"Apply this workflow's `{name}` operation — it moves the task to **{target_state}**. "
+        f'Invoke it with the `apply_operation` tool (`operation="{name}"`, `task_id="{task_id}"`); '
+        f"don't edit the state directly. It's gated on the current state's responsibilities and "
+        f"starts a new turn.\n"
+    )
+
+
+def write_agent_skills(skills: Iterable[Skill], root: Path, task_id: str) -> list[Path]:
+    """Write each skill to ``<root>/.agents/skills/<name>/SKILL.md``; return the paths written.
+
+    Uses codex's model-discoverable skills mechanism. Written to user scope (``<root>`` is
+    ``~``), so nothing reaches the task's working tree.
+    """
+    written = []
+    for skill in skills:
+        skill_dir = root / ".agents" / "skills" / skill.name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        path = skill_dir / "SKILL.md"
+        path.write_text(render_agent_skill(skill, task_id))
+        written.append(path)
+    return written
+
+
+def write_agent_operation_skills(
+    operations: Mapping[str, str], root: Path, task_id: str
+) -> list[Path]:
+    """Write each core operation to ``<root>/.agents/skills/<name>/SKILL.md``."""
+    written = []
+    for name, target_state in operations.items():
+        skill_dir = root / ".agents" / "skills" / name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        path = skill_dir / "SKILL.md"
+        path.write_text(render_agent_operation(name, target_state, task_id))
+        written.append(path)
+    return written

tests/container/test_codex.py

@@ -32,25 +32,32 @@ def _load_config(cli: CodexAgentCLI, config_dir: Path) -> dict[str, object]:
 # -- skills + operations → custom prompts -------------------------------------------------------
 
 
-def test_render_skills_writes_prompt_files(tmp_path: Path) -> None:
+def test_render_skills_writes_skill_files(tmp_path: Path) -> None:
     client = _FakeClient(
         [{"name": "babysit-ci", "description": "Watch CI.", "instructions": "loop"}]
     )
     CodexAgentCLI().render_skills(client, "t1", tmp_path)  # type: ignore[arg-type]
-    body = (tmp_path / ".codex" / "prompts" / "babysit-ci.md").read_text()
-    # Same frontmatter format codex + claude both read; the task id is injected for MCP calls.
-    assert body.startswith("---\ndescription: Watch CI.")
+    # Model-discoverable skills surface; user scope keeps the working tree clean.
+    path = tmp_path / ".agents" / "skills" / "babysit-ci" / "SKILL.md"
+    assert path.exists(), f"expected SKILL.md at {path}"
+    body = path.read_text()
+    assert body.startswith("---\nname: babysit-ci\ndescription: Watch CI.")
     assert 'task_id="t1"' in body
+    # Old custom-prompt surface must not be written.
+    assert not (tmp_path / ".codex" / "prompts").exists()
 
 
-def test_render_operations_writes_a_prompt_per_operation(tmp_path: Path) -> None:
+def test_render_operations_writes_a_skill_per_operation(tmp_path: Path) -> None:
     client = _FakeClient([], {"advance": "COMPLETE", "drop": "DROPPED"})
     CodexAgentCLI().render_operations(client, "t1", tmp_path)  # type: ignore[arg-type]
-    prompts = tmp_path / ".codex" / "prompts"
-    assert {p.name for p in prompts.glob("*.md")} == {"advance.md", "drop.md"}
-    body = (prompts / "advance.md").read_text()
+    skills_dir = tmp_path / ".agents" / "skills"
+    assert {p.parent.name for p in skills_dir.rglob("SKILL.md")} == {"advance", "drop"}
+    body = (skills_dir / "advance" / "SKILL.md").read_text()
+    assert body.startswith("---\nname: advance\n")
     assert "apply_operation" in body and "COMPLETE" in body
     assert 'task_id="t1"' in body
+    # Old custom-prompt surface must not be written.
+    assert not (tmp_path / ".codex" / "prompts").exists()
 
 
 # -- MCP config (config.toml [mcp_servers.panopticon]) ------------------------------------------