Add CI, MIT license, and Claude Code usage docs

Author: GloriaGuo

.github/workflows/validate.yml

@@ -0,0 +1,25 @@
+name: Validate Skill
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: python3 -m pip install pyyaml
+
+      - name: Validate skill
+        run: python3 scripts/validate_skill.py

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GloriaGuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -44,6 +44,8 @@ This skill gives Codex a read-first, agent-safe operating path so it can:
 - [references/practical-scenarios.md](./references/practical-scenarios.md): detailed scenario manual
 - [references/troubleshooting.md](./references/troubleshooting.md): common failures and fixes
 - [examples/README.md](./examples/README.md): example prompts and command recipes
+- [examples/claude-code.md](./examples/claude-code.md): Claude Code installation and prompt examples
+- [scripts/validate_skill.py](./scripts/validate_skill.py): portable validation script for CI and local checks
 
 ## Install
 
@@ -59,6 +61,44 @@ Or copy the folder contents manually into:
 ${CODEX_HOME:-$HOME/.codex}/skills/opencli
 ```
 
+## Use In Codex
+
+Once installed, ask Codex naturally or invoke the skill explicitly:
+
+```text
+Use $opencli to inspect the installed OpenCLI surface and fetch the Bilibili hot list.
+```
+
+```text
+Use $opencli to troubleshoot why my Zhihu command returns empty data.
+```
+
+Codex-oriented installation path:
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/opencli"
+```
+
+## Use In Claude Code
+
+Claude Code skills typically live under `~/.claude/skills`. Copy or clone this repository there:
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git ~/.claude/skills/opencli
+```
+
+Then ask Claude Code in natural language or reference the skill explicitly:
+
+```text
+Use $opencli to run a safe read-first OpenCLI workflow for this task.
+```
+
+```text
+Use $opencli to inspect the local OpenCLI setup and tell me whether the Codex and Cursor adapters are available.
+```
+
+Claude Code usage examples are collected in [examples/claude-code.md](./examples/claude-code.md).
+
 ## Recommended OpenCLI Setup
 
 ```bash
@@ -115,7 +155,7 @@ opencli bilibili download BV1xxx --output ./bilibili
 ## Validation
 
 ```bash
-python3 /Users/ruiguo/.codex/skills/.system/skill-creator/scripts/quick_validate.py .
+python3 scripts/validate_skill.py
 ```
 
 ## 中文说明
@@ -145,6 +185,8 @@ python3 /Users/ruiguo/.codex/skills/.system/skill-creator/scripts/quick_validate
 - [references/practical-scenarios.md](./references/practical-scenarios.md)：详细实用场景手册
 - [references/troubleshooting.md](./references/troubleshooting.md)：常见故障排查
 - [examples/README.md](./examples/README.md)：可直接照抄的 prompt 和命令示例
+- [examples/claude-code.md](./examples/claude-code.md)：Claude Code 安装与调用示例
+- [scripts/validate_skill.py](./scripts/validate_skill.py)：本地与 CI 通用的校验脚本
 
 ## 安装方式
 
@@ -158,6 +200,44 @@ git clone git@github.com:GloriaGuo/opencli-skill.git "${CODEX_HOME:-$HOME/.codex
 ${CODEX_HOME:-$HOME/.codex}/skills/opencli
 ```
 
+## 在 Codex 里怎么用
+
+安装后，可以自然描述任务，也可以显式提到 `$opencli`：
+
+```text
+Use $opencli to inspect the installed OpenCLI surface and fetch the Bilibili hot list.
+```
+
+```text
+Use $opencli to troubleshoot why my Zhihu command returns empty data.
+```
+
+Codex 默认安装路径：
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/opencli"
+```
+
+## 在 Claude Code 里怎么用
+
+Claude Code 的 skill 通常放在 `~/.claude/skills` 下，可以这样安装：
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git ~/.claude/skills/opencli
+```
+
+然后直接用自然语言，或者显式提到 `$opencli`：
+
+```text
+Use $opencli to run a safe read-first OpenCLI workflow for this task.
+```
+
+```text
+Use $opencli to inspect the local OpenCLI setup and tell me whether the Codex and Cursor adapters are available.
+```
+
+更完整的 Claude Code 示例见 [examples/claude-code.md](./examples/claude-code.md)。
+
 ## 推荐的 OpenCLI 环境准备
 
 ```bash
@@ -210,3 +290,9 @@ opencli bilibili download BV1xxx --output ./bilibili
 - 以本机安装版本的命令面为准，不盲信旧文档
 - agent 消费优先 `json`，人工查看优先 `yaml`
 - 浏览器登录态是第一优先级依赖
+
+## 校验
+
+```bash
+python3 scripts/validate_skill.py
+```

examples/README.md

@@ -3,4 +3,5 @@
 This folder contains practical prompts and command recipes you can copy into Codex or run directly.
 
 - [agent-prompts.md](./agent-prompts.md): user-style prompts that should trigger the skill
+- [claude-code.md](./claude-code.md): Claude Code installation and invocation examples
 - [command-recipes.md](./command-recipes.md): reusable command recipes grouped by workflow

examples/claude-code.md

@@ -0,0 +1,73 @@
+# Claude Code Usage
+
+This document shows how to install and use the OpenCLI skill in Claude Code.
+
+## Install
+
+Clone this repository into Claude Code's skills directory:
+
+```bash
+git clone git@github.com:GloriaGuo/opencli-skill.git ~/.claude/skills/opencli
+```
+
+If the folder already exists, update it:
+
+```bash
+cd ~/.claude/skills/opencli
+git pull
+```
+
+## Triggering The Skill
+
+Claude Code can often pick the skill from context, but explicit invocation is more reliable:
+
+```text
+Use $opencli to inspect the local OpenCLI setup and run the correct command.
+```
+
+## Example Prompts
+
+### Browser-backed sites
+
+```text
+Use $opencli to fetch the top 10 Bilibili hot videos as JSON.
+```
+
+```text
+Use $opencli to search Zhihu for "Android 性能优化" and summarize the top results.
+```
+
+### Desktop adapters
+
+```text
+Use $opencli to inspect the local OpenCLI setup and tell me whether Codex and Cursor adapters are available.
+```
+
+```text
+Use $opencli to read the current Codex desktop conversation and summarize the latest progress.
+```
+
+### Troubleshooting
+
+```text
+Use $opencli to diagnose why my browser-backed command is returning empty data.
+```
+
+```text
+Use $opencli to compare the installed OpenCLI command surface with the README and tell me what is actually available.
+```
+
+## Recommended Prompt Pattern
+
+The most reliable structure is:
+
+1. mention `$opencli`
+2. describe the target site or app
+3. state the expected output format or outcome
+4. ask for read-first behavior if the task could become write-capable
+
+Example:
+
+```text
+Use $opencli to inspect the installed command surface, then run a read-first workflow against Zhihu and return JSON only.
+```

scripts/validate_skill.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Portable validator for this skill repository."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+try:
+    import yaml
+except ImportError as exc:  # pragma: no cover
+    print(f"Missing dependency: {exc}. Install with `python3 -m pip install pyyaml`.")
+    sys.exit(1)
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SKILL = ROOT / "SKILL.md"
+OPENAI_YAML = ROOT / "agents" / "openai.yaml"
+
+
+def fail(message: str) -> None:
+    print(f"ERROR: {message}")
+    sys.exit(1)
+
+
+def load_frontmatter(text: str) -> dict:
+    if not text.startswith("---\n"):
+        fail("SKILL.md is missing YAML frontmatter.")
+    parts = text.split("---\n", 2)
+    if len(parts) < 3:
+        fail("SKILL.md frontmatter is malformed.")
+    return yaml.safe_load(parts[1]) or {}
+
+
+def main() -> None:
+    if not SKILL.exists():
+        fail("SKILL.md not found.")
+    if not OPENAI_YAML.exists():
+        fail("agents/openai.yaml not found.")
+
+    frontmatter = load_frontmatter(SKILL.read_text())
+    allowed_keys = {"name", "description"}
+    extra = set(frontmatter) - allowed_keys
+    if extra:
+        fail(f"Unexpected frontmatter keys: {sorted(extra)}")
+
+    if not frontmatter.get("name"):
+        fail("Frontmatter `name` is required.")
+    if not frontmatter.get("description"):
+        fail("Frontmatter `description` is required.")
+
+    if not str(frontmatter["name"]).replace("-", "").isalnum():
+        fail("Frontmatter `name` must use letters, digits, and hyphens only.")
+
+    openai = yaml.safe_load(OPENAI_YAML.read_text()) or {}
+    interface = openai.get("interface", {})
+    for key in ("display_name", "short_description", "default_prompt"):
+        if not interface.get(key):
+            fail(f"`agents/openai.yaml` is missing interface.{key}")
+
+    print("Skill is valid!")
+
+
+if __name__ == "__main__":
+    main()