feat(skills): add opencli-skill and document Codex/Cursor/Claude Code integration

[shouldnotappearcalm]

Overview

This PR packages OpenCLI platform knowledge into a reusable skill layout and documents how to wire it into common agent environments.

Included in this PR

• Introduce skills/opencli-skill/ as the canonical skill package.
• Add SKILL.md as the routing/usage entrypoint for agent execution.
• Add per-platform references in references/commands/*.md as the command knowledge base.
• Update docs for practical agent onboarding:
  • Codex (~/.codex/skills)
  • Cursor (.cursor/rules/*.mdc, with legacy .cursorrules compatibility)
  • Claude Code (CLAUDE.md, optional .claude/commands)
• Align repo references to the new skill path/name.
• Clean malformed/truncated command-reference text to improve reliability.

Why

OpenCLI already exposes broad platform coverage, but agents need a deterministic, loadable interface.
opencli-skill provides that interface and standardizes how agents discover commands, required args, and expected usage patterns.

Scope

• Skill package + documentation updates only
• No runtime behavior changes to OpenCLI core execution paths

[shouldnotappearcalm]

add douyin, jd, linkedin, pixiv, web.

[Astro-Han]

A few structural concerns before diving into individual files:

1. Path mismatch in root SKILL.md

The diff adds a "Skill Package in Repo" section to SKILL.md pointing to skills/opencli-platform-router/, but the actual directory created is skills/opencli-skill/. These don't match.

2. README Claude Code section overwrites existing CLAUDE.md

The suggested cat > CLAUDE.md <<'EOF' command would overwrite the repo's existing CLAUDE.md (which contains adapter development rules, the CLI-EXPLORER reference, etc.). Should be append or a separate file.

3. Duplicate command reference with no auto-generation

The root SKILL.md already has a comprehensive command reference. This PR adds 63 hand-written markdown files that duplicate that information in a different format. Without a generation script, these will drift out of sync every time a command is added or changed. A script that generates from adapter source (or --help output) would make this sustainable.

4. Source file changes in a docs-only PR

src/build-manifest.ts and src/validate.ts have blank-line removals. Minor, but the PR description says "No runtime behavior changes to OpenCLI core execution paths", so source files shouldn't be touched.

[Astro-Han]

Follow-up to my earlier review: this is not just a future drift risk, the new skill command reference is already incomplete in this PR.

I compared the new skills/opencli-skill/references/commands/*.md files against the commands currently exposed under src/clis/, and several platform docs are already missing valid commands from the current tree:

• weibo.md only lists hot and search, but src/clis/weibo/ also has comments, feed, me, post, and user
• youtube.md is missing channel, comments, and transcript-group
• twitter.md is missing likes
• xiaohongshu.md is missing comments
• xueqiu.md is missing fund-holdings and fund-snapshot

So the problem here is stronger than "these docs may drift later": they already cannot be treated as the canonical command reference for agents, because an agent following these docs today would conclude that some real commands do not exist.

[shouldnotappearcalm]

@Astro-Han

1. Path Mismatch in Root SKILL.md

Status: ✅ Fixed

Root SKILL.md now points to the actual paths:

• skills/opencli-skill/SKILL.md
• skills/opencli-skill/references/commands/*.md

---

2. README → CLAUDE.md Overwrite Risk

Status: ✅ Fixed

Updated both README.md and README.zh-CN.md:

• Changed from overwrite mode (cat > CLAUDE.md) to append mode (cat >> CLAUDE.md)
• Added a scoped section header to avoid clobbering existing project guidance

---

3. Duplicate Command Reference Drift

Status: ✅ Fixed

Implemented source-driven generation + checks:

• Added script(s) to generate command docs from src/clis/*
• Added generation for skills/opencli-skill/SKILL.md platform coverage/description from source adapters
• Added npm run skill:sync and npm run skill:check
• Added CI workflow to enforce sync on PR/push (.github/workflows/skill-docs-check.yml)

Command references are no longer hand-maintained and should not drift from source.

---

4. Source File Changes in Docs-Focused PR

Status: ✅ Cleaned Up

• No runtime logic changes were introduced
• src/build-manifest.ts and src/validate.ts edits were reduced to formatting-only rollback consistency (blank-line restoration)
• No behavior changes

[shouldnotappearcalm]

@Astro-Han

Hi, thanks for the thorough review! All 4 structural concerns have been addressed in the latest update:

1. Path mismatch in root SKILL.md — Fixed to point to the correct actual paths.
2. CLAUDE.md overwrite risk — Switched to append mode with a scoped section header.
3. Command reference drift — Implemented source-driven generation with skill:sync / skill:check scripts and a CI workflow to enforce sync.
4. Source file changes in a docs-focused PR — Cleaned up to formatting-only changes with no behavior impact.

Beyond the fixes, I've also built out the auto-generation logic for skill content — command references and SKILL.md descriptions are now derived directly from source adapters, so they stay in sync automatically.

Would you mind taking a look and letting me know if the approach seems reasonable? Happy to adjust if needed.