# 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

```bash
# 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 |