docs: standardize skill-template and add development guide

scripts/util/argparse_zh.py

@@ -0,0 +1,12 @@
+"""argparse 中文错误说明。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+class ZhArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        print(f"参数错误：{message}\n请执行：python main.py -h 查看帮助", file=sys.stderr)
+        self.exit(2)

scripts/util/constants.py

@@ -0,0 +1,5 @@
+"""技能标识与版本（复制后请修改）。"""
+
+SKILL_SLUG = "your-skill-slug"
+SKILL_VERSION = "1.0.0"
+LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"

scripts/util/logging_config.py

@@ -0,0 +1,21 @@
+"""Re-export unified logging (implementation: jiangchang_skill_core.unified_logging)."""
+
+from jiangchang_skill_core.unified_logging import (
+    attach_unified_file_handler,
+    ensure_trace_for_process,
+    get_skill_log_file_path,
+    get_skill_logger,
+    get_unified_logs_dir,
+    setup_skill_logging,
+    subprocess_env_with_trace,
+)
+
+__all__ = [
+    "attach_unified_file_handler",
+    "ensure_trace_for_process",
+    "get_skill_log_file_path",
+    "get_skill_logger",
+    "get_unified_logs_dir",
+    "setup_skill_logging",
+    "subprocess_env_with_trace",
+]

scripts/util/runtime_paths.py

@@ -0,0 +1,34 @@
+"""数据根、技能目录、兄弟技能根路径。"""
+
+from __future__ import annotations
+
+import os
+
+from jiangchang_skill_core.runtime_env import get_data_root, get_sibling_skills_root, get_user_id
+
+from util.constants import SKILL_SLUG
+
+_SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def get_skill_root() -> str:
+    return os.path.dirname(_SCRIPTS_DIR)
+
+
+def get_openclaw_root() -> str:
+    return get_sibling_skills_root(_SCRIPTS_DIR)
+
+
+def get_skills_root() -> str:
+    return get_sibling_skills_root(_SCRIPTS_DIR)
+
+
+def get_skill_data_dir() -> str:
+    path = os.path.join(get_data_root(), get_user_id(), SKILL_SLUG)
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def get_db_path(filename: str | None = None) -> str:
+    name = filename or f"{SKILL_SLUG}.db"
+    return os.path.join(get_skill_data_dir(), name)

scripts/util/timeutil.py

@@ -0,0 +1,20 @@
+"""时间戳与 ISO 展示。"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Optional
+
+
+def now_unix() -> int:
+    return int(time.time())
+
+
+def unix_to_iso(ts: Optional[int]) -> Optional[str]:
+    if ts is None:
+        return None
+    try:
+        return datetime.fromtimestamp(int(ts)).isoformat(timespec="seconds")
+    except (ValueError, OSError, OverflowError):
+        return None