zsxq-skill: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

zsxq-skill is the official skill package for zsxq-cli (知识星球 CLI). It contains documentation-only skill definitions — no application code, no build system, no tests. All files are Markdown (scenario scripts under scripts/, when added, are the only executable code).

The skill is consumed by AI agents (Claude Code, Codex, Cursor, OpenClaw) to learn how to operate the 知识星球 platform via zsxq-cli.

Codex/Cursor/OpenClaw 等 agent 通过 AGENTS.md 指向本文件；本文件是面向所有 agent 的唯一开发指南，文中 "Claude Code" 可泛指当前所用 agent。

Architecture

只发布一个 zsxq skill：

skills/zsxq/
├── SKILL.md                 # 触发、执行模式路由、能力索引、全局安全规则
├── references/
│   ├── auth-errors.md       # 认证、通用错误表、CLI 未安装恢复
│   ├── cli-exploration.md   # 探索模式：--help / api list / api call / api raw
│   ├── share-links.md       # 分享链接拼接模板
│   ├── <domain>-<verb>.md   # 原子操作 reference（group-list、topic-create …）
│   └── scenarios/
│       └── <scenario-id>.md # 场景入口（如 migrate-legacy-skills.md）
├── scripts/scenarios/<scenario-id>/   # 场景脚本（确定性代码，按需）
└── assets/scenarios/<scenario-id>/    # 场景模板/静态资源（按需）

• SKILL.md 只负责触发、路由、能力索引和全局安全规则；命令细节全部在 reference 按需加载
• 场景目录中不得创建 SKILL.md，避免被识别为独立 skill

执行模式（写文档时须维持这个路由结构）

命中场景 -> 按场景入口文档编排
否则命中原子操作 -> 读对应 reference 直接执行
否则 -> 探索模式（cli-exploration.md）

原子操作和场景执行时不得预先运行无关的 doctor、--help 或 api list；仅在能力不匹配或调用失败时回退到探索模式。

Key Conventions

SKILL.md frontmatter format

---
name: zsxq
description: "触发描述（中文，含关键词以便 AI 匹配触发；上限 1024 字符）"
metadata:
  version: "3.0.0"
  channels: "cli（zsxq-cli，优先）/ mcp（call_zsxq_api，兜底）"
  cliHelp: "zsxq-cli --help"
---

frontmatter 须符合 Agent Skills 规范：name 小写连字符且与目录同名；description ≤1024 字符；metadata 为 string→string 扁平映射（不要嵌套对象/数组）。仓库根另有 plugin.json 遵循 Agent Plugins 规范。

description 字段直接决定 AI 何时触发该 skill，修改时确保包含所有相关操作的关键词（含场景触发语）。