Codex Cli Specialist

# =============================================================================
# agents/openai.yaml - Codex CLI Skill Configuration Template
# =============================================================================
#
# This template defines a skill for OpenAI Codex CLI.
# Copy this file to your-skill/agents/openai.yaml and customize it.
#
# Documentation: references/codex-cli-guide.md
# Converter tool: python scripts/codex_skill_converter.py
# Validator tool: python scripts/cross_platform_validator.py
#
# =============================================================================

# ---------------------------------------------------------------------------
# REQUIRED: Skill identity
# ---------------------------------------------------------------------------

# Unique identifier for the skill (kebab-case, lowercase)
name: my-skill-name

# Short description for skill discovery and matching.
# Codex uses this to decide when to activate the skill.
# Be specific about what the skill does and when to use it.
description: >
  Expert guidance for [DOMAIN]. Analyzes [X], generates [Y],
  and enforces [Z] best practices. Use when working with [CONTEXT].

# ---------------------------------------------------------------------------
# RECOMMENDED: Behavioral instructions
# ---------------------------------------------------------------------------

# Instructions define how the agent behaves when this skill is active.
# Write in second person ("You are...") with clear structure.
# Keep under 2000 words for optimal context usage.
instructions: |
  You are a senior [DOMAIN] specialist with deep expertise in [AREAS].

  ## Core Responsibilities
  - [Responsibility 1: what you help with]
  - [Responsibility 2: what you analyze]
  - [Responsibility 3: what you generate]

  ## Process
  When the user asks about [PRIMARY TASK]:
  1. Understand the context and requirements
  2. Run the appropriate analysis tool
  3. Apply best practices from references/
  4. Provide structured recommendations

  When the user asks about [SECONDARY TASK]:
  1. [Step 1]
  2. [Step 2]
  3. [Step 3]

  ## Quality Standards
  - Always explain your reasoning
  - Provide concrete, actionable recommendations
  - Reference specific files and line numbers when relevant
  - Use the available tools for data-driven analysis
  - Follow the patterns in references/ for domain best practices

  ## Output Format
  Structure your responses with:
  - A brief summary of findings
  - Detailed analysis with evidence
  - Prioritized recommendations
  - Next steps for the user

# ---------------------------------------------------------------------------
# RECOMMENDED: Tool definitions
# ---------------------------------------------------------------------------

# Tools expose Python scripts to the Codex agent.
# Each tool maps to a command that Codex can execute.
tools:
  # Tool 1: Primary analysis tool
  - name: primary_analyzer
    description: >
      Analyzes [X] and produces a structured assessment report.
      Use this when the user asks to review, audit, or evaluate [X].
    command: python scripts/primary_analyzer.py
    # Optional: define accepted arguments
    # args:
    #   - name: input_path
    #     description: Path to the file or directory to analyze
    #     required: true
    #   - name: format
    #     description: Output format (json or text)
    #     required: false
    #     default: text

  # Tool 2: Generator tool
  - name: artifact_generator
    description: >
      Generates [Y] artifacts from templates and configuration.
      Use this when the user asks to create, scaffold, or produce [Y].
    command: python scripts/artifact_generator.py

  # Tool 3: Validator tool (optional)
  # - name: validator
  #   description: >
  #     Validates [Z] against best practices and standards.
  #     Use this when the user asks to check, verify, or validate [Z].
  #   command: python scripts/validator.py

# ---------------------------------------------------------------------------
# OPTIONAL: Model and version
# ---------------------------------------------------------------------------

# Preferred model for this skill (optional - uses user default if omitted)
# Options: o4-mini (fast, cheap), o3 (complex reasoning), gpt-4.1 (broad)
# model: o4-mini

# Skill version (follows semver)
version: 1.0.0

#!/usr/bin/env python3
"""
Codex Skill Converter

Converts a Claude Code SKILL.md into Codex-compatible format by generating
an agents/openai.yaml configuration file alongside the existing skill.

Usage:
    python codex_skill_converter.py path/to/SKILL.md
    python codex_skill_converter.py path/to/SKILL.md --output-dir ./converted
    python codex_skill_converter.py path/to/SKILL.md --json
"""

import argparse
import json
import os
import re
import shutil
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


def parse_yaml_frontmatter(content: str) -> Tuple[Dict[str, Any], str]:
    """Parse YAML frontmatter from markdown content.

    Returns a tuple of (frontmatter_dict, body_content).
    Uses a simple parser to avoid external dependencies.
    """
    frontmatter: Dict[str, Any] = {}
    body = content

    if not content.startswith("---"):
        return frontmatter, body

    lines = content.split("\n")
    end_index = -1
    for i in range(1, len(lines)):
        if lines[i].strip() == "---":
            end_index = i
            break

    if end_index == -1:
        return frontmatter, body

    fm_lines = lines[1:end_index]
    body = "\n".join(lines[end_index + 1:]).lstrip("\n")

    # Simple YAML key-value parser (handles flat keys and nested metadata)
    current_key = None
    current_indent = 0

    for line in fm_lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        # Top-level key: value
        match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
        if match and indent == 0:
            key = match.group(1)
            value = match.group(2).strip()
            if value:
                # Remove surrounding quotes if present
                if (value.startswith('"') and value.endswith('"')) or \
                   (value.startswith("'") and value.endswith("'")):
                    value = value[1:-1]
                frontmatter[key] = value
            else:
                frontmatter[key] = {}
            current_key = key
            current_indent = indent
            continue

        # Nested key: value (under metadata, codex, etc.)
        if indent > 0 and current_key and isinstance(frontmatter.get(current_key), dict):
            nested_match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
            if nested_match:
                nkey = nested_match.group(1)
                nval = nested_match.group(2).strip()
                if (nval.startswith('"') and nval.endswith('"')) or \
                   (nval.startswith("'") and nval.endswith("'")):
                    nval = nval[1:-1]
                frontmatter[current_key][nkey] = nval
                continue

        # Multi-line description continuation
        if current_key == "description" and indent > 0 and isinstance(frontmatter.get("description"), str):
            frontmatter["description"] += " " + stripped

    return frontmatter, body


def extract_title(body: str) -> str:
    """Extract the first H1 title from markdown body."""
    for line in body.split("\n"):
        line = line.strip()
        if line.startswith("# "):
            return line[2:].strip()
    return ""


def extract_scripts(skill_dir: Path) -> List[Dict[str, str]]:
    """Find Python scripts in the skill's scripts/ directory."""
    scripts_dir = skill_dir / "scripts"
    tools = []

    if not scripts_dir.is_dir():
        return tools

    for script_path in sorted(scripts_dir.glob("*.py")):
        name = script_path.stem
        # Read first docstring for description
        description = f"Runs {script_path.name}"
        try:
            with open(script_path, "r", encoding="utf-8") as f:
                content = f.read()
            # Extract module docstring
            doc_match = re.search(r'^"""(.*?)"""', content, re.DOTALL)
            if not doc_match:
                doc_match = re.search(r"^'''(.*?)'''", content, re.DOTALL)
            if doc_match:
                doc_text = doc_match.group(1).strip()
                # Take just the first line or sentence
                first_line = doc_text.split("\n")[0].strip()
                if first_line:
                    description = first_line
        except (OSError, UnicodeDecodeError):
            pass

        tools.append({
            "name": name,
            "description": description,
            "command": f"python scripts/{script_path.name}",
        })

    return tools


def build_instructions(frontmatter: Dict[str, Any], body: str, title: str) -> str:
    """Build Codex instructions from the skill's content."""
    lines = []

    lines.append(f"You are an expert {title.lower()} specialist.")
    lines.append("")

    # Extract description for context
    desc = frontmatter.get("description", "")
    if desc:
        lines.append(f"## Purpose")
        lines.append(desc)
        lines.append("")

    # Extract key sections from the body for instructions
    sections = extract_key_sections(body)
    if sections.get("workflows"):
        lines.append("## Key Workflows")
        for wf in sections["workflows"][:5]:  # Limit to 5 workflows
            lines.append(f"- {wf}")
        lines.append("")

    if sections.get("best_practices"):
        lines.append("## Best Practices")
        for bp in sections["best_practices"][:8]:
            lines.append(f"- {bp}")
        lines.append("")

    lines.append("## Output Standards")
    lines.append("- Provide clear, actionable guidance")
    lines.append("- Show concrete examples when possible")
    lines.append("- Reference available tools when relevant")
    lines.append("- Use the scripts in the scripts/ directory for automation")

    return "\n".join(lines)


def extract_key_sections(body: str) -> Dict[str, List[str]]:
    """Extract workflow names and best practices from markdown body."""
    result: Dict[str, List[str]] = {"workflows": [], "best_practices": []}

    lines = body.split("\n")
    in_best_practices = False

    for line in lines:
        stripped = line.strip()

        # Find workflow section headers (### Workflow N: Title)
        wf_match = re.match(r'^###\s+(?:Workflow\s+\d+[:.]\s*)?(.+)', stripped)
        if wf_match and "workflow" in stripped.lower():
            result["workflows"].append(wf_match.group(1).strip())

        # Detect best practices sections
        if re.match(r'^#{1,3}\s+[Bb]est\s+[Pp]ractices', stripped):
            in_best_practices = True
            continue

        # Next heading exits best practices
        if in_best_practices and re.match(r'^#{1,3}\s+', stripped):
            in_best_practices = False
            continue

        # Collect numbered or bulleted items in best practices
        if in_best_practices:
            bp_match = re.match(r'^[\d]+[.)]\s+\*\*(.+?)\*\*', stripped)
            if bp_match:
                result["best_practices"].append(bp_match.group(1).strip())
            elif stripped.startswith("- ") or stripped.startswith("* "):
                text = stripped.lstrip("-* ").strip()
                if text and not text.startswith("```"):
                    result["best_practices"].append(text)

    return result


def generate_openai_yaml(
    name: str,
    description: str,
    instructions: str,
    tools: List[Dict[str, str]],
    version: str = "1.0.0",
    model: Optional[str] = None,
) -> str:
    """Generate the agents/openai.yaml content."""
    lines = []

    lines.append(f"name: {name}")
    lines.append("description: >")
    # Wrap description at ~78 chars
    desc_words = description.split()
    current_line = "  "
    for word in desc_words:
        if len(current_line) + len(word) + 1 > 78:
            lines.append(current_line.rstrip())
            current_line = "  " + word
        else:
            current_line += (" " if len(current_line.strip()) > 0 else "") + word
    if current_line.strip():
        lines.append(current_line.rstrip())

    lines.append("instructions: |")
    for inst_line in instructions.split("\n"):
        if inst_line:
            lines.append(f"  {inst_line}")
        else:
            lines.append("")

    if tools:
        lines.append("tools:")
        for tool in tools:
            lines.append(f"  - name: {tool['name']}")
            lines.append(f"    description: >")
            lines.append(f"      {tool['description']}")
            lines.append(f"    command: {tool['command']}")

    if model:
        lines.append(f"model: {model}")

    lines.append(f"version: {version}")

    return "\n".join(lines) + "\n"


def convert_skill(
    skill_md_path: str,
    output_dir: Optional[str] = None,
) -> Dict[str, Any]:
    """Convert a Claude Code SKILL.md to Codex-compatible format.

    Returns a result dict with status, warnings, and generated files.
    """
    result: Dict[str, Any] = {
        "status": "success",
        "source": str(skill_md_path),
        "output_dir": "",
        "files_generated": [],
        "files_copied": [],
        "warnings": [],
        "errors": [],
    }

    skill_md = Path(skill_md_path).resolve()

    if not skill_md.is_file():
        result["status"] = "error"
        result["errors"].append(f"File not found: {skill_md}")
        return result

    if skill_md.name != "SKILL.md":
        result["warnings"].append(
            f"Expected filename 'SKILL.md', got '{skill_md.name}'. Proceeding anyway."
        )

    skill_dir = skill_md.parent

    # Determine output directory
    if output_dir:
        out_path = Path(output_dir).resolve()
    else:
        out_path = skill_dir

    result["output_dir"] = str(out_path)

    # Read and parse SKILL.md
    try:
        with open(skill_md, "r", encoding="utf-8") as f:
            content = f.read()
    except (OSError, UnicodeDecodeError) as e:
        result["status"] = "error"
        result["errors"].append(f"Cannot read {skill_md}: {e}")
        return result

    frontmatter, body = parse_yaml_frontmatter(content)

    if not frontmatter:
        result["warnings"].append("No YAML frontmatter found. Using defaults.")

    # Extract key fields
    name = frontmatter.get("name", skill_dir.name)
    description = frontmatter.get("description", "")
    title = extract_title(body) or name

    if not description:
        description = f"Expert guidance for {title}."
        result["warnings"].append("No description in frontmatter. Generated a default.")

    # Extract metadata
    metadata = frontmatter.get("metadata", {})
    version = "1.0.0"
    if isinstance(metadata, dict):
        version = metadata.get("version", "1.0.0")

    # Check for Codex-specific hints
    codex_hints = frontmatter.get("codex", {})
    model = None
    if isinstance(codex_hints, dict):
        model = codex_hints.get("model")

    # Find scripts
    tools = extract_scripts(skill_dir)

    # Build instructions
    instructions = build_instructions(frontmatter, body, title)

    # Generate openai.yaml
    yaml_content = generate_openai_yaml(
        name=name,
        description=description,
        instructions=instructions,
        tools=tools,
        version=version,
        model=model,
    )

    # Create output directory structure
    try:
        agents_dir = out_path / "agents"
        agents_dir.mkdir(parents=True, exist_ok=True)

        yaml_path = agents_dir / "openai.yaml"
        with open(yaml_path, "w", encoding="utf-8") as f:
            f.write(yaml_content)
        result["files_generated"].append(str(yaml_path))

    except OSError as e:
        result["status"] = "error"
        result["errors"].append(f"Cannot write output: {e}")
        return result

    # If output dir differs from source, copy other files
    if out_path != skill_dir:
        for subdir in ["scripts", "references", "assets"]:
            src = skill_dir / subdir
            dst = out_path / subdir
            if src.is_dir():
                try:
                    if dst.exists():
                        shutil.rmtree(dst)
                    shutil.copytree(src, dst)
                    result["files_copied"].append(str(dst))
                except OSError as e:
                    result["warnings"].append(f"Could not copy {subdir}/: {e}")

        # Copy SKILL.md
        dst_skill = out_path / "SKILL.md"
        try:
            shutil.copy2(skill_md, dst_skill)
            result["files_copied"].append(str(dst_skill))
        except OSError as e:
            result["warnings"].append(f"Could not copy SKILL.md: {e}")

    # Check for existing openai.yaml that was overwritten
    if (skill_dir / "agents" / "openai.yaml").is_file() and out_path == skill_dir:
        result["warnings"].append(
            "Overwrote existing agents/openai.yaml. Previous version not backed up."
        )

    return result


def format_human_output(result: Dict[str, Any]) -> str:
    """Format result as human-readable text."""
    lines = []
    lines.append("Codex Skill Converter")
    lines.append("=" * 40)
    lines.append("")
    lines.append(f"Source:     {result['source']}")
    lines.append(f"Output:    {result['output_dir']}")
    lines.append(f"Status:    {result['status'].upper()}")
    lines.append("")

    if result["files_generated"]:
        lines.append("Files Generated:")
        for f in result["files_generated"]:
            lines.append(f"  + {f}")
        lines.append("")

    if result["files_copied"]:
        lines.append("Files Copied:")
        for f in result["files_copied"]:
            lines.append(f"  > {f}")
        lines.append("")

    if result["warnings"]:
        lines.append("Warnings:")
        for w in result["warnings"]:
            lines.append(f"  ! {w}")
        lines.append("")

    if result["errors"]:
        lines.append("Errors:")
        for e in result["errors"]:
            lines.append(f"  X {e}")
        lines.append("")

    if result["status"] == "success":
        lines.append("Conversion complete. Review agents/openai.yaml before deploying.")
    else:
        lines.append("Conversion failed. See errors above.")

    return "\n".join(lines)


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Convert a Claude Code SKILL.md into Codex-compatible format.",
        epilog="Example: python codex_skill_converter.py path/to/SKILL.md --output-dir ./converted",
    )
    parser.add_argument(
        "skill_md",
        help="Path to the Claude Code SKILL.md file to convert",
    )
    parser.add_argument(
        "--output-dir",
        default=None,
        help="Output directory for the converted skill (default: same as source)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output results in JSON format",
    )

    args = parser.parse_args()

    result = convert_skill(args.skill_md, args.output_dir)

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print(format_human_output(result))

    if result["status"] != "success":
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Cross-Platform Skill Validator

Validates that a skill directory is compatible with both Claude Code and
Codex CLI. Checks YAML frontmatter, file structure, description format,
and agents/openai.yaml configuration.

Usage:
    python cross_platform_validator.py path/to/skill-dir
    python cross_platform_validator.py path/to/skill-dir --strict
    python cross_platform_validator.py path/to/skill-dir --json
"""

import argparse
import json
import os
import re
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


class ValidationResult:
    """Holds a single validation check result."""

    def __init__(self, check: str, platform: str, passed: bool,
                 message: str, severity: str = "error"):
        self.check = check
        self.platform = platform
        self.passed = passed
        self.message = message
        self.severity = severity  # "error", "warning", "info"

    def to_dict(self) -> Dict[str, Any]:
        return {
            "check": self.check,
            "platform": self.platform,
            "passed": self.passed,
            "message": self.message,
            "severity": self.severity,
        }


def parse_yaml_frontmatter_simple(content: str) -> Tuple[Dict[str, str], bool]:
    """Simple YAML frontmatter parser. Returns (dict, is_valid)."""
    result: Dict[str, str] = {}

    if not content.startswith("---"):
        return result, False

    lines = content.split("\n")
    end_index = -1
    for i in range(1, len(lines)):
        if lines[i].strip() == "---":
            end_index = i
            break

    if end_index == -1:
        return result, False

    fm_lines = lines[1:end_index]
    current_key = None
    current_value = ""

    for line in fm_lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        # Top-level key: value
        match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
        if match and indent == 0:
            if current_key and current_value:
                result[current_key] = current_value.strip()
            current_key = match.group(1)
            current_value = match.group(2).strip()
            # Remove quotes
            if (current_value.startswith('"') and current_value.endswith('"')) or \
               (current_value.startswith("'") and current_value.endswith("'")):
                current_value = current_value[1:-1]
            continue

        # Continuation of multi-line value
        if indent > 0 and current_key:
            if current_key in ("description",):
                current_value += " " + stripped
            elif ":" in stripped:
                # Nested key - store parent as marker
                if current_key not in result:
                    result[current_key] = "__nested__"

    if current_key and current_value:
        result[current_key] = current_value.strip()

    return result, True


def parse_openai_yaml_simple(content: str) -> Tuple[Dict[str, Any], bool]:
    """Simple parser for agents/openai.yaml. Returns (dict, is_valid)."""
    result: Dict[str, Any] = {}

    lines = content.split("\n")
    current_key = None
    current_value = ""
    tools_list: List[Dict[str, str]] = []
    in_tools = False
    current_tool: Dict[str, str] = {}

    for line in lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        # Top-level key
        top_match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
        if top_match and indent == 0:
            # Save previous key
            if current_key and current_value and current_key != "tools":
                result[current_key] = current_value.strip()
            if in_tools and current_tool:
                tools_list.append(current_tool)
                current_tool = {}

            current_key = top_match.group(1)
            val = top_match.group(2).strip()

            if current_key == "tools":
                in_tools = True
                current_value = ""
                continue

            in_tools = False
            if val in (">", "|", "|-", ">-"):
                current_value = ""
            else:
                current_value = val
            continue

        # Inside tools section
        if in_tools:
            if stripped.startswith("- name:"):
                if current_tool:
                    tools_list.append(current_tool)
                current_tool = {"name": stripped.split(":", 1)[1].strip()}
            elif ":" in stripped and current_tool:
                k, v = stripped.split(":", 1)
                k = k.strip()
                v = v.strip()
                if v in (">", "|"):
                    current_tool[k] = ""
                elif v:
                    current_tool[k] = v
                elif k in current_tool and not current_tool[k]:
                    pass  # Multi-line continuation handled below
            elif current_tool:
                # Continuation line for tool field
                for tk in ("description", "command"):
                    if tk in current_tool and not current_tool[tk]:
                        current_tool[tk] = stripped
                        break
            continue

        # Multi-line value continuation
        if indent > 0 and current_key:
            if current_value:
                current_value += " " + stripped
            else:
                current_value = stripped

    # Finalize
    if current_key and current_value and current_key != "tools":
        result[current_key] = current_value.strip()
    if in_tools and current_tool:
        tools_list.append(current_tool)
    if tools_list:
        result["tools"] = tools_list

    return result, bool(result)


def validate_skill(skill_dir: str, strict: bool = False) -> Dict[str, Any]:
    """Validate a skill directory for cross-platform compatibility.

    Returns a validation report dict.
    """
    path = Path(skill_dir).resolve()
    checks: List[ValidationResult] = []
    skill_name = path.name

    # =========================================================
    # Claude Code Compatibility Checks
    # =========================================================

    # Check 1: SKILL.md exists
    skill_md_path = path / "SKILL.md"
    if skill_md_path.is_file():
        checks.append(ValidationResult(
            "skill_md_exists", "claude-code", True,
            "SKILL.md exists"
        ))
    else:
        checks.append(ValidationResult(
            "skill_md_exists", "claude-code", False,
            "SKILL.md not found - required for Claude Code",
            "error"
        ))

    # Check 2: Valid YAML frontmatter
    frontmatter: Dict[str, str] = {}
    if skill_md_path.is_file():
        try:
            with open(skill_md_path, "r", encoding="utf-8") as f:
                content = f.read()
            frontmatter, fm_valid = parse_yaml_frontmatter_simple(content)
            if fm_valid:
                checks.append(ValidationResult(
                    "valid_frontmatter", "claude-code", True,
                    "Valid YAML frontmatter found"
                ))
            else:
                checks.append(ValidationResult(
                    "valid_frontmatter", "claude-code", False,
                    "No valid YAML frontmatter (must start with --- and end with ---)",
                    "error"
                ))
        except (OSError, UnicodeDecodeError) as e:
            checks.append(ValidationResult(
                "valid_frontmatter", "claude-code", False,
                f"Cannot read SKILL.md: {e}",
                "error"
            ))

    # Check 3: Name field present
    if frontmatter.get("name"):
        checks.append(ValidationResult(
            "name_field", "claude-code", True,
            f"Name field present: {frontmatter['name']}"
        ))
        skill_name = frontmatter["name"]
    else:
        checks.append(ValidationResult(
            "name_field", "claude-code", False,
            "Name field missing in frontmatter",
            "error"
        ))

    # Check 4: Description field present and third-person
    desc = frontmatter.get("description", "")
    if desc:
        checks.append(ValidationResult(
            "description_exists", "claude-code", True,
            "Description field present"
        ))

        # Check third-person / discovery format
        discovery_patterns = [
            r"this skill",
            r"should be used when",
            r"use for",
            r"use when",
            r"analyzes",
            r"generates",
            r"provides",
            r"automates",
        ]
        has_discovery_pattern = any(
            re.search(pat, desc, re.IGNORECASE) for pat in discovery_patterns
        )
        if has_discovery_pattern:
            checks.append(ValidationResult(
                "description_format", "claude-code", True,
                "Description uses discovery-friendly format"
            ))
        else:
            checks.append(ValidationResult(
                "description_format", "claude-code", False,
                "Description should use third-person, discovery-friendly format "
                "(e.g., 'This skill should be used when...')",
                "warning"
            ))
    else:
        checks.append(ValidationResult(
            "description_exists", "claude-code", False,
            "Description field missing in frontmatter",
            "error"
        ))

    # Check 5: License field
    if frontmatter.get("license"):
        checks.append(ValidationResult(
            "license_field", "claude-code", True,
            f"License: {frontmatter['license']}"
        ))
    else:
        checks.append(ValidationResult(
            "license_field", "claude-code", False,
            "License field missing (recommended for distribution)",
            "warning"
        ))

    # Check 6: Scripts directory
    scripts_dir = path / "scripts"
    if scripts_dir.is_dir():
        py_scripts = list(scripts_dir.glob("*.py"))
        if py_scripts:
            checks.append(ValidationResult(
                "scripts_dir", "claude-code", True,
                f"scripts/ directory found ({len(py_scripts)} Python tool(s))"
            ))
        else:
            checks.append(ValidationResult(
                "scripts_dir", "claude-code", False,
                "scripts/ directory exists but contains no Python files",
                "warning"
            ))
    else:
        checks.append(ValidationResult(
            "scripts_dir", "claude-code", False,
            "scripts/ directory not found (optional but recommended)",
            "warning"
        ))

    # Check 7: References directory
    refs_dir = path / "references"
    if refs_dir.is_dir():
        ref_files = list(refs_dir.glob("*.md"))
        checks.append(ValidationResult(
            "references_dir", "claude-code", True,
            f"references/ directory found ({len(ref_files)} file(s))"
        ))
    else:
        checks.append(ValidationResult(
            "references_dir", "claude-code", False,
            "references/ directory not found (optional)",
            "info"
        ))

    # Check 8: Assets directory
    assets_dir = path / "assets"
    if assets_dir.is_dir():
        asset_files = list(assets_dir.iterdir())
        asset_count = len([f for f in asset_files if f.is_file()])
        checks.append(ValidationResult(
            "assets_dir", "claude-code", True,
            f"assets/ directory found ({asset_count} file(s))"
        ))
    else:
        checks.append(ValidationResult(
            "assets_dir", "claude-code", False,
            "assets/ directory not found (optional)",
            "info"
        ))

    # Check 9: No requirements.txt or heavy dependencies
    req_file = path / "requirements.txt"
    if req_file.is_file():
        try:
            with open(req_file, "r", encoding="utf-8") as f:
                deps = [l.strip() for l in f if l.strip() and not l.startswith("#")]
            if deps:
                checks.append(ValidationResult(
                    "no_heavy_deps", "claude-code", False,
                    f"requirements.txt found with {len(deps)} dependencies "
                    f"(skills should use standard library only)",
                    "warning"
                ))
        except OSError:
            pass
    else:
        checks.append(ValidationResult(
            "no_heavy_deps", "claude-code", True,
            "No requirements.txt (standard library only - good)"
        ))

    # =========================================================
    # Codex CLI Compatibility Checks
    # =========================================================

    # Check 10: agents/openai.yaml exists
    yaml_path = path / "agents" / "openai.yaml"
    if yaml_path.is_file():
        checks.append(ValidationResult(
            "openai_yaml_exists", "codex-cli", True,
            "agents/openai.yaml exists"
        ))
    else:
        checks.append(ValidationResult(
            "openai_yaml_exists", "codex-cli", False,
            "agents/openai.yaml not found - required for Codex CLI",
            "error"
        ))

    # Check 11: Valid YAML structure
    yaml_data: Dict[str, Any] = {}
    if yaml_path.is_file():
        try:
            with open(yaml_path, "r", encoding="utf-8") as f:
                yaml_content = f.read()
            yaml_data, yaml_valid = parse_openai_yaml_simple(yaml_content)
            if yaml_valid:
                checks.append(ValidationResult(
                    "openai_yaml_valid", "codex-cli", True,
                    "agents/openai.yaml has valid structure"
                ))
            else:
                checks.append(ValidationResult(
                    "openai_yaml_valid", "codex-cli", False,
                    "agents/openai.yaml appears empty or invalid",
                    "error"
                ))
        except (OSError, UnicodeDecodeError) as e:
            checks.append(ValidationResult(
                "openai_yaml_valid", "codex-cli", False,
                f"Cannot read agents/openai.yaml: {e}",
                "error"
            ))

    # Check 12: Name field in openai.yaml
    if yaml_data.get("name"):
        checks.append(ValidationResult(
            "yaml_name", "codex-cli", True,
            f"Name field present: {yaml_data['name']}"
        ))

        # Check name matches SKILL.md
        if skill_name and yaml_data["name"] != skill_name:
            checks.append(ValidationResult(
                "name_match", "cross-platform", False,
                f"Name mismatch: SKILL.md has '{skill_name}', "
                f"openai.yaml has '{yaml_data['name']}'",
                "warning"
            ))
        else:
            checks.append(ValidationResult(
                "name_match", "cross-platform", True,
                "Skill name matches across platforms"
            ))
    elif yaml_path.is_file():
        checks.append(ValidationResult(
            "yaml_name", "codex-cli", False,
            "Name field missing in agents/openai.yaml",
            "error"
        ))

    # Check 13: Description in openai.yaml
    if yaml_data.get("description"):
        checks.append(ValidationResult(
            "yaml_description", "codex-cli", True,
            "Description field present in openai.yaml"
        ))
    elif yaml_path.is_file():
        checks.append(ValidationResult(
            "yaml_description", "codex-cli", False,
            "Description field missing in agents/openai.yaml",
            "error"
        ))

    # Check 14: Instructions in openai.yaml
    if yaml_data.get("instructions"):
        inst_len = len(yaml_data["instructions"])
        if inst_len > 50:
            checks.append(ValidationResult(
                "yaml_instructions", "codex-cli", True,
                f"Instructions field present ({inst_len} chars)"
            ))
        else:
            checks.append(ValidationResult(
                "yaml_instructions", "codex-cli", False,
                f"Instructions field is very short ({inst_len} chars) - "
                "consider adding more detail",
                "warning"
            ))
    elif yaml_path.is_file():
        checks.append(ValidationResult(
            "yaml_instructions", "codex-cli", False,
            "Instructions field missing in agents/openai.yaml",
            "warning"
        ))

    # Check 15: Tools in openai.yaml reference existing scripts
    if yaml_data.get("tools") and isinstance(yaml_data["tools"], list):
        for tool in yaml_data["tools"]:
            cmd = tool.get("command", "")
            # Extract script path from command
            script_match = re.search(r'scripts/(\S+)', cmd)
            if script_match:
                script_file = path / "scripts" / script_match.group(1)
                if script_file.is_file():
                    checks.append(ValidationResult(
                        f"tool_script_{tool.get('name', 'unknown')}", "codex-cli", True,
                        f"Tool '{tool.get('name', 'unknown')}' references existing script"
                    ))
                else:
                    checks.append(ValidationResult(
                        f"tool_script_{tool.get('name', 'unknown')}", "codex-cli", False,
                        f"Tool '{tool.get('name', 'unknown')}' references "
                        f"missing script: {script_match.group(1)}",
                        "error"
                    ))

    # =========================================================
    # Cross-Platform Checks
    # =========================================================

    # Check 16: File encoding (UTF-8)
    for file_path in path.rglob("*"):
        if file_path.is_file() and file_path.suffix in (".md", ".yaml", ".yml", ".py"):
            try:
                with open(file_path, "r", encoding="utf-8") as f:
                    f.read()
            except UnicodeDecodeError:
                checks.append(ValidationResult(
                    "utf8_encoding", "cross-platform", False,
                    f"File not UTF-8 encoded: {file_path.relative_to(path)}",
                    "error"
                ))
                break
    else:
        checks.append(ValidationResult(
            "utf8_encoding", "cross-platform", True,
            "All text files are UTF-8 encoded"
        ))

    # Check 17: Skill size
    total_size = sum(
        f.stat().st_size for f in path.rglob("*") if f.is_file()
    )
    size_kb = total_size / 1024
    if size_kb < 1024:
        checks.append(ValidationResult(
            "skill_size", "cross-platform", True,
            f"Skill size: {size_kb:.1f} KB (under 1 MB - good)"
        ))
    else:
        checks.append(ValidationResult(
            "skill_size", "cross-platform", False,
            f"Skill size: {size_kb:.1f} KB (over 1 MB - consider reducing)",
            "warning"
        ))

    # Build summary
    errors = [c for c in checks if not c.passed and c.severity == "error"]
    warnings = [c for c in checks if not c.passed and c.severity == "warning"]
    infos = [c for c in checks if not c.passed and c.severity == "info"]
    passed = [c for c in checks if c.passed]

    if strict:
        is_compatible = len(errors) == 0 and len(warnings) == 0
    else:
        is_compatible = len(errors) == 0

    report = {
        "skill_name": skill_name,
        "skill_path": str(path),
        "compatible": is_compatible,
        "summary": {
            "total_checks": len(checks),
            "passed": len(passed),
            "errors": len(errors),
            "warnings": len(warnings),
            "info": len(infos),
        },
        "checks": [c.to_dict() for c in checks],
    }

    return report


def format_human_output(report: Dict[str, Any]) -> str:
    """Format validation report as human-readable text."""
    lines = []
    lines.append("Cross-Platform Skill Validator")
    lines.append("=" * 40)
    lines.append(f"Skill: {report['skill_name']}")
    lines.append(f"Path:  {report['skill_path']}")
    lines.append("")

    # Group by platform
    platforms: Dict[str, List[Dict[str, Any]]] = {}
    for check in report["checks"]:
        platform = check["platform"]
        if platform not in platforms:
            platforms[platform] = []
        platforms[platform].append(check)

    platform_labels = {
        "claude-code": "Claude Code Compatibility",
        "codex-cli": "Codex CLI Compatibility",
        "cross-platform": "Cross-Platform Checks",
    }

    for platform_key in ["claude-code", "codex-cli", "cross-platform"]:
        if platform_key not in platforms:
            continue
        label = platform_labels.get(platform_key, platform_key)
        lines.append(f"{label}:")

        for check in platforms[platform_key]:
            if check["passed"]:
                status = "[PASS]"
            elif check["severity"] == "warning":
                status = "[WARN]"
            elif check["severity"] == "info":
                status = "[INFO]"
            else:
                status = "[FAIL]"
            lines.append(f"  {status} {check['message']}")

        lines.append("")

    # Summary
    s = report["summary"]
    compat_str = "COMPATIBLE" if report["compatible"] else "NOT COMPATIBLE"
    detail_parts = []
    if s["errors"] > 0:
        detail_parts.append(f"{s['errors']} error(s)")
    if s["warnings"] > 0:
        detail_parts.append(f"{s['warnings']} warning(s)")
    detail = f" ({', '.join(detail_parts)})" if detail_parts else ""

    lines.append(f"Overall: {compat_str}{detail}")
    lines.append(f"Checks: {s['passed']}/{s['total_checks']} passed")

    return "\n".join(lines)


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Validate a skill directory for Claude Code and Codex CLI compatibility.",
        epilog="Example: python cross_platform_validator.py path/to/skill-dir",
    )
    parser.add_argument(
        "skill_dir",
        help="Path to the skill directory to validate",
    )
    parser.add_argument(
        "--strict",
        action="store_true",
        help="Treat warnings as errors (fail if any warnings)",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output results in JSON format",
    )

    args = parser.parse_args()

    if not Path(args.skill_dir).is_dir():
        print(f"Error: '{args.skill_dir}' is not a directory", file=sys.stderr)
        sys.exit(1)

    report = validate_skill(args.skill_dir, strict=args.strict)

    if args.json:
        print(json.dumps(report, indent=2))
    else:
        print(format_human_output(report))

    if not report["compatible"]:
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Skills Index Builder

Builds a skills-index.json manifest from a directory of skills. Scans for
skill directories containing SKILL.md files, extracts metadata, and produces
a structured index for skill registries and discovery systems.

Usage:
    python skills_index_builder.py /path/to/skills
    python skills_index_builder.py /path/to/skills --output skills-index.json
    python skills_index_builder.py /path/to/skills --format human
    python skills_index_builder.py /path/to/skills --category engineering
"""

import argparse
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


INDEX_VERSION = "1.0.0"


def parse_yaml_frontmatter(content: str) -> Dict[str, Any]:
    """Parse YAML frontmatter from markdown content.

    Returns a flat-ish dict of frontmatter fields.
    """
    result: Dict[str, Any] = {}

    if not content.startswith("---"):
        return result

    lines = content.split("\n")
    end_index = -1
    for i in range(1, len(lines)):
        if lines[i].strip() == "---":
            end_index = i
            break

    if end_index == -1:
        return result

    fm_lines = lines[1:end_index]
    current_key: Optional[str] = None
    current_value = ""
    nested_dict: Dict[str, str] = {}
    nested_key: Optional[str] = None

    for line in fm_lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        # Top-level key
        match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
        if match and indent == 0:
            # Save previous
            if current_key:
                if nested_key and nested_dict:
                    result[current_key] = dict(nested_dict)
                    nested_dict = {}
                    nested_key = None
                elif current_value:
                    result[current_key] = current_value.strip()

            current_key = match.group(1)
            val = match.group(2).strip()

            # Remove YAML flow indicators
            if val in (">", "|", "|-", ">-"):
                current_value = ""
            elif val:
                if (val.startswith('"') and val.endswith('"')) or \
                   (val.startswith("'") and val.endswith("'")):
                    val = val[1:-1]
                current_value = val
            else:
                current_value = ""
                nested_key = current_key
            continue

        # Nested key: value
        if indent > 0 and nested_key:
            nested_match = re.match(r'^(\w[\w-]*)\s*:\s*(.*)', stripped)
            if nested_match:
                nkey = nested_match.group(1)
                nval = nested_match.group(2).strip()
                if (nval.startswith('"') and nval.endswith('"')) or \
                   (nval.startswith("'") and nval.endswith("'")):
                    nval = nval[1:-1]
                nested_dict[nkey] = nval
                continue

        # Multi-line continuation
        if indent > 0 and current_key:
            if current_value:
                current_value += " " + stripped
            else:
                current_value = stripped

    # Final key
    if current_key:
        if nested_key and nested_dict:
            result[current_key] = dict(nested_dict)
        elif current_value:
            result[current_key] = current_value.strip()

    return result


def detect_platforms(skill_dir: Path) -> List[str]:
    """Detect which platforms a skill supports."""
    platforms = []

    if (skill_dir / "SKILL.md").is_file():
        platforms.append("claude-code")

    if (skill_dir / "agents" / "openai.yaml").is_file():
        platforms.append("codex-cli")

    # Check for other platform markers
    if (skill_dir / ".cursorrules").is_file():
        platforms.append("cursor")

    if (skill_dir / ".github" / "copilot-instructions.md").is_file():
        platforms.append("github-copilot")

    return platforms


def get_directory_size(dir_path: Path) -> int:
    """Calculate total size of all files in a directory."""
    total = 0
    for f in dir_path.rglob("*"):
        if f.is_file():
            try:
                total += f.stat().st_size
            except OSError:
                pass
    return total


def count_files_by_type(dir_path: Path) -> Dict[str, int]:
    """Count files grouped by extension."""
    counts: Dict[str, int] = {}
    for f in dir_path.rglob("*"):
        if f.is_file():
            ext = f.suffix.lower() or "(no extension)"
            counts[ext] = counts.get(ext, 0) + 1
    return counts


def scan_skill(skill_dir: Path) -> Optional[Dict[str, Any]]:
    """Scan a single skill directory and extract metadata.

    Returns None if the directory is not a valid skill.
    """
    skill_md_path = skill_dir / "SKILL.md"
    if not skill_md_path.is_file():
        return None

    try:
        with open(skill_md_path, "r", encoding="utf-8") as f:
            content = f.read()
    except (OSError, UnicodeDecodeError):
        return None

    frontmatter = parse_yaml_frontmatter(content)

    name = frontmatter.get("name", skill_dir.name)
    description = frontmatter.get("description", "")
    license_val = frontmatter.get("license", "")

    # Extract metadata
    metadata = frontmatter.get("metadata", {})
    version = "0.0.0"
    category = ""
    domain = ""
    if isinstance(metadata, dict):
        version = metadata.get("version", "0.0.0")
        category = metadata.get("category", "")
        domain = metadata.get("domain", "")

    # Find scripts
    scripts_dir = skill_dir / "scripts"
    tools: List[str] = []
    if scripts_dir.is_dir():
        tools = sorted([f.name for f in scripts_dir.glob("*.py")])

    # Find references
    refs_dir = skill_dir / "references"
    references: List[str] = []
    if refs_dir.is_dir():
        references = sorted([f.name for f in refs_dir.glob("*.md")])

    # Find assets
    assets_dir = skill_dir / "assets"
    assets: List[str] = []
    if assets_dir.is_dir():
        assets = sorted([f.name for f in assets_dir.iterdir() if f.is_file()])

    # Detect platforms
    platforms = detect_platforms(skill_dir)

    # Calculate size
    total_size = get_directory_size(skill_dir)

    # Extract title from markdown body
    title = ""
    body_start = content.find("\n---\n")
    if body_start >= 0:
        body = content[body_start + 5:]
    else:
        body = content
    for line in body.split("\n"):
        if line.strip().startswith("# "):
            title = line.strip()[2:].strip()
            break

    # Extract keywords if present
    keywords: List[str] = []
    kw_match = re.search(
        r'##\s+Keywords\s*\n+(.+?)(?:\n\n|\n##)',
        content,
        re.DOTALL
    )
    if kw_match:
        kw_text = kw_match.group(1).strip()
        keywords = [k.strip() for k in kw_text.split(",") if k.strip()]

    return {
        "name": name,
        "title": title or name,
        "description": description,
        "version": version,
        "license": license_val,
        "category": category,
        "domain": domain,
        "keywords": keywords,
        "tools": tools,
        "tools_count": len(tools),
        "references": references,
        "references_count": len(references),
        "assets": assets,
        "assets_count": len(assets),
        "platforms": platforms,
        "size_bytes": total_size,
        "size_human": format_size(total_size),
        "path": str(skill_dir.relative_to(skill_dir.parent)),
    }


def format_size(size_bytes: int) -> str:
    """Format byte size to human readable string."""
    if size_bytes < 1024:
        return f"{size_bytes} B"
    elif size_bytes < 1024 * 1024:
        return f"{size_bytes / 1024:.1f} KB"
    else:
        return f"{size_bytes / (1024 * 1024):.1f} MB"


def build_index(
    skills_dir: str,
    category_filter: Optional[str] = None,
) -> Dict[str, Any]:
    """Build a skills index from a directory of skill subdirectories.

    Returns the complete index dict.
    """
    path = Path(skills_dir).resolve()

    if not path.is_dir():
        return {
            "error": f"Directory not found: {skills_dir}",
            "version": INDEX_VERSION,
            "skills": [],
            "skills_count": 0,
        }

    skills: List[Dict[str, Any]] = []

    # Scan all subdirectories for SKILL.md
    for item in sorted(path.iterdir()):
        if not item.is_dir():
            continue
        if item.name.startswith("."):
            continue

        skill_data = scan_skill(item)
        if skill_data is None:
            continue

        # Apply category filter
        if category_filter:
            if skill_data.get("category", "").lower() != category_filter.lower():
                continue

        skills.append(skill_data)

    # Build summary stats
    total_tools = sum(s["tools_count"] for s in skills)
    total_refs = sum(s["references_count"] for s in skills)
    total_size = sum(s["size_bytes"] for s in skills)

    categories: Dict[str, int] = {}
    domains: Dict[str, int] = {}
    platform_counts: Dict[str, int] = {}

    for s in skills:
        cat = s.get("category") or "uncategorized"
        categories[cat] = categories.get(cat, 0) + 1

        dom = s.get("domain") or "unspecified"
        domains[dom] = domains.get(dom, 0) + 1

        for p in s.get("platforms", []):
            platform_counts[p] = platform_counts.get(p, 0) + 1

    index = {
        "version": INDEX_VERSION,
        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
        "source_directory": str(path),
        "skills_count": len(skills),
        "summary": {
            "total_tools": total_tools,
            "total_references": total_refs,
            "total_size": format_size(total_size),
            "total_size_bytes": total_size,
            "categories": categories,
            "domains": domains,
            "platforms": platform_counts,
        },
        "skills": skills,
    }

    return index


def format_human_output(index: Dict[str, Any]) -> str:
    """Format index as human-readable text."""
    lines = []
    lines.append("Skills Index")
    lines.append("=" * 60)
    lines.append(f"Source:     {index.get('source_directory', 'N/A')}")
    lines.append(f"Generated: {index.get('generated_at', 'N/A')}")
    lines.append(f"Skills:    {index.get('skills_count', 0)}")
    lines.append("")

    summary = index.get("summary", {})
    lines.append(f"Total Tools:      {summary.get('total_tools', 0)}")
    lines.append(f"Total References: {summary.get('total_references', 0)}")
    lines.append(f"Total Size:       {summary.get('total_size', '0 B')}")
    lines.append("")

    cats = summary.get("categories", {})
    if cats:
        lines.append("Categories:")
        for cat, count in sorted(cats.items()):
            lines.append(f"  {cat}: {count}")
        lines.append("")

    platforms = summary.get("platforms", {})
    if platforms:
        lines.append("Platform Support:")
        for plat, count in sorted(platforms.items()):
            lines.append(f"  {plat}: {count} skill(s)")
        lines.append("")

    lines.append("-" * 60)
    lines.append(f"{'Name':<30} {'Version':<10} {'Tools':<8} {'Platforms'}")
    lines.append("-" * 60)

    for skill in index.get("skills", []):
        name = skill.get("name", "unknown")
        version = skill.get("version", "?")
        tools = str(skill.get("tools_count", 0))
        platforms_str = ", ".join(skill.get("platforms", []))

        # Truncate name if too long
        if len(name) > 28:
            name = name[:25] + "..."

        lines.append(f"{name:<30} {version:<10} {tools:<8} {platforms_str}")

    lines.append("-" * 60)
    lines.append(f"Total: {index.get('skills_count', 0)} skills")

    return "\n".join(lines)


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Build a skills-index.json manifest from a directory of skills.",
        epilog="Example: python skills_index_builder.py /path/to/skills --output skills-index.json",
    )
    parser.add_argument(
        "skills_dir",
        help="Path to the directory containing skill subdirectories",
    )
    parser.add_argument(
        "--output", "-o",
        default=None,
        help="Output file path (default: print to stdout)",
    )
    parser.add_argument(
        "--format", "-f",
        choices=["json", "human"],
        default="json",
        help="Output format (default: json)",
    )
    parser.add_argument(
        "--category", "-c",
        default=None,
        help="Filter skills by category",
    )

    args = parser.parse_args()

    if not Path(args.skills_dir).is_dir():
        print(f"Error: '{args.skills_dir}' is not a directory", file=sys.stderr)
        sys.exit(1)

    index = build_index(args.skills_dir, category_filter=args.category)

    if "error" in index and index["skills_count"] == 0:
        print(f"Error: {index['error']}", file=sys.stderr)
        sys.exit(1)

    if args.format == "human":
        output_text = format_human_output(index)
    else:
        output_text = json.dumps(index, indent=2)

    if args.output:
        output_path = Path(args.output)
        try:
            output_path.parent.mkdir(parents=True, exist_ok=True)
            with open(output_path, "w", encoding="utf-8") as f:
                f.write(output_text)
                f.write("\n")
            if args.format == "human":
                print(f"Index written to {output_path}")
            else:
                print(f"Index written to {output_path} ({index['skills_count']} skills)")
        except OSError as e:
            print(f"Error writing output: {e}", file=sys.stderr)
            sys.exit(1)
    else:
        print(output_text)


if __name__ == "__main__":
    main()