commands-frontmatter-adapter

hairihou's avatarfrom hairihou

Parse Claude command frontmatter and expose body/meta for Codex CLI.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Prompt Templates and Packaging]

When & Why to Use This Skill

The Commands Frontmatter Adapter is a specialized developer utility designed to bridge Claude-style command files with the Codex CLI. It efficiently parses Markdown-based command files to separate YAML metadata from the prompt body, enabling structured prompt management, metadata-driven execution, and seamless integration into automated AI workflows. By exposing metadata as JSON while isolating the prompt text, it ensures that AI agents receive clean instructions while developers maintain full control over command attributes.

Use Cases

  • Structured Prompt Management: Organize complex AI prompts in Markdown files while maintaining metadata like descriptions, argument hints, and tool whitelists in a clean YAML frontmatter.
  • Automated CLI Workflows: Streamline the process of piping prompt content directly into Codex CLI or other agentic interfaces by automatically stripping metadata blocks.
  • Dynamic Command Discovery: Programmatically extract command descriptions and usage hints to build interactive command-line pickers or automated documentation for custom AI toolsets.
  • Tool Permission Enforcement: Use the extracted 'allowed-tools' metadata to programmatically restrict or validate tool access during an AI agent's execution session.
namecommands-frontmatter-adapter
descriptionParse Claude command frontmatter and expose body/meta for Codex CLI.

Commands Frontmatter Adapter

Extract frontmatter and body from Claude-style command files so Codex CLI can consume the body as a prompt while still exposing metadata as JSON.

Usage

  • By command name (from the scripts directory): ./adapter.py --command diary --pretty
  • By explicit file (from anywhere): /abs/path/to/adapter.py --file /abs/path/to/src/.claude/commands/diary.md

Note: The script resolves src/.claude/commands relative to the skill location, so symlinked global installs work without depending on the current working directory. Use --file if your commands live elsewhere.

Options

  • --body-only Output body only (paste into prompt)
  • --frontmatter-only Output parsed frontmatter as JSON
  • --raw-frontmatter Output raw frontmatter block
  • --pretty Pretty-print JSON

Behavior

  1. Treat the first --- ... --- block as frontmatter.
  2. Try yaml.safe_load; if PyYAML is missing or fails, fall back to a minimal parser (key/value and bullet lists).
  3. JSON output structure:
    • file: target file path
    • frontmatter: parsed metadata (dict or null)
    • frontmatter_raw: raw text
    • body: body text

Known frontmatter keys (current commands)

  • description: short summary shown in command picker.
  • argument-hint: usage hint for $ARGUMENTS.
  • allowed-tools: tool whitelist string (pass-through; no validation here).

The adapter performs parsing only; interpretation or enforcement of these keys is left to the caller (e.g., Codex CLI prompt wrappers).

Tips

  • Prefer --body-only when piping into Codex CLI prompts.
  • Manually respect metadata such as allowed-tools as needed in your session.
  • If a file has no frontmatter, only the body is returned.