skill-template/CLAUDE.md

CLAUDE.md

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

What This Repo Is

OpenClaw is a monorepo of installable "Skills" (plugins) for the Claw agent hosting platform (深圳匠厂科技). Each subdirectory is an independent skill that ships as an encrypted ZIP to jc2009.com and gets installed by a desktop/gateway host.

Each skill is independently versioned and can have its own git remote (http://120.25.191.12:3000/admin/<slug>.git). The root .git tracks only the skill-template scaffold.

Running Skills

No build step — all skills are plain Python 3.10+. Run directly:

# Health / version check (every skill exposes these)
python scripts/skill_main.py health
python scripts/skill_main.py version

# Account manager
python account-manager/scripts/main.py list all
python account-manager/scripts/main.py add "搜狐号" "13800138000"

# Content manager
python content-manager/scripts/main.py get <id>

# API key vault
python api-key-vault/scripts/vault.py get 17track

# Logistics
python logistics-tracker/scripts/main.py <tracking_number>

# Sohu publish
python sohu-publisher/scripts/main.py <account_id> <article_id>

Releasing a Skill

From the skill's directory:

.\release.ps1            # tag + push
.\release.ps1 -DryRun    # preview only
.\release.ps1 -AutoCommit -CommitMessage "Release v1.0.5"

This delegates to jiangchang-platform-kit/tools/release.ps1, creates a semver git tag, and triggers the GitHub Actions workflow that encrypts scripts via PyArmor, packs a ZIP, and syncs metadata to jc2009.com.

Architecture

Skill Structure

Every skill directory contains:

• SKILL.md — YAML frontmatter (name, version, slug, category, dependencies, allowed-tools) + Markdown body with usage triggers and env requirements. Version here must stay in sync with the git tag.
• scripts/ — Python entry points
• release.ps1 — delegates to platform kit

Environment Contract (CLAW_*)

Skills locate user data via env vars:

Variable	Purpose	Dev default
CLAW_DATA_ROOT	User data root	D:\claw-data or ~/.claw-data
CLAW_USER_ID	Workspace ID	_anon
CLAW_SKILLS_ROOT	Sibling skills dir	Parent of skill dir

Legacy aliases (JIANGCHANG_DATA_ROOT, etc.) are still detected; prefer CLAW_* in new code.

Data path convention: {CLAW_DATA_ROOT}/{CLAW_USER_ID}/{slug}/ (SQLite DBs, cache, temp).

Skill Types

Type	Pattern	Examples
A	Stateless tool	logistics-tracker
B	Local persistent (SQLite)	account-manager, content-manager, api-key-vault
C	Orchestrator (calls sibling skills via subprocess)	—
D	Hybrid (B + C)	sohu-publisher

Type C/D skills declare dependencies.required in SKILL.md and call siblings like:

subprocess.run(["python", f"{skills_root}/account-manager/scripts/main.py", ...])

Shared Platform Kit (jiangchang-platform-kit/)

• sdk/jiangchang_skill_core — EntitlementClient, enforce_entitlement (license checks)
• .github/workflows/reusable-release-skill.yaml — reusable CI called by every skill's release workflow
• tools/release.ps1 — shared release script

CLI Conventions

• Subcommands: health (offline quick check, exits 0/1), version (JSON output), custom actions
• Success prefix: OK or plain output
• Error prefix: ERROR: (e.g., ERROR:REQUIRE_LOGIN)
• Windows GBK fix: wrap stdout/stderr with io.TextIOWrapper(..., encoding='utf-8')

Key Docs

File	What it covers
skill-template/README.md	Onboarding, anti-patterns
skill-template/docs/RUNTIME.md	Full env var contract and fallback behavior
skill-template/docs/SKILL_TYPES.md	Type A–D classification checklist
skill-template/docs/PORTABILITY.md	Cross-platform encoding, path differences
skill-template/docs/LOGGING.md	TimedRotatingFileHandler setup

Known Dev-Mode Issues

• account-manager/scripts/main.py has _ACCOUNT_MANAGER_CLI_LOCAL_DEV = True hardcoded with a fixed data path (D:\jiangchang-data) and user ID — disable before releasing.
• toutiao-publisher is a placeholder stub; publish logic is not yet implemented.