给仓库写传记的Skill首拆：满口PowerShell的外来户——repo-story-time 实读

概述

本期是本栏目第 2 轮，单件深度拆解。拆解对象是装机目录里的 repo-story-time——一件把 git 仓库变成「技术叙事」的件：读你的提交历史，产出两份文件，一份技术盘点，一份题为《The Story of This Repo》的仓库传记。它入选两个理由：其一，本栏目实读十余件以来，正文里带着另一家宿主口音的，它是头一份；其二，「把仓库当采访对象」这个件型，在横评里被归进过写作线、归进过取材层，却从未被单独开膛。本期把它的 SKILL.md 拆到段，顺手做一次文本取证。凡加载通道不可见处，照例以※标注。

评测对比表

五维权重沿用本栏目固定口径：功能 25%、设计 25%、实战 20%、上手 15%（越高越容易）、社区 15%。实战维度未执行实测，从黑箱※；社区维度因作者与上游仓库不可考，从最低※。对照行取本站 9 月 13 日存档《写Skill前先过的四道门》中的两件参照分。

评分说明：功能四星给的是「勘探—盘点—考古—写作」四相闭环的完整度；设计三星是拉开差距的一维，理由见下文——结构与模板是上乘，纪律写法是下乘；上手五星因为它零配置，任何一个有 .git 的目录都是它的工位。

生态坐标：装机端来了个外乡户

这件事的生态含义比这件本身大：Skill 的分发正在跨宿主流动，但正文不会自动入乡随俗。迁居件能不能干活，全看执行模型愿不愿意替它翻译。本期拆的就是这样一份「口音标本」。

主拆解：正文逐段讲

1. 开局两行：人设先行，任务后置

正文第一段不是流程，是人设：「You're a senior technical analyst and storyteller with expertise in repository archaeology, code pattern analysis, and narrative synthesis」。三个头衔里最传神的是 repository archaeology（仓库考古）——这个词组把整件的方法论预告完了：它不读代码逻辑，它读地层。第二句给出使命：「transform raw repository data into compelling technical narratives that reveal the human stories behind the code」。注意定语：human stories。这件从第一行就押了注——它的产出不是文档，是故事。

2. 交付契约：两份文件与三重焦虑

Task 一节立了交付契约：产出必须是两个实体文件，REPOSITORY_SUMMARY.md（技术盘点）和 THE_STORY_OF_THIS_REPO.md（叙事传记）。随后是全文第一处加粗的 CRITICAL：「You must CREATE and WRITE these files with complete markdown content. Do NOT output the markdown content in the chat - use the editFiles tool」。

这句禁令在全文出现了三次——Task 一节一次，Success Criteria 一节一次（「NO markdown content should be output to chat」），收尾的 Critical Final Instructions 又一次（「DO NOT output markdown content in the chat. DO use the editFiles tool」）。加上 Success Criteria 里的「files are ACTUALLY CREATED」「without any copy/paste from chat dialog」，一件三百来行的正文，花了将近一成篇幅反复喊同一句话。

这是本文最诚实的地方：作者被模型「把活干在聊天区、让用户自己复制」烫过，而且不止一次。对照官方 skill-creator 的口径（本站造件机拆解存档）——「给理由，别喊禁令，成片全大写是黄旗」——这份正文恰好是反着写的：三重 DO NOT、四处全大写，但没给一句「为什么要落盘」。更缺的是第五段：它的成功标准全是描述性的，没有一条可执行验收——写完 ls 一下文件在不在，一行就够，没有。

3. 方法论四相：勘探、盘点、考古、写作

Methodology 分四相，骨架干净。Phase 1 勘探：扫目录、找配置（package.json、pom.xml、requirements.txt）、读 README、认出主源码目录和测试目录。Phase 2 盘点：五问定案——解决什么问题、代码怎么组织、用了什么技术、核心组件是什么、数据怎么流动。Phase 3 考古：六步 git 命令组（下文单拆）。Phase 4 识别叙事素材。四相各司其职，先看地面，再看地层，最后动笔——这个顺序本身就是对的，比社区件常见的「上来就写」稳一层。

4. 口音取证一：满正文 PowerShell

Phase 1 给的两条勘探命令是铁证：Get-ChildItem -Recurse -Include "*.md"...、Where-Object {$_.Name -notmatch "(node_modules|\.git|bin|obj)"}。这是纯 PowerShell。更有味道的是那个排除清单：node_modules 是前端的，.git 是通用的，而 bin 和 obj 成对出现，是 .NET 的构建目录默认名——作者的地基里浇筑着 C#/Windows 的日常。Phase 3 的命令组更是一路 PowerShell 到底：(git log ...).Count 用属性取数、ForEach-Object { $_.Substring(0,7) } 截月份、Group-Object 做频次。

本机的装机目录在 Linux 上。也就是说：这件每次被触发，执行模型都得先把它的命令现场翻译成 bash 才能干活。命令可以翻，有两样东西翻不了——这就引出第二条取证。

5. 口音取证二：editFiles 与语义搜索

正文两处要求「use the editFiles tool」，一处要求「use semantic search to understand key concepts」。editFiles 不是本宿主的工具名；semantic search 同样没有对应的原生工具。命令方言错了，模型会顺手换成等价物；工具名错了，是最容易翻车的一种口音——因为它看起来像精确指令，模型要么硬找一个不存在的工具，要么自行映射到 Write/Grep，全凭模型自觉。据正文证据推断，此件原生于另一家以 editFiles 为工具名的编码代理宿主，后原样迁入本机装机目录——此为推断，作者与上游仓库均不可考※，未经官方证实。

5'. 顺带一提：它没有门牌可查

frontmatter 的 name 和 description 在加载通道中不随正文注入，本期照例看不到它的触发面写得pushy还是克制※。按官方口径「门牌是唯一触发机制」（造件机拆解存档），这是本次实读的最大盲区，只能存疑。

6. 六步考古：命令即提纲

Phase 3 是全文技术密度最高的一段，六步各有分工：第一步总量（git rev-list --all --count 加近一年计数）；第二步人物（git shortlog -sn 取前 20 贡献者）；第三步节奏（按月分组取前 12）；第四步主题（--grep="feat|fix|update|add|remove" 加 --name-only 找高频改动文件）；第五步协作（--merges 看 PR 合并记录）；第六步季节（按月份序排列）。每步后面跟着同款纪律句：「Execute each command and analyze the output before proceeding to the next step」——跑一步消化一步，不许攒着。结尾还开了一个活口：「Use your best judgment to execute additional commands not listed above」——命令清单是提纲不是牢笼。

这六步的价值在于它把「分析一个仓库」从一句模糊愿望压成了六条可直接回车的命令。哪怕不装这件，把六步抄下来手动跑，也能得到一份像样的仓库体检单。

7. 五个取景框：把统计变成叙事的现成模具

Phase 4 列了五个叙事元素：Characters（人物）、Seasons（季节）、Themes（主题）、Conflicts（冲突）、Evolution（演变）。对照 Phase 3 的命令组，能看到一套严丝合缝的供料关系：

这是本件真正值得抄走的资产：五个取景框是「把一堆统计数字变成一篇人话」的通用模具，换个领域照样能用——把 git 换成工单系统、换成账单流水，取景框不动。

8. 两份骨架：小说目录学

Output Format 给了两份完整骨架。技术那份中规中矩（Overview、Architecture、Key Components、Technologies、Data Flow、Team and Ownership）。叙事那份是全文最有文学性的一段，章节名直接按小说目录起：「The Chronicles: A Year in Numbers」（编年史：一年间的数字）、「Cast of Characters」（人物表）、「Plot Twists and Turning Points」（反转与转折点）、「The Current Chapter」（当前章）。Key Instructions 六条里最见功力的是两条：「Context Matters: Explain why patterns exist (holidays, releases, incidents)」——看到八月提交骤降，要想到假期和发版；「Be Specific: Use actual file names, commit messages, and contributor names」——叙事必须挂真实证据。收尾一行题词：「Every repository tells a story.」——件有品牌感，这在装机目录里是稀罕品质。

流程图：它的完整流水线

flowchart TD
    A["触发：讲讲这个仓库"] --> B["相一：勘探目录与文档"]
    B --> C["相二：技术五问盘点"]
    C --> D["相三：git考古六步"]
    D --> D1["总量与贡献者"]
    D --> D2["节奏与主题"]
    D --> D3["合并与季节"]
    D1 --> E["相四：五个取景框"]
    D2 --> E
    D3 --> E
    E --> F1["技术盘点文件"]
    E --> F2["仓库传记文件"]
    F1 --> G["落盘交付<br/>聊天区禁贴正文"]
    F2 --> G

它答对的与没答对的

对照本栏目沉淀的写法标准（官方造件机拆解与四道门存档），逐条对账：

答对的三处。 其一，交付契约显式化：两个文件名、两份骨架、成功标准里写明「拿来即用、无需复制粘贴」——期望产出写到模板级，这是官方都点名表扬的写法。其二，确定性纪律：跑一步消化一步、叙事必须挂真实 commit 证据，把「编故事」的冲动按在了证据上。其三，六步命令组加五取景框，是可脱离此件独立复用的方法论资产。

没答对的三处。 其一，纪律全靠喊：三重 DO NOT、成片全大写，按官方口径是黄旗写法——给理由和给验收动作，都比喊三遍可靠。其二，分层缺失：正文里看不到 scripts、references 的任何影子※，而它的第四步（高频文件统计、按月分组）全是确定性算术，按「确定性算术沉进 scripts/」的原则本该下沉——模型手算一万次错一次，脚本跑一万次一个样。其三，回收与失败路径为零：浅克隆怎么办、没有 .git 的目录怎么办、只有三个 commit 的周末项目怎么办——正文一个字没提。对照四道门存档里的处方「报错即停，不许改用自己猜的命令硬来」，这件在第四道门前弃了权。

适用与不适用

适用：新成员入职手册（比干巴巴的架构文档有人味）、团队年度复盘与项目周年稿、开源项目的宣传与招新文案、离职交接时的项目口述史、技术博客选题挖掘。

不适用：合规与安全审计——叙事按「有意思」取材，不保证覆盖全部高危变更，审计要的是清单不是故事；squash merge 的仓库——人物与过程被压扁，故事先天失真；万级提交的大仓——--since="1 year ago" 硬编码，超窗即瞎；浅克隆或无 git 目录——Phase 3 全空且无降级路径；对外发布前——contributor names 会进叙事，过一遍隐私。

推荐排行榜

• 最该抄走的资产：五取景框——把统计变叙事的通用模具，脱离此件也能用
• 最该学的写法：交付契约——文件名写死、骨架给全、成功标准写「无需复制粘贴」
• 最该删的段落：三重焦虑禁令——换成一句「写完 ls 验收」
• 最该补的一块：失败路径——浅克隆、无 git、小仓库三行降级说明
• 最大谜团※：作者是谁、原生的宿主是谁——正文口音指向另一家代理，未经证实
• 本期的提醒：装别人的件之前，先听一眼口音——工具名对不上宿主的正文，每次执行都在靠模型免费翻译

安装与上手命令

# 本期拆件已在装机目录（~/.claude/skills/repo-story-time），无需安装
# 复刻同款：一个目录一个文件即生效
mkdir -p ~/.claude/skills/repo-story-time
# 把正文存为该目录下的 SKILL.md（要点见本文引用段落）

# 不装件也能手动跑它的六步考古（PowerShell 已译成 bash）：
git rev-list --all --count
git shortlog -sn --since="1 year ago" | head -20
git log --since="1 year ago" --format="%ai" | cut -c1-7 | sort | uniq -c | sort -rn | head -12
git log --since="1 year ago" --oneline --grep="feat|fix|update|add|remove" | head -50
git log --since="1 year ago" --name-only --oneline | grep -v "^[a-f0-9]" | sort | uniq -c | sort -rn | head -20
git log --since="1 year ago" --merges --oneline | head -20

参考来源

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。