CommunityWriting & Editinggithub.com

article-card

把一篇文章转换成一个结构化内容卡片,包含标题、一句话主旨、3-5 个核心要点、关键概念、行动项、原文出处、标签与难度等级,并同时给出可机读的 JSON 版本与可阅读的 Markdown 版本。当用户提供了一篇需要提炼要点、归档、复习、做读书笔记或分享给他人的文章(技术文章、论文、博客、公众号长文、课程讲义)时使用本技能。不适用于需要联网抓取网页、解析 PDF 版式、或需要检索外部资料来补全原文的场景。

What is article-card?

article-card is a Codex agent skill that 把一篇文章转换成一个结构化内容卡片,包含标题、一句话主旨、3-5 个核心要点、关键概念、行动项、原文出处、标签与难度等级,并同时给出可机读的 JSON 版本与可阅读的 Markdown 版本。当用户提供了一篇需要提炼要点、归档、复习、做读书笔记或分享给他人的文章(技术文章、论文、博客、公众号长文、课程讲义)时使用本技能。不适用于需要联网抓取网页、解析 PDF 版式、或需要检索外部资料来补全原文的场景。.

Works with~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Hans525/article-card-skill/tree/HEAD

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

内容卡片生成器(article-card)

你的任务:读一篇已给出的文章,产出一张可归档、可复习、可分享的内容卡片。

核心原则只有一句:卡片是原文的忠实浓缩,不是原文的续写。 所有信息必须能在原文中找到依据,找不到就留空或写"原文未提供"。


1. 何时使用 / 何时不使用

使用:用户贴进一段完整的文章、Markdown 笔记、讲稿、论文正文,并希望

  • 提炼要点 / 做摘要
  • 生成笔记或复习卡片
  • 归档到知识库
  • 快速判断这篇值不值得精读

不使用(遇到就直说,不要硬做):

  • 只给了链接或 PDF 文件而你无法读取内容 → 请用户提供正文文本
  • 输入是代码文件、表格、聊天记录、纯图片 → 说明本技能面向散文类文本
  • 用户要你"评价这篇文章好不好" → 那是评论任务,卡片只做忠实提炼,不做评价

2. 输入契约

项目约定
输入形式纯文本或 Markdown。可以带标题、小标题、列表、脚注,保留原样即可
篇幅150 字 ~ 8000 字直接处理;超过 8000 字进入「长文策略」
输入语言任意。输出语言默认跟随原文主语言;用户在提示里指定语言则以用户为准
元信息作者、链接、日期、出处只在输入中明确出现时才能填写,禁止推测
一篇文章一次只处理一篇。用户一次给了多篇 → 逐篇输出多张卡片,不合并、不合并要点

正文之间可能夹杂导航栏、版权声明、"点击关注"之类的噪声。这些不属于文章内容,不进入卡片。


3. 执行流程

按顺序执行,不要跳步:

  1. 判定:先判断这是不是一篇可提炼的散文类文章,篇幅多大,主语言是什么。
  2. 通读:完整读一遍,识别文章结构(问题 → 论证 → 结论?还是清单式?)。
  3. 定位主张:用一句话回答"作者到底想让读者相信什么或做什么"。这句就是 one_liner 的原料。
  4. 抽要点:找出 3-5 个支撑该主张的独立论点。每个论点必须能指回原文的某个段落。
  5. 抽术语:挑出读者若不理解就读不懂全文的概念,给出仅限本文语境的解释。
  6. 抽行动:找出原文明确建议读者去做的事。原文没有 → 空数组,不要自己发明建议。
  7. 定标签与难度:标签按主题而非按体裁;难度按"读懂它需要的前置知识"判定。
  8. 自检:过一遍第 8 节清单,任何一条不通过就改,改完再输出。

4. 字段规则

八个字段,一个不多一个不少。

长度计量规则:一律按字符数(一个汉字 = 1 字符)。表里有两列长度—— 硬上限由 openai.yaml 的 JSON Schema 强制,超了会被服务端拒绝; 中文目标是中文输出的质量目标。英文不用"字"衡量,直接以硬上限为准,因为英文表达同等信息需要更多字符。中文目标约为硬上限的一半,这是按"一个汉字承载的信息量约等于 2–3 个英文字符"给出的工程约定,不是语言学结论。

字段类型数量/硬上限(字符)中文目标规则
titlestring1–60≤40 字原文有明确标题且不超长则沿用原标题;超长可压缩但不得改变含义;自拟标题不得引入原文没有的概念
one_linerstring1–120≤60 字一句话、单句、可独立成立。写"作者主张什么",不写"本文介绍了什么"
key_pointsstring[]2–5 条,每条 1–100每条 ≤50 字正常情况 3–5 条;原文极短时允许 2 条。要点之间必须彼此独立、不重叠、不互为因果。按原文出现顺序排列
concepts{term, gloss}[]2–8 个;term 1–40,gloss 1–90term ≤20 字,gloss ≤30 字只收本文反复使用或作为论述前提的术语。gloss 用本文中的含义解释,不搬百科定义、不补充原文没有的知识
action_itemsstring[]0–3 条,每条 1–80每条 ≤40 字以动词开头、可直接执行、有明确对象。原文无行动建议 → []。禁止把"理解 X"这类空话当行动项
source{title, author, url, locator}四键必填,不设长度上限,值可为 null—只在原文出现时填写。locator 用于定位:文件名 + 小节名/段落号,或用户给出的出处描述。四个值都不确定就全填 null
tagsstring[]3–6 个,每个 1–30,不重复≤24 字小写英文 kebab-case(machine-learning)或中文短词(认知科学),二选一,不混用。禁止 article、reading、notes 这类无区分度的标签
difficultyenumbeginner / intermediate / advanced—beginner:无需前置知识;intermediate:需要领域常识或相关经验;advanced:需要专业背景或数学/工程基础。判据是读懂所需前置知识,不是文章长度

难度判定示例

  • 面向大众的科普、方法论、随笔 → beginner
  • 需要一点行业背景的技术博客、产品分析 → intermediate
  • 论文、含公式推导、需要专业训练的深度文章 → advanced

5. 输出格式

5.1 默认输出(交互式使用)

先输出一个 json 代码块,再输出一个 markdown 代码块,顺序固定,中间不加解释性文字。

JSON 必须严格符合以下形状(键名、嵌套、类型都不能变):

{
  "title": "…",
  "one_liner": "…",
  "key_points": ["…", "…", "…"],
  "concepts": [{"term": "…", "gloss": "…"}],
  "action_items": ["…"],
  "source": {"title": null, "author": null, "url": null, "locator": null},
  "tags": ["…", "…", "…"],
  "difficulty": "beginner"
}

5.2 严格 JSON 模式(API 调用)

当调用方通过 response_format 要求只返回 JSON 时(见 openai.yaml),只输出 JSON 对象本身:不加代码块围栏、不加前后说明、不加 Markdown。Markdown 卡片由调用方按 5.3 的模板渲染。

5.3 Markdown 卡片模板

下面是中文版本。英文文章必须整份换用英文小节名,否则会得到中英混排的卡片——见紧随模板后的对照表。

---
title: {{title}}
difficulty: {{difficulty}}
tags: [{{tags}}]
---

# {{title}}

> {{one_liner}}

## 核心要点

1. {{key_points[0]}}
2. {{key_points[1]}}
3. {{key_points[2]}}

## 关键概念

- **{{concepts[0].term}}**:{{concepts[0].gloss}}
- **{{concepts[1].term}}**:{{concepts[1].gloss}}

## 行动项

- [ ] {{action_items[0]}}
- [ ] {{action_items[1]}}

> 原文未给出可执行的行动建议。

## 出处

- 标题:{{source.title}}
- 作者:{{source.author}}
- 链接:{{source.url}}
- 定位:{{source.locator}}

## 标签与难度

`{{tags[0]}}` `{{tags[1]}}` · 难度:{{difficulty}}

小节名与固定措辞跟随输出语言(中文输出用左列,英文输出用右列,不要混用):

中文输出英文输出
## 核心要点## Key points
## 关键概念## Key concepts
## 行动项## Action items
## 出处## Source
## 标签与难度## Tags and difficulty
- 标题: - 作者: - 链接: - 定位:- Title: - Author: - URL: - Locator:
未提供not provided
难度:difficulty:
原文未给出可执行的行动建议。The source gives no actionable recommendation.
原文篇幅较短,卡片颗粒度相应降低。Source is short; card granularity is reduced.
列表项用全角冒号 :列表项用半角冒号 :

渲染规则:

  • action_items 为空时,整节只保留那句引用块(措辞按上表取对应语言),不保留空的 - [ ] 行。
  • 任何 source 值为 null 时,该行写「未提供」/not provided,不要留空、不要写 null。
  • 占位符按实际条目数量展开,不增不减。
  • Markdown 与 JSON 必须是同一份数据的两种呈现,内容不得有差异。
  • 英文输出时 term 与 gloss 之间的冒号用 : ,与其他英文标点保持一致。

6. 质量红线(违反任何一条即为失败)

  1. 不编造:作者、链接、发表时间、页码、数据、引文、章节号——原文没有就 null。宁可空,不可猜。这条包括你"明明知道"的情况:文章风格明显、你能认出作者是谁,但原文未署名 → 仍然填 null,把判断留给读者,而不是替读者下结论。
  2. 逐字引用 ≤ 25 词:需要引用原句时必须加引号,且单处不超过 25 词,全卡合计不超过原文的 5%(工程约定,非法律意见)。
  3. 区分主张与事实:原文的观点写成"作者认为…",不要转述成客观事实。
  4. 不给高风险建议:涉及医疗、法律、投资、安全的行动项,只允许复述原文,不得自行延伸。
  5. 不做原文替代品:卡片是压缩与重构,不是转录。自检方式不是数字数,而是问一句:只读卡片的人,能不能还原出原文的全部论证细节?如果能,说明压缩失败——删要点,而不是把句子改短。(早期版本曾写"总长不超过原文 20%",实测不可行:一张卡片的元信息与结构本身就会超过短文长度,这个比例只会诱导模型把内容压到失去信息量。)
  6. 要点不重复:两条要点讲同一件事就是失败,合并或删掉一条。
  7. 不反向膨胀:原文没提到的概念不要为了凑数补进 concepts。

7. 边界情况

短文本(150–400 字) 仍按正常流程出卡。要点可降到 2 条,概念可降到 2 个,但不得虚构深度。在 Markdown 卡片末尾加一行:> 原文篇幅较短,卡片颗粒度相应降低。

长文(> 8000 字)

  1. 按原文小标题(无小标题则每约 2000 字)切段;
  2. 对每段抽 1-2 条要点、若干术语;
  3. 合并同类项、删除重复,压到 5 条以内,优先保留支撑主旨的论点;
  4. key_points 按合并后的逻辑顺序重排;
  5. 在 Markdown 末尾标注:> 卡片由分段提炼合并而成,可能遗漏局部细节。

非中文原文 输出语言跟随原文。若原文是英文而用户用中文提问,仍按原文语言输出,并在末尾主动问一句是否需要中文版;用户明确要求中文则直接给中文。

问的时候要给出代价,让用户能做决定,而不是丢一句"要不要中文版?"。例如:"术语在这一版里保留英文原文,翻译后 upwind、midwit peak 这类作者自造词会失真——需要中文版吗?"

用户要求中文版时:作者自造术语(如 upwind、midwit peak)应保留英文原文,在括号内给中文,避免生造词丢失隐喻。此时卡片是混合语言卡,必须在 Markdown 末尾加一行说明:

混合语言卡片:作者自造术语保留英文原文,括号内为中文释义。

同时 title 用中文译名,原文标题原样放进 source.title,两边都不丢。这类词的 term 长度按英文字符计(受硬上限约束),括号内的中文不计入「中文目标」——否则一条正常的混合术语会被误判超长。

输入残缺(明显被截断、只有半篇) 先出卡,但在开头用一行说明:> 输入可能不完整(末尾中断),以下卡片基于现有内容。,并在 source.locator 注明。

输入无法判断 如果读完之后仍然无法确定文章主旨(例如是纯列表、纯代码、无意义字符),直接告诉用户无法生成,并说明缺什么。不要输出一张全靠编的卡片。


8. 输出前自检清单

逐条打勾,任何一条不过就回去改:

  • JSON 能被 json.loads 直接解析,且恰好有这 8 个键,无多余键、无嵌套偏差
  • key_points 在 2–5 条之间,两两不重复
  • action_items 每一条都能在原文找到依据;没有依据就整节置空
  • source 里每个非 null 值都能在输入中逐字找到
  • 逐字引用都加了引号且单处 ≤ 25 词
  • Markdown 与 JSON 内容一致,null 已渲染成"未提供"
  • 全文没有任何原文之外的数字、年份、人名、机构名

9. 示例(短文本,完整且合规)

输入:

很多人把学习理解成输入:读书、听课、收藏文章。但输入的熟悉感很容易伪装成理解——你看懂了一段话,并不等于你能复述它。写作强迫你把模糊的直觉变成明确的句子。当你要向一个不了解背景的人解释一个概念时,含糊的地方会立刻暴露。写不出来的地方,就是真正的知识缺口。

输出,第一块:

{
  "title": "写作是学习的动作",
  "one_liner": "写作把模糊的直觉逼成明确的句子,从而暴露真正的知识缺口。",
  "key_points": [
    "输入的熟悉感会伪装成理解,看懂不等于能复述。",
    "写不出来的地方,就是真正的知识缺口。"
  ],
  "concepts": [
    {"term": "输入的熟悉感", "gloss": "读到时觉得已经懂了、却无法复述的错觉。"},
    {"term": "知识缺口", "gloss": "试图解释时卡住、说不清的那个位置。"}
  ],
  "action_items": [],
  "source": {"title": null, "author": null, "url": null, "locator": null},
  "tags": ["learning", "writing", "metacognition"],
  "difficulty": "beginner"
}

输出,第二块:

---
title: 写作是学习的动作
difficulty: beginner
tags: [learning, writing, metacognition]
---

# 写作是学习的动作

> 写作把模糊的直觉逼成明确的句子,从而暴露真正的知识缺口。

## 核心要点

1. 输入的熟悉感会伪装成理解,看懂不等于能复述。
2. 写不出来的地方,就是真正的知识缺口。

## 关键概念

- **输入的熟悉感**:读到时觉得已经懂了、却无法复述的错觉。
- **知识缺口**:试图解释时卡住、说不清的那个位置。

## 行动项

> 原文未给出可执行的行动建议。

## 出处

- 标题:未提供
- 作者:未提供
- 链接:未提供
- 定位:未提供

## 标签与难度

`learning` `writing` `metacognition` · 难度:beginner

> 原文篇幅较短,卡片颗粒度相应降低。

这张卡片是下限形态:2 条要点、2 个概念、3 个标签、0 个行动项,全部在约束范围内。正常篇幅的文章应产出 3-5 条要点、3-6 个概念。

Related Skills