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)

Per-request overrides (web payload ai_config)
Environment variables: GLM_API_KEY, GLM_BASE_URL, GLM_MODEL, GLM_TIMEOUT
Fallback env vars: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, ANTHROPIC_DEFAULT_OPUS_MODEL
~/.claude/settings.json (reads env/envs/environment sections)
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

3.6 KiB Raw Permalink Blame History