Create Claw Skill

#!/usr/bin/env python3
"""
OpenClaw Skill Initializer - Creates a new skill from template

Usage:
    init_claw_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]

Examples:
    init_claw_skill.py my-new-skill --path ~/.openclaw/skills
    init_claw_skill.py my-new-skill --path ~/.openclaw/skills --resources scripts,references
    init_claw_skill.py my-api-helper --path ./skills --resources scripts --examples
"""

import argparse
import re
import sys
from pathlib import Path

MAX_SKILL_NAME_LENGTH = 64
ALLOWED_RESOURCES = {"scripts", "references", "assets"}

SKILL_TEMPLATE = """---
name: {skill_name}
description: >
  [TODO: Write trigger-rich description. Include 3-5 varied trigger phrases.
  Example: "This skill should be used when the user asks to 'do X', 'handle Y', or mentions Z."]
---

# {skill_title}

[TODO: 1-2 sentences explaining what this skill enables]

## Process

[TODO: Choose structure that fits this skill's purpose:

**Workflow-Based** (sequential processes)
- Step-by-step procedures with clear ordering
- Example: ## Overview -> ## Step 1 -> ## Step 2...

**Task-Based** (tool collections)
- Different operations/capabilities grouped by function
- Example: ## Overview -> ## Task Category 1 -> ## Task Category 2...

**Reference/Guidelines** (standards or specifications)
- Brand guidelines, coding standards, requirements
- Example: ## Overview -> ## Guidelines -> ## Specifications...

Delete this section when done.]

## [First Section]

[TODO: Add content. Use imperative voice ("Analyze", "Generate").
No first-person ("I will"). Use exec tool for shell operations.
Reference skill-relative files with {{baseDir}}/path/to/file.]

## Resources

[TODO: Delete this section if no resources needed. Otherwise, document what's in each directory:]

### scripts/
Executable code invoked via the exec tool to perform deterministic operations.

### references/
Documentation loaded into context as needed via the read tool. Keep SKILL.md lean; put
detailed info here.

### assets/
Files used in output (templates, images, fonts) — not loaded into context.
"""

EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
Example helper script for {skill_name}

Replace with actual implementation or delete if not needed.
Invoke via the exec tool: python3 {{baseDir}}/scripts/example.py
"""

import sys

def main():
    print("Example script for {skill_name}")
    # TODO: Add actual script logic
    sys.exit(0)

if __name__ == "__main__":
    main()
'''

EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}

Replace with actual reference content or delete if not needed.
Load this file via the read tool when needed: read `{{baseDir}}/references/reference.md`

## When Reference Docs Are Useful

- Comprehensive option catalogs
- Detailed workflow guides
- Complex multi-step processes
- Information too lengthy for SKILL.md
- Content only needed for specific use cases
"""

EXAMPLE_ASSET = """# Example Asset

This placeholder represents where asset files would be stored.
Replace with actual files (templates, images, fonts) or delete if not needed.

Asset files are NOT loaded into context — they are used in output.
"""


def normalize_skill_name(skill_name):
    """Normalize a skill name to lowercase hyphen-case."""
    normalized = skill_name.strip().lower()
    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
    normalized = normalized.strip("-")
    normalized = re.sub(r"-{2,}", "-", normalized)
    return normalized


def title_case_skill_name(skill_name):
    """Convert hyphenated skill name to Title Case."""
    return " ".join(word.capitalize() for word in skill_name.split("-"))


def parse_resources(raw_resources):
    if not raw_resources:
        return []
    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
    if invalid:
        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
        print(f"   Allowed: {allowed}")
        sys.exit(1)
    return list(dict.fromkeys(resources))  # dedupe preserving order


def create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples):
    for resource in resources:
        resource_dir = skill_dir / resource
        resource_dir.mkdir(exist_ok=True)
        if resource == "scripts":
            if include_examples:
                example_script = resource_dir / "example.py"
                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
                example_script.chmod(0o755)
                print("[OK] Created scripts/example.py")
            else:
                print("[OK] Created scripts/")
        elif resource == "references":
            if include_examples:
                example_ref = resource_dir / "reference.md"
                example_ref.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
                print("[OK] Created references/reference.md")
            else:
                print("[OK] Created references/")
        elif resource == "assets":
            if include_examples:
                example_asset = resource_dir / "example_asset.txt"
                example_asset.write_text(EXAMPLE_ASSET)
                print("[OK] Created assets/example_asset.txt")
            else:
                print("[OK] Created assets/")


def init_skill(skill_name, path, resources, include_examples):
    skill_dir = Path(path).expanduser().resolve() / skill_name

    if skill_dir.exists():
        print(f"[ERROR] Skill directory already exists: {skill_dir}")
        return None

    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"[OK] Created skill directory: {skill_dir}")
    except Exception as e:
        print(f"[ERROR] Error creating directory: {e}")
        return None

    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)

    skill_md_path = skill_dir / "SKILL.md"
    try:
        skill_md_path.write_text(skill_content)
        print("[OK] Created SKILL.md")
    except Exception as e:
        print(f"[ERROR] Error creating SKILL.md: {e}")
        return None

    if resources:
        try:
            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)
        except Exception as e:
            print(f"[ERROR] Error creating resource directories: {e}")
            return None

    print(f"\n[OK] Skill '{skill_name}' initialized at {skill_dir}")
    print("\nNext steps:")
    print("1. Edit SKILL.md — complete TODOs and update description")
    if resources:
        print("2. Add/customize resources in scripts/, references/, assets/")
    print("3. Install: copy to ~/.openclaw/skills/ or <workspace>/skills/")
    print("4. Distribute: clawhub publish <path> --slug <slug> --version 1.0.0 --tags latest")

    return skill_dir


def main():
    parser = argparse.ArgumentParser(
        description="Create a new OpenClaw skill directory with template SKILL.md",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
    parser.add_argument("--path", required=True, help="Output directory (e.g., ~/.openclaw/skills)")
    parser.add_argument("--resources", default="", help="Comma-separated: scripts,references,assets")
    parser.add_argument("--examples", action="store_true", help="Create example files in resource dirs")
    args = parser.parse_args()

    skill_name = normalize_skill_name(args.skill_name)
    if not skill_name:
        print("[ERROR] Skill name must include at least one letter or digit.")
        sys.exit(1)
    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
        print(f"[ERROR] Skill name too long ({len(skill_name)} chars). Max: {MAX_SKILL_NAME_LENGTH}")
        sys.exit(1)
    if skill_name != args.skill_name:
        print(f"Note: Normalized '{args.skill_name}' to '{skill_name}'")

    resources = parse_resources(args.resources)
    if args.examples and not resources:
        print("[ERROR] --examples requires --resources")
        sys.exit(1)

    print(f"Initializing OpenClaw skill: {skill_name}")
    print(f"   Location: {args.path}")
    if resources:
        print(f"   Resources: {', '.join(resources)}")
    print()

    result = init_skill(skill_name, args.path, resources, args.examples)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
OpenClaw Skill Validator - Validates skill structure and frontmatter

Usage:
    validate_claw_skill.py <skill_directory> [--output json] [--strict]

Examples:
    validate_claw_skill.py ~/.openclaw/skills/my-skill
    validate_claw_skill.py ./skills/my-skill --output json
"""

import argparse
import json
import re
import sys
from pathlib import Path

MAX_SKILL_NAME_LENGTH = 64

# Valid OpenClaw frontmatter fields
ALLOWED_FRONTMATTER = {
    "name",
    "description",
    "user-invocable",
    "disable-model-invocation",
    "command-dispatch",
    "command-tool",
    "command-arg-mode",
    "metadata",
    "argument-hint",
    "homepage",  # valid alias for metadata.openclaw.homepage
}

# Claude Code-only fields that are invalid in OpenClaw
CLAUDE_CODE_FIELDS = {
    "model": "set at agent level in openclaw.json, not per-skill",
    "context": "context: fork is not supported; use sessions_spawn in skill body",
    "agent": "specialized agent routing is not available in OpenClaw",
    "allowed-tools": "tool policy is gateway config, not frontmatter",
    "hooks": "hooks are system-level, not per-skill in OpenClaw",
    "license": "not a valid OpenClaw skill field",
}

# Claude Code tool names that should not appear in OpenClaw skill bodies
CLAUDE_CODE_TOOLS = [
    "Bash", "WebSearch", "WebFetch", "Glob", "Grep",
    "Task", "Skill", "AskUserQuestion", "EnterPlanMode", "ExitPlanMode",
    "NotebookEdit",
]


def parse_frontmatter(content):
    """Extract and parse YAML frontmatter from SKILL.md content without PyYAML."""
    if not content.startswith("---"):
        return None, "No YAML frontmatter found (must start with ---)", None

    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
    if not match:
        return None, "Invalid frontmatter format (missing closing ---)", None

    frontmatter_text = match.group(1)
    body = content[match.end():].strip()

    # Minimal YAML parser for flat key: value pairs (sufficient for skill frontmatter)
    frontmatter = {}
    lines = frontmatter_text.split("\n")
    i = 0
    while i < len(lines):
        line = lines[i]
        if not line.strip() or line.strip().startswith("#"):
            i += 1
            continue

        # Match key: value
        key_match = re.match(r"^([a-zA-Z][a-zA-Z0-9_-]*)\s*:\s*(.*)", line)
        if not key_match:
            i += 1
            continue

        key = key_match.group(1)
        value_raw = key_match.group(2).strip()

        # Folded/literal scalar (> or |)
        if value_raw in (">", "|", ">-", "|-"):
            scalar_lines = []
            i += 1
            while i < len(lines) and (lines[i].startswith("  ") or lines[i].strip() == ""):
                scalar_lines.append(lines[i].strip())
                i += 1
            if value_raw.startswith(">"):
                frontmatter[key] = " ".join(scalar_lines).strip()
            else:
                frontmatter[key] = "\n".join(scalar_lines).strip()
            continue

        # Quoted string
        if value_raw.startswith("'") and value_raw.endswith("'"):
            frontmatter[key] = value_raw[1:-1]
        elif value_raw.startswith('"') and value_raw.endswith('"'):
            frontmatter[key] = value_raw[1:-1]
        elif value_raw.lower() == "true":
            frontmatter[key] = True
        elif value_raw.lower() == "false":
            frontmatter[key] = False
        elif value_raw == "":
            frontmatter[key] = None
        else:
            frontmatter[key] = value_raw

        i += 1

    return frontmatter, None, body


def validate_skill(skill_path, strict=False):
    """
    Validate an OpenClaw skill directory.

    Returns a dict: {"valid": bool, "errors": [{"field": str, "message": str, "severity": str}]}
    Severity levels: "critical", "major", "minor"
    """
    skill_path = Path(skill_path).expanduser().resolve()
    errors = []

    def add(field, message, severity="major"):
        errors.append({"field": field, "message": message, "severity": severity})

    # Check SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        add("SKILL.md", "SKILL.md not found", "critical")
        return {"valid": False, "errors": errors}

    content = skill_md.read_text()

    # Parse frontmatter
    frontmatter, parse_error, body = parse_frontmatter(content)
    if parse_error:
        add("frontmatter", parse_error, "critical")
        return {"valid": False, "errors": errors}

    if not isinstance(frontmatter, dict):
        add("frontmatter", "Frontmatter must be a YAML dictionary", "critical")
        return {"valid": False, "errors": errors}

    # Check for Claude Code-only fields (invalid in OpenClaw)
    for field, reason in CLAUDE_CODE_FIELDS.items():
        if field in frontmatter:
            add(
                field,
                f"'{field}' is a Claude Code-only field and is not valid in OpenClaw ({reason})",
                "critical",
            )

    # Check for unexpected fields
    unexpected = set(frontmatter.keys()) - ALLOWED_FRONTMATTER - set(CLAUDE_CODE_FIELDS.keys())
    if unexpected:
        add(
            "frontmatter",
            f"Unrecognized frontmatter field(s): {', '.join(sorted(unexpected))}",
            "major",
        )

    # Required fields
    if "name" not in frontmatter:
        add("name", "Missing required 'name' field", "critical")
    if "description" not in frontmatter:
        add("description", "Missing required 'description' field", "critical")

    # Validate name
    name = frontmatter.get("name", "")
    if isinstance(name, str):
        name = name.strip()
        if name:
            if not re.match(r"^[a-z0-9-]+$", name):
                add("name", f"Name '{name}' must be hyphen-case (lowercase, digits, hyphens only)", "critical")
            elif name.startswith("-") or name.endswith("-") or "--" in name:
                add("name", f"Name '{name}' cannot start/end with hyphen or have consecutive hyphens", "major")
            elif len(name) > MAX_SKILL_NAME_LENGTH:
                add("name", f"Name too long ({len(name)} chars). Max: {MAX_SKILL_NAME_LENGTH}", "major")
    elif name is not None:
        add("name", f"'name' must be a string, got {type(name).__name__}", "critical")

    # Validate description
    description = frontmatter.get("description", "")
    if isinstance(description, str):
        description = description.strip()
        if description:
            if len(description) > 1024:
                add("description", f"Description too long ({len(description)} chars). Max: 1024", "major")
            if "[TODO" in description:
                add("description", "Description contains TODO placeholder — please complete it", "major")
    elif description is not None:
        add("description", f"'description' must be a string, got {type(description).__name__}", "major")

    # Validate metadata: must be parseable as JSON (not multi-line YAML mapping)
    metadata_raw = frontmatter.get("metadata")
    if metadata_raw is not None:
        if isinstance(metadata_raw, str):
            try:
                json.loads(metadata_raw)
            except json.JSONDecodeError as e:
                add(
                    "metadata",
                    f"'metadata' must be a single-line JSON string parseable as JSON. Error: {e}. "
                    "Multi-line YAML mappings under metadata are not valid in OpenClaw.",
                    "critical",
                )
        elif isinstance(metadata_raw, dict):
            # Parsed as YAML dict — this means it was written as multi-line YAML, which is invalid
            add(
                "metadata",
                "'metadata' was parsed as a YAML mapping (multi-line). "
                "OpenClaw requires metadata to be a single-line JSON string: "
                "metadata: '{\"openclaw\": {\"emoji\": \"🔧\"}}'",
                "critical",
            )
        else:
            add("metadata", f"'metadata' must be a JSON string, got {type(metadata_raw).__name__}", "major")

    # Validate command-dispatch and command-tool consistency
    has_dispatch = "command-dispatch" in frontmatter
    has_tool = "command-tool" in frontmatter
    if has_dispatch and not has_tool:
        add("command-tool", "'command-dispatch' is set but 'command-tool' is missing", "major")
    if has_tool and not has_dispatch:
        add("command-dispatch", "'command-tool' is set but 'command-dispatch' is missing", "minor")

    # Check body
    if not body:
        add("body", "SKILL.md body is empty", "major")
    elif "[TODO" in body:
        add("body", "SKILL.md body contains TODO placeholders — please complete them", "major")
    else:
        # Strip inline code spans (content between backtick pairs) before scanning —
        # a checklist item saying "do not use `Bash`" should not trigger a Bash violation.
        body_no_code = re.sub(r"`[^`\n]+`", "", body)

        # Warn if Claude Code tool names appear in body outside of code spans
        for tool_name in CLAUDE_CODE_TOOLS:
            pattern = rf'\b{re.escape(tool_name)}\b'
            if re.search(pattern, body_no_code):
                add(
                    "body",
                    f"Body references Claude Code tool '{tool_name}'. "
                    f"Use the OpenClaw equivalent instead (see references/claw-patterns.md).",
                    "minor",
                )

        # Check for $CLAUDE_PLUGIN_ROOT usage outside of code spans
        if "$CLAUDE_PLUGIN_ROOT" in body_no_code:
            add(
                "body",
                "Body uses '$CLAUDE_PLUGIN_ROOT' (Claude Code path convention). "
                "Use '{baseDir}' instead for OpenClaw skill-relative paths.",
                "major",
            )

    valid = not any(e["severity"] in ("critical", "major") for e in errors)
    return {"valid": valid, "errors": errors}


def format_text_output(result, skill_path):
    lines = [f"Validating: {skill_path}"]
    if result["valid"]:
        lines.append("[OK] Skill is valid")
    else:
        lines.append("[FAIL] Skill has validation errors")

    for e in result["errors"]:
        prefix = "[ERROR]" if e["severity"] in ("critical", "major") else "[WARN]"
        lines.append(f"  {prefix} [{e['severity'].upper()}] {e['field']}: {e['message']}")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Validate an OpenClaw skill directory",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument("skill_directory", help="Path to skill directory containing SKILL.md")
    parser.add_argument(
        "--output",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    parser.add_argument(
        "--strict",
        action="store_true",
        help="Treat minor issues as errors (affects exit code)",
    )
    args = parser.parse_args()

    result = validate_skill(args.skill_directory, strict=args.strict)

    if args.output == "json":
        print(json.dumps(result, indent=2))
    else:
        print(format_text_output(result, args.skill_directory))

    if args.strict:
        success = len(result["errors"]) == 0
    else:
        success = result["valid"]

    sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()