33-js-concepts Resource Curator Skill：为 JavaScript 概念页策展与维护高质量外部学习资源的五阶段方法论

本篇技术指南解析 33-js-concepts 仓库中 resource-curator Skill 的完整设计：它定义了一套为概念文档页发现、评估、添加并持续维护外部学习资源（文章、视频、课程、书籍、官方参考）的五阶段工作流，涵盖可信来源分级、质量红线清单、发布日期门槛、Card 描述写作公式与链接审计报告模板。读完本文，你可以直接按这套方法论为新概念页补齐 2-4 条 MDN 参考、4-6 篇文章与 3-4 个视频资源，并对既有页面完成一次结构化的失效链接审计。

Skill 定位：文档站内容流水线的第一道工序

33-js-concepts 是一个 JavaScript 概念教程仓库：主体内容位于 Mintlify 文档站目录 下的 33 个概念页，每个概念页除正文外，还包含 Reference、Articles、Videos 等外部资源区段。这些资源区段的质量由 .claude/skills/ 下的一组定制 Skill 保障，其中 CLAUDE.md 明确列出了六个 Skill：write-concept、fact-check、seo-review、test-writer、resource-curator 与编排者 concept-workflow。

从源码结构看，concept-workflow Skill 将资源策展编排为端到端流程的第一阶段：

Phase 1: resource-curator  →  Find quality external resources
Phase 2: write-concept     →  Write the documentation page
Phase 3: test-writer       →  Generate tests for code examples
Phase 4: fact-check        →  Verify technical accuracy
Phase 5: seo-review        →  Optimize for search visibility

也就是说，先按本 Skill 的标准把外部资源选齐、写好评语，再由 write-concept 把它们组装进页面。Skill 文档本身给出的五个适用场景是：

• 为新概念页添加资源
• 刷新既有页面的资源
• 审计失效或过时的链接
• 评审社区贡献的资源
• 周期性的链接维护

五阶段资源策展方法论

Skill 的核心是一套五阶段方法，每个阶段都有明确的检查点。

Phase 1：审计既有资源

在添加任何新资源之前，先盘点现状。对页面上每一条既有资源依次做五项检查：

1. 检查链接可达性 —— 链接是否返回 200？
2. 验证内容准确性 —— 内容是否仍然正确？
3. 核对发布日期 —— 对该主题而言是否过于陈旧？
4. 识别过时内容 —— 是否仍在使用旧语法/旧模式？
5. 复查描述文字 —— 是具体有价值，还是泛泛而谈？

Phase 2：识别资源缺口

将现状与目标数量对比。目标值（同时也是审计报告中"Resource Count vs Targets"一栏的基准）为：

Section	Target Count	Icon
Reference	2-4 MDN links	book
Articles	4-6 articles	newspaper
Videos	3-4 videos	video
Courses	1-3（可选）	graduation-cap
Books	1-2（可选）	book

同时回答四个多样性问题：

• 是否同时覆盖初学者和进阶读者？
• 是否有视觉化内容（图解、动画）？
• 是否包含官方参考（MDN）？
• 教学风格是否多样？

Phase 3：定向搜索新资源

在可信来源上使用模板化查询词搜索，而不是无目的地浏览。Skill 给出了三类查询模板（[concept] 替换为具体概念名，如 promises、closures）：

文章搜索：

[concept] javascript tutorial site:javascript.info
[concept] javascript explained site:freecodecamp.org
[concept] javascript site:dev.to
[concept] javascript deep dive site:2ality.com
[concept] javascript guide site:css-tricks.com

视频搜索：

YouTube: [concept] javascript explained
YouTube: [concept] javascript tutorial
YouTube: jsconf [concept]
YouTube: [concept] javascript fireship
YouTube: [concept] javascript web dev simplified

MDN 搜索：

[concept] site:developer.mozilla.org
[API name] MDN

Phase 4：撰写描述

每条资源都需要一句具体、有价值的描述，写作公式为：

Sentence 1: What makes this resource unique OR what it specifically covers
Sentence 2: Why reader should click (what they'll gain, who it's best for)

即第一句讲"它独特在哪 / 具体覆盖什么"，第二句讲"读者为什么要点开 / 最适合谁"。仓库中的真实页面正是按这个公式写成的，例如 Event Loop 概念页的 Reference 区段：

<Card title="setTimeout — MDN" icon="book" href="...">
  Complete reference for setTimeout including syntax, parameters, and the minimum delay behavior.
</Card>

第一条句描述具体覆盖面，与公式严格对应。

Phase 5：格式化与组织

• 使用正确的 Card 语法与图标（见下文"资源区段模板"）；
• 资源按逻辑顺序排列（基础内容在前，进阶内容在后）；
• 保持格式一致性。

可信来源清单（分级表）

Skill 将"去哪找资源"沉淀为四张分级表，这是可检索性最强的部分：同类来源按优先级排序，避免在低优先级站点浪费筛选时间。

参考类来源（优先级从高到低）

Priority	Source	Domain	Best For
1	MDN Web Docs	developer.mozilla.org	API 文档、指南、兼容性
2	ECMAScript Spec	tc39.es/ecma262	行为权威定义
3	Node.js Docs	nodejs.org/docs	Node 特有 API
4	Web.dev	web.dev	性能、最佳实践
5	Can I Use	caniuse.com	浏览器兼容性

文章类来源（优先级从高到低）

Priority	Source	Why Trusted
1	javascript.info	全面、带练习、维护良好
2	MDN Guides	官方、准确、定期更新
3	freeCodeCamp	对初学者友好、偏实操
4	2ality (Dr. Axel)	深度技术剖析、面向规范
5	CSS-Tricks	DOM、视觉主题、写作扎实
6	dev.to (Lydia Hallie)	可视化讲解、动画
7	LogRocket Blog	实用教程、贴近真实场景
8	Smashing Magazine	深入、研究充分
9	Digital Ocean	教程清晰、示例多
10	Kent C. Dodds	测试、React、最佳实践

视频创作者（优先级从高到低）

Priority	Creator	Style	Best For
1	Fireship	快、现代、娱乐性强	快速概览、现代 JS
2	Web Dev Simplified	清晰、对初学者友好	初学者、基础概念
3	Fun Fun Function	深度剖析、人格鲜明	理解"为什么"
4	Traversy Media	全面速成课	完整主题覆盖
5	JSConf/dotJS	专家会议演讲	进阶、深入
6	Academind	讲解详尽	完整理解
7	The Coding Train	创意、视觉化	视觉型学习者
8	Wes Bos	实用、真实项目	应用性学习
9	The Net Ninja	逐步教程	跟着做
10	Programming with Mosh	专业、清晰	职业导向

课程来源

Source	Type	Notes
javascript.info	Free	全面、带练习
Piccalilli	Free	写作精良、现代
freeCodeCamp	Free	项目驱动
Frontend Masters	Paid	专家讲师
Egghead.io	Paid	短小、聚焦
Udemy (top-rated)	Paid	需仔细核对评价
Codecademy	Freemium	交互式

质量判据：必须有、优选、一票否决

Must Have（必须满足）

• 链接可用 —— 返回 200（不是 404、301、5xx）；
• 聚焦 JavaScript —— 主体不是 C#、Python、Java 等语言；
• 技术准确 —— 无事实错误或反模式；
• 可访问 —— 免费或有有意义的免费预览。

Should Have（优选）

• 足够新 —— 见下文发布日期指南；
• 来源可靠 —— 来自可信来源清单或知名创作者；
• 视角独特 —— 不是既有资源的重复；
• 深度匹配 —— 与概念的复杂度相称；
• 互动良好 —— 评论区正面、播放量高（针对视频）。

Red Flags（发现即拒绝）

Red Flag	Why It Matters
通篇使用 var	对 ES6+ 主题已过时
教授反模式	对学习者是有害的
主体是其他语言	焦点错误
硬付费墙（无预览）	无法访问
现代主题却发表于 2015 年之前	大概率过时
评论区质量低	往往暗示内容有问题
存在事实错误	会扩散错误信息
标题党、内容单薄	浪费读者时间

发布日期指南：按主题类别设门槛

不是所有资源都要求"新"。Skill 为不同主题类别设定了最低年份门槛：

Topic Category	Minimum Year	Reasoning
ES6+ Features	2015+	ES6 于 2015 年 6 月发布
Promises	2015+	原生 Promise 出自 ES6
async/await	2017+	ES2017 特性
ES Modules	2018+	浏览器稳定支持
Optional chaining (?.)	2020+	ES2020 特性
Nullish coalescing (??)	2020+	ES2020 特性
Top-level await	2022+	ES2022 特性
Fundamentals（闭包、作用域、this）	不限	核心概念不会变
DOM manipulation	2018+	优先现代 API
Fetch API	2017+	广泛支持

经验法则：时效性强的主题，优先选最近 3-5 年的内容；基础概念则经典旧文往往依然优秀。

描述写作指南：公式、正反例与措辞表

正反例对照

Skill 给出了一组真实风格的"好描述"示例（URL 以省略号代指，实际写作时替换为完整链接）：

<Card title="JavaScript Visualized: Promises & Async/Await — Lydia Hallie" icon="newspaper" href="...">
  Animated GIFs showing the call stack, microtask queue, and event loop in action.
  The visuals make Promise execution order finally click for visual learners.
</Card>

<Card title="What the heck is the event loop anyway? — Philip Roberts" icon="video" href="...">
  The legendary JSConf talk that made the event loop click for millions of developers.
  Philip Roberts' live visualizations are the gold standard — a must-watch.
</Card>

<Card title="You Don't Know JS: Scope & Closures — Kyle Simpson" icon="book" href="...">
  Kyle Simpson's deep dive into JavaScript's scope mechanics and closure behavior.
  Goes beyond the basics into edge cases and mental models for truly understanding scope.
</Card>

<Card title="JavaScript Promises in 10 Minutes — Web Dev Simplified" icon="video" href="...">
  Quick, clear explanation covering Promise creation, chaining, and error handling.
  Perfect starting point if you're new to async JavaScript.
</Card>

<Card title="How to Escape Async/Await Hell — Aditya Agarwal" icon="newspaper" href="...">
  The pizza-and-drinks ordering analogy makes parallel vs sequential execution crystal clear.
  Essential reading once you know async/await basics but want to write faster code.
</Card>

这些示例的共同点：第一句点出独特形式（动画 GIF、类比、深度剖析），第二句给出人群与收益。与之相对，Skill 明确列出了四类应避免的坏描述：

<!-- TOO GENERIC -->
<Card title="Promises Tutorial" icon="newspaper" href="...">
  A comprehensive guide to Promises in JavaScript.
</Card>

<!-- NO VALUE PROPOSITION -->
<Card title="Learn Closures" icon="video" href="...">
  This video explains closures in JavaScript.
</Card>

<!-- VAGUE, NO SPECIFICS -->
<Card title="JavaScript Guide" icon="newspaper" href="...">
  Everything you need to know about JavaScript.
</Card>

<!-- JUST RESTATING THE TITLE -->
<Card title="Understanding the Event Loop" icon="video" href="...">
  A video about understanding the event loop.
</Card>

措辞替换表

应避免的措辞：

Avoid	Why	Use Instead
"comprehensive guide to..."	含糊、被用滥	写清楚具体覆盖什么
"learn all about..."	泛泛	具体能学到什么？
"everything you need to know..."	夸张	具体化
"great tutorial on..."	主观填充	它好在哪？
"explains X"	太基础	怎么讲？独特在哪？
"in-depth look at..."	含糊	哪种深度？哪个侧面？

行之有效的措辞：

Good Phrase	Example
"step-by-step walkthrough"	"Step-by-step walkthrough of building a Promise from scratch"
"visual explanation"	"Visual explanation with animated diagrams"
"deep dive into"	"Deep dive into V8's optimization strategies"
"practical examples of"	"Practical examples of closures in React hooks"
"the go-to reference for"	"The go-to reference for array method signatures"
"finally makes X click"	"Finally makes prototype chains click"
"perfect for beginners"	"Perfect for beginners new to async code"
"covers X, Y, and Z"	"Covers creation, chaining, and error handling"

链接审计流程：从状态码到缺口分析

对既有页面做周期性维护时，Skill 把审计拆成四个可执行步骤。

Step 1：逐条检查链接

点击每条资源链接，并记录 HTTP 状态码，按下表处置：

Status	Meaning	Action
200	OK	保留，继续做内容检查
301/302	Redirect	更新为最终 URL
404	Not Found	删除或寻找替代
403	Forbidden	手动核查，可能被地域屏蔽
5xx	Server Error	稍后重试，可能是临时故障

Step 2：内容验证

对每条可达链接：

1. 快速浏览内容 —— 是否仍然准确？
2. 核对日期 —— 何时发布/更新？
3. 确认 JavaScript 焦点 —— 主体是否确实是 JS？
4. 排查红旗项 —— 反模式、错误、过时语法。

Step 3：描述复查

对每条资源：

1. 读现有描述 —— 是否具体？
2. 与实际内容对比 —— 是否相符？
3. 检查泛化措辞 —— "comprehensive guide" 之类；
4. 找出改进点 —— 如何写得更具体？

Step 4：缺口分析

审计完全部资源后：

1. 按区段统计数量 —— 是否达到目标值？
2. 检查多样性 —— 初学者和进阶都有吗？视觉与文本兼有吗？
3. 找出缺失类型 —— 没有 MDN？没有视频？
4. 记录建议 —— 应该补什么？

资源区段模板：Card / CardGroup 语法

概念页使用 Mintlify 的 <Card> 与 <CardGroup> 组件承载资源。Skill 为每个区段提供了模板：

Reference 区段

## Reference

<CardGroup cols={2}>
  <Card title="[Main Topic] — MDN" icon="book" href="...">
    Official MDN documentation covering [specific aspects].
    The authoritative reference for [what it's best for].
  </Card>
  <Card title="[Related API/Concept] — MDN" icon="book" href="...">
    [What this reference covers].
    Essential reading for understanding [specific aspect].
  </Card>
</CardGroup>

Articles 区段

## Articles

<CardGroup cols={2}>
  <Card title="[Article Title]" icon="newspaper" href="...">
    [What makes it unique/what it covers].
    [Why read this one/who it's for].
  </Card>
  <Card title="[Article Title]" icon="newspaper" href="...">
    [Specific coverage].
    [Value proposition].
  </Card>
</CardGroup>

Videos 区段

## Videos

<CardGroup cols={2}>
  <Card title="[Video Title] — [Creator]" icon="video" href="...">
    [What it covers/unique approach].
    [Why watch/who it's for].
  </Card>
</CardGroup>

Books 区段（可选）

<Card title="[Book Title] — [Author]" icon="book" href="...">
  [What the book covers and its approach].
  [Who should read it and what they'll gain].
</Card>

Courses 区段（可选）

<CardGroup cols={2}>
  <Card title="[Course Title] — [Platform]" icon="graduation-cap" href="...">
    [What the course covers].
    [Format and who it's best for].
  </Card>
</CardGroup>

这些模板在真实页面中被逐字遵循。以 Event Loop 页面 为例：Reference 区用 icon="book" 挂 4 条 MDN 链接，Articles 区用 icon="newspaper" 列 6 篇文章（正好落在 4-6 的目标区间），Videos 区用 icon="video" 列 3 个会议/教程视频（落在 3-4 的目标区间），且视频标题统一带 "— Creator" 后缀——与 Quick Reference 中"视频标题须包含创作者"的约定一致。此外该页还有一个 Skill 未强制要求但仓库实际使用的扩展区段 ## Tools（如交互式事件循环可视化器），说明模板是最低基线，页面可在此之上补充。

资源审计报告模板

每次审计完成后，Skill 要求用一份结构化报告留痕，便于后续按优先级修复。模板骨架如下：

# Resource Audit Report: [Concept Name]

**File:** `/docs/concepts/[slug].mdx`
**Date:** YYYY-MM-DD
**Auditor:** [Name/Claude]

## Summary
| Metric | Count |
| Total Resources / Working Links (200) / Broken Links (404)
| Redirects (301/302) / Outdated Content / Generic Descriptions |

## Resource Count vs Targets
| Section | Current | Target | Status (✅/⚠️/❌) |

## Broken Links (Remove or Replace)
| Resource | Line | URL | Status | Action |

## Redirects (Update URLs)
| Resource | Line | Old URL | New URL |

## Outdated Resources (Consider Replacing)
| Resource | Line | Issue | Recommendation |

## Description Improvements Needed
| Resource | Line | Current | Suggested |

## Missing Resources (Recommendations)
| Type | Gap | Suggested Resource | URL |

## Non-JavaScript Resources (Remove)
| Resource | Line | Issue |

## Action Items
### High Priority / Medium Priority / Low Priority

## Verification Checklist
- [ ] All broken links removed or replaced
- [ ] All redirect URLs updated
- [ ] Outdated resources replaced
- [ ] Generic descriptions rewritten
- [ ] Missing resource types added
- [ ] Resource counts meet targets
- [ ] All new links verified working
- [ ] All descriptions are specific and valuable

报告的分级行动项（High/Medium/Low Priority）与 CLAUDE.md 中的 Conventional Commits 规范衔接：修复失效链接的提交应写作 fix: update broken MDN link in Promises section，新增资源写作 feat(closures): add video tutorial by Fun Fun Function。

快速参考与最终质量清单

图标速查

Content Type	Icon Value
MDN/官方文档	book
文章/博客	newspaper
视频	video
课程	graduation-cap
书籍	book
相关概念	视语境选择

字段指引

Element	Guideline
Card title	保持简洁，视频须包含创作者
Description sentence 1	覆盖内容 / 独特之处
Description sentence 2	为何值得阅读观看 / 适合谁

资源排序规则

同一区段内按以下顺序排列：

1. 最基础、最对初学者友好的在前；
2. 官方参考先于社区内容；
3. 最推荐的显著放置；
4. 进阶/小众内容殿后。

四组最终质量清单

• 链接核验：所有链接返回 200、无重定向链、无未声明的硬付费墙、URL 尽量为 HTTPS；
• 内容质量：全部聚焦 JavaScript、不教反模式、发布日期匹配主题、初阶与进阶兼有、视觉与文本兼有；
• 描述质量：具体不泛化、解释独特价值、不含 "comprehensive guide to..." 类措辞、每条恰为两句话、与实际内容相符；
• 完整性：2-4 条官方参考、4-6 篇优质文章、3-4 个优质视频、排序合理、教学风格多样。

小结：资源应当增益学习，而非填充页面

这套 Skill 的结尾给出总原则：Resources should enhance learning, not pad the page. Every link should offer genuine value. Quality over quantity — a few excellent resources beat many mediocre ones.（资源应当增益学习，而不是撑页面；每个链接都应有真实价值；少量卓越资源胜过多条平庸资源。）

落到 33-js-concepts 仓库上，其执行闭环是：审计既有链接（五查）→ 对照目标找缺口（2-4 / 4-6 / 3-4）→ 在分级可信来源中定向搜索 → 按两句话公式写描述 → 用 Card 模板格式化 → 产出带优先级行动项的审计报告。对维护者而言，CLAUDE.md 中的六 Skill 分工与 CONTRIBUTING 指南 中的资源添加规范（高质量、准确、时效、按 Reference/Articles/Videos/Books 分类）共同构成了从个人工具到社区协作的一致性约束；对读者与 LLM 而言，SKILL.md 本身即可作为任意"教程型仓库"资源维护章节的可复用蓝本直接借鉴。