skill-convertor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SGClaw Skill Converter — Go CLI + Web tool that converts JavaScript browser scripts into SGClaw-compatible skill packages. Single-file Go application (main.go) with a static web frontend (web/).

Build & Run

# Build
go build -o sgclaw-skill-converter.exe .

# CLI usage
go run . --js-script-path path/to/script.js --skill-name my-skill --write

# Web server
go run . --serve --host 127.0.0.1 --port 8787

# CLI with inline script
go run . --js-script-code "return {data: []}" --skill-name demo --skill-domain www.example.com --use-ai

No external dependencies — uses only Go standard library (go 1.22, zero third-party packages).

Architecture

Everything is in main.go (~1100 lines). Key functions:

• generateSkillPackage() — Core conversion orchestrator. Reads JS script, resolves defaults, optionally calls AI, generates TOML/MD/notes, writes to disk.
• callAI() — Sends script metadata to GLM-5.1 (OpenAI-compatible /chat/completions endpoint) to auto-generate skill metadata, descriptions, and documentation.
• scanRisk() — Pattern-based security scanner checking for shell commands, network requests, XPath usage, and missing return/throw.
• inferArgsFromScript() / inferArtifactFields() — Regex-based inference of script parameters and output fields.
• buildSkillToml() / buildSkillMD() — Template generators for SKILL.toml and SKILL.md when AI is disabled.
• runServer() — HTTP server with routes: GET /api/config, POST /api/convert, static file serving from web/.

Data Flow

CLI flags or Web POST payload → generateSkillPackage() → read/infer script metadata → optional AI enhancement → generate 5 files (SKILL.toml, SKILL.md, scripts/*.js, references/implementation-notes.md, assets/notes.md) → write to skills/<name>/ if --write.

AI Config Resolution (priority order)

1. Per-request overrides (web payload ai_config)
2. Environment variables: GLM_API_KEY, GLM_BASE_URL, GLM_MODEL, GLM_TIMEOUT
3. Fallback env vars: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, ANTHROPIC_DEFAULT_OPUS_MODEL
4. ~/.claude/settings.json (reads env/envs/environment sections)
5. Defaults: glm-5.1 model, https://open.bigmodel.cn/api/paas/v4

Skill Package Structure

Generated output follows SGClaw conventions:

skills/<skill_name>/
├── SKILL.toml          # Skill config (name, tools, args, kind=browser_script)
├── SKILL.md            # Human-readable documentation
├── scripts/<tool>.js   # The browser script (preserved as-is)
├── references/implementation-notes.md
└── assets/notes.md

Key constraints from the spec (docs/superpowers/specs/skill-generator-规范.md):

• Scripts must end with return <payload> or throw Error
• No network requests, shell commands, or XPath in scripts
• expected_domain is a bare hostname, declared in contract not injected into script
• CSS selectors only, no jQuery :contains

Key CLI Flags

Flag	Purpose
--js-script-path	Script file path (alternative to --js-script-code)
--js-script-code	Inline JS code
--skill-name	Output skill name (kebab-case)
--skill-domain	Target domain (bare hostname)
--tool-name	Tool name (snake_case)
--arg-spec	Params as k=v,k2=v2, JSON string, or @json_file
--preferred-mode	compact (default) or full
--write	Write files to disk
--no-ai	Disable AI enhancement
--serve	Start web server