ljg-skills 仓库 CLAUDE.md 全解：面向 Claude Code 的自包含技能集架构、格式规范与开发维护指南

【免费下载链接】ljg-skills项目地址https://gitcode.com/gh_mirrors/lj/ljg-skills点击查看免费下载本文以仓库根目录下的 CLAUDE.md 为骨架系统讲解 ljg-skills 这个个人 Claude Code 技能仓库的目录结构、SKILL.md 技能格式、安装命令、调用架构与开发维护流程。读完本文你将掌握如何阅读和理解本仓库的每一个技能目录、如何把技能安装到本机 Claude Code/Codex 环境以及如何按照仓库既定约定新增、测试和发布一个自包含技能。这份 CLAUDE.md 是给谁看的仓库根目录的 CLAUDE.md 是一份面向 Claude Codeclaude.ai/code 的编码 Agent的仓库引导文件当 Claude Code 在本仓库内工作时会优先读取它从而理解这里是什么、技能怎么组织、怎么安装、怎么调用、改动后怎么测试。它的定位不是面向最终用户的营销文档而是一份工程契约——规定了技能仓库的结构、技能文件的格式、共享的架构约定与开发红线。因此本文也以同样的工程视角展开先讲结构再讲格式最后讲架构与维护。仓库总体结构一切皆自包含技能目录CLAUDE.md 在 Overview 中首先声明了仓库的本质这是一个个人 Claude Code 技能仓库每个技能都是一个自包含目录可以被安装到~/.claude/skills/下从而扩展 Claude Code 的能力。随后它给出了标准目录树ljg-skills/ ├── ljg-*/ # Each skill is a directory with ljg- prefix │ ├── SKILL.md # Skill definition with YAML frontmatter │ ├── references/ # Reference docs for complex skills │ ├── assets/ # Templates, images, scripts │ └── scripts/ # Helper scripts (bash, node) ├── README.md └── .gitignore # Ignores everything except ljg-*/ and specific files对照仓库实际内容这一结构完全成立且能进一步补充三层细节技能目录统一以ljg-前缀命名。当前仓库共包含 23 个技能目录全部位于 skills/ 下如skills/ljg-card、skills/ljg-paper、skills/ljg-plain、skills/ljg-word。CLAUDE.md 顶部画的ljg-*顶层目录在仓库中实际统一收纳在skills/子目录中这是 README 与 CLAUDE.md 之间唯一需要互相印证的位置差异——安装时见下文需要把skills/整体同步到目标位置。技能目录内部四件套SKILL.md是技能定义含 YAML frontmatter 与正文指令references/存放复杂技能的参考文档assets/存放模板、图片与脚本scripts/存放辅助脚本。以最复杂的 skills/ljg-card 为例其assets/下有capture.ts、capture.test.ts、verify-full-text.ts、prepare-whiteboard-source.ts与四套 HTML 模板long_template.html、full_template.html、comic_template.html、whiteboard_template.htmlreferences/下有taste.md、image-generation.md、learning-design.md与四个 mode 文件——与 CLAUDE.md 的描述一一对应。仓库级配套文件除了 CLAUDE.md 与 README.md根目录还有 .gitignore、LICENSE、scripts/含 install.sh、sync-push.sh以及 .claude-plugin/ 插件清单plugin.json、marketplace.json。.gitignore 采用的策略值得专门说明默认忽略一切文件首行*仅通过!pattern显式放行根目录文档、.claude-plugin/、scripts/与skills/下的全部文件同时排除node_modules/、*.pyc、__pycache__/、*.log等构建产物。这保证了仓库里只保留技能与文档任何依赖安装或本地构建残留都不会被提交。技能格式SKILL.md 与 YAML frontmatterCLAUDE.md 明确规定每个SKILL.md都遵循同一结构——以 YAML frontmatter 开头后接 Markdown 正文--- name: skill-name description: What this skill does. Use when user says... user_invocable: true|false version: x.x.x --- # Skill content in markdown...四个 frontmatter 字段的工程含义如下均可从仓库真实技能文件中找到实例字段作用仓库实例name技能唯一标识也是被调用时的名字ljg-card、ljg-word、ljg-plaindescription技能做什么以及触发短语是 Agent 路由的关键skills/ljg-plain/SKILL.mdUse when user says 白话说, 说人话, 解释一下, plain, grokuser_invocable是否可由用户显式触发ljg-card为trueversion7.4.1ljg-paper未声明则不可显式调用version手工维护的版本号skills/ljg-word/SKILL.md 为1.0.1skills/ljg-plain/SKILL.md 为5.0.0从源码看description不仅是给人类读的一句话简介更承担着意图匹配职责Claude Code 会依据用户话语与description中的触发短语做匹配命中后才加载对应 SKILL.md。因此各技能的 description 都刻意写入了中英文双语的触发词例如 skills/ljg-card/SKILL.md 的铸, cast, 做成图, 做成卡片, 做成海报等。正文部分则是给 Agent 的完整执行指令。以 skills/ljg-word/SKILL.md 为例它规定了严格的三段式输出结构标题行 → 核心语义 → 一语道破并明确目标不是翻译而是让用户掌握这个词的深层含义和用法以 skills/ljg-plain/SKILL.md 为例正文用九条红线口语检验、零术语、短词优先、一句一事、具体、开头给理由、不填充、信任读者、诚实规定了改写下限。这说明 SKILL.md 的正文不是自由发挥的提示词而是一份可验收的执行规范。技能清单从 5 个核心技能到 23 个全量技能CLAUDE.md 给出了一个精炼的技能清单表格5 项聚焦于当时的核心技能及其外部依赖SkillPurposeExternal Dependenciesljg-cardContent → PNG visuals (long cards, infographs, posters)Node.js Playwrightljg-paperAcademic paper analysis pipelineNoneljg-plainPlain language rewriterNoneljg-wordEnglish word deep-diveNoneljg-writesWriting engine for thinking through ideasNone而 README.md 的技能表格则完整登记了当前仓库的全部 23 个技能覆盖了比 CLAUDE.md 清单更广的能力面ljg-blind盲区扫描、ljg-card内容铸卡、ljg-classic古文精读、ljg-learn概念解剖、ljg-paper论文阅读、ljg-book拆书、ljg-qa信息提问机、ljg-plain白话引擎、ljg-rank降秩引擎、ljg-constraint约束引擎、ljg-is理解引擎、ljg-map知识地图、ljg-think追本之箭、ljg-word单词精通、ljg-writes写作引擎、ljg-teach体验式教学、ljg-invest投资分析、ljg-read伴读、ljg-relationship关系分析、ljg-roundtable圆桌讨论、ljg-structure母题结构风洞、ljg-presentUnix 演讲设计、ljg-push推送引擎。其中ljg-push还承担了把本地~/.agents/skills/ljg-*一键同步回 GitHub 仓库master md 双分支的职责。两份清单共同说明一件事技能是原子化的能力单元彼此独立可单独安装。CLAUDE.md 清单可视为核心五件套README 表格则是完整的技能目录索引。安装与依赖管理ljg-card 的运行时依赖CLAUDE.md 指出唯一有外部依赖的技能是ljg-card——它依赖 Playwright 做截图捕获安装命令为cd ljg-card npm install npx playwright install chromium仓库中的 scripts/install.sh 就是这段逻辑的自动化脚本脚本先定位到skills/ljg-card目录检查package.json存在后依次执行npm install与npx playwright install chromium并在成功后打印提示。注意 CLAUDE.md 写作时描述截图脚本为assets/capture.js而当前仓库 skills/ljg-card/assets 下的实际实现已演进为 TypeScript 版本capture.ts配套capture.test.ts调用方式为bun assets/capture.ts html png width height [fullpage]依赖缺失时在技能目录内运行bun install bunx playwright install chromium即可补齐。面向用户的技能安装CLAUDE.md 给出了面向 Claude Code 用户的最简安装方式# Copy all skills to Claude Code mkdir -p ~/.claude/skills cp -r ljg-* ~/.claude/skills/而 README.md 则补充了两种更工程化的安装路径可一并参考skills CLI 安装推荐bunx skills add lijigang/ljg-skills -g -a codex --skill * -y全局安装全部技能到~/.agents/skills/--skill name可单装某个技能可重复使用--skill *安装全部#md后缀表示从md分支安装 Markdown 格式版本默认 master 分支为 org-mode 格式-l仅列出可用技能不安装。git clone 替代方案由于仓库根目录不是技能目录本身clone 后需要把skills/同步到目标位置例如git clone --branch master --depth 1后用rsync -a $HOME/code/ljg-skills/skills/ $HOME/.agents/skills/。无论哪种方式核心操作都是把技能目录复制/同步到 Agent 的技能目录——这与 CLAUDE.md 的语义完全一致只是目标目录随工具而异Claude Code 为~/.claude/skills/Codex 为~/.agents/skills/。架构说明技能如何被调用与处理内容技能调用机制CLAUDE.md 用三条规则概括了调用架构user_invocable: true的技能可以通过/skill-name斜杠命令或自然语言触发触发短语定义在每个技能的description字段中这正是上文强调 description 承担意图匹配的原因技能之间可以通过 Skill 工具互相调用——这为ljg-writes、ljg-plain这类组合型工作流提供了可能。内容处理管线多个技能共享同一条内容摄入模式CLAUDE.md 将其归纳为三种输入通道URL→ WebFetch例如 skills/ljg-plain/SKILL.md 的URL → WebFetch | 文本 → 直接用 | 文件路径 → Read | 概念 → 直接解释文件路径→ Read 工具原始文本→ 直接使用这条管线在技能正文中体现得相当彻底ljg-card 的输入与命名章节明确区分了 URL、粘贴文本、文件路径三种来源的处理方式ljg-paper 则按输入类型arXiv 链接、PDF、本地论文、只有标题路由到不同的必读材料组合。ljg-card 架构最复杂技能的样板CLAUDE.md 用四步概括了 ljg-card 的渲染架构这是仓库中架构最复杂的技能HTML 模板存放在assets/包括long_template.html、infograph_template.html、poster_template.html当前仓库实际为long_template.html、full_template.html、comic_template.html、whiteboard_template.html四套对应-l/-f/-c/-w四种模具截图脚本assets/capture.js现为capture.ts用 Playwright 把 HTML 截图为 PNG参考文档references/taste.md设计准则与references/mode-*.md各模式专属指令当前仓库还有image-generation.md与learning-design.md输出PNG 文件写入~/Downloads/最终交付物位置可由用户指定中间产物则必须写入/tmp下的任务独占临时目录。skills/ljg-card/SKILL.md 进一步把架构落实为可执行的共同生产线锁定来源与事实边界 → 建立视觉母题/论证账本 → 调用图像生成工具校准 → 保存并核对图片 → 将全部文字、数字、公式放入 HTML/CSS → 替换模板占位符 → 等待字体与图片加载后截图 → 整图与重叠切片 QA → 交付前内容审阅。它还包含一张 mode 路由表把四个参数精确映射到参考文档与模板参数mode 文件模板-lreferences/mode-long.mdassets/long_template.html-freferences/mode-full.mdassets/full_template.html-creferences/mode-comic.mdassets/comic_template.html-wreferences/mode-whiteboard.mdassets/whiteboard_template.html值得注意的是 ljg-card 的交付合同最终回复必须报告 PNG 绝对路径、像素尺寸、内容来源、使用的 mode、生成图数量以及整图/分段视觉 QA 结果——这体现了整个仓库指令 可验收的设计哲学。共享约定CLAUDE.md 记录了三条跨技能共享的硬性约定避免各技能风格漂移Org-mode 输出约定适用于 ljg-paper、ljg-plain、ljg-writes加粗用*text*单星号禁用**——skills/ljg-plain/SKILL.md 将其列为格式约束第一条文件名格式{timestamp}--{title}__{type}.org例如 ljg-paper 的 Denote 风格文件名{YYYYMMDDTHHMMSS}--paper-{方法名或论文关键词}__paper.org输出目录~/Documents/notes/时间戳由date %Y%m%dT%H%M%S生成可读时间用date %Y-%m-%d %a %H:%M。ASCII 图约定允许字符集 - | / \ v ^ * ~ . : # [ ] ( ) _ , ; ! 及空格禁止 Unicode 制表符绘图字符。ljg-plain 明确指出所有图表用纯 ASCII 字符这是为了保证任何终端与编辑器都能无损渲染。开发准则如何在这个仓库里新增与修改技能CLAUDE.md 的 Development Guidelines 定义了四条开发红线是维护本仓库时必须遵守的契约技能是原子单元——每个技能目录自包含不依赖目录外的文件保证可独立拷贝安装版本号手工维护——version字段在 SKILL.md 的 frontmatter 中手动递增不依赖自动工具仓库中ljg-card7.4.1、ljg-plain5.0.0、ljg-word1.0.1 等版本即手工标记的实例.gitignore 默认忽略一切——新增文件必须显式用!pattern放行否则不会被版本控制收录联动更新——修改技能逻辑时SKILL.md 与references/中被引用的文件必须同步更新避免指令与参考文档脱节。以 ljg-card 为例维护自检章节还给出了技能自身的回归保障命令bun run audit bun test bun run fixtures其中audit检查共享协议与四路引用test运行纯函数与反例测试fixtures则在/tmp/ljg-card-v7-fixtures/生成代表 HTML 并实际截图读回 PNG 验证渲染——这正好印证了 CLAUDE.md 中每个技能自包含 可验证的工程要求。改动后的测试流程CLAUDE.md 最后用三步定义了改完一个技能后怎么验收复制到~/.claude/skills/——把修改后的技能目录放入 Claude Code 的技能加载路径重启 Claude Code 以重载技能——技能在启动时加载改完不重启不会生效用自然语言或/skill-name触发测试——通过真实调用验证行为而非只做静态检查。这条流程与 ljg-card 的交付合同、ljg-paper 的独立阅读检查由未参与写作的新上下文评估最终笔记验证脚本只能检查格式与记录、不能证明易懂互为补充共同构成了仓库修改 → 安装 → 重载 → 实测的完整闭环。结语CLAUDE.md 用不到百行内容把一个个人技能仓库的工程全貌交代得清清楚楚自包含的目录结构、带 YAML frontmatter 的 SKILL.md 格式、可独立安装的原子技能、共享的内容处理管线与输出约定以及改完必须实测的开发纪律。它既是 Claude Code 理解本仓库的入口也是任何希望构建自己技能集的开发者可以对照的模板——理解了这份文档你就理解了 ljg-skills 仓库的全部组织逻辑也就能按同样的范式阅读、安装乃至创建自己的技能。赞分享【免费下载链接】ljg-skills项目地址https://gitcode.com/gh_mirrors/lj/ljg-skills点击查看免费下载相关推荐Marketing Skills 仓库协作规范面向 Claude Code 与 AI 智能体的 Agent Skills 开发、版本管理与工具集成指南Marketing Skills 仓库协作规范面向 Claude Code 与 AI 智能体的 Agent Skills 开发、版本管理与工具集成指南 本文是AI 技能人工智能IcemacOS 菜单栏管理工具可视化拖拽布局调整IcemacOS 菜单栏管理工具可视化拖拽布局调整 Ice 是一款面向 macOS 的菜单栏管理工具核心功能是控制菜单栏项目的隐藏与显示另提供拖拽布局、桌面应用NetAlertX 仓库 AI 协作开发指南面向 Claude Code 的项目架构、命令与编码规范全解析NetAlertX 仓库 AI 协作开发指南面向 Claude Code 的项目架构、命令与编码规范全解析 本文是 NetAlertX 仓库根目录下 CLAU后端网络运维数据可视化上一篇2025年DXVK完全指南安装、配置与性能优化全攻略下一篇NGCBot消息加密传输保护微信机器人通信安全的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考