“skills”这个名字乍看朴素到不像一个项目。但恰恰是这种高度概括的命名逼着你去思考一个问题当一个人把自己的技术能力、项目经历、协作方式浓缩成一个词时背后应该承载什么我前段时间彻底重构了个人技能清单项目代号就叫“skills”本文就把完整的设计思路、踩坑记录和最终落地形态分享出来希望能给正在整理技术栈、简历或个人主页的同学一些参考。先说说这个项目到底是干什么的。它不是一个简历模板也不是一个静态的标签页而是一套“技能数据的结构化管理系统”。核心功能包含三块一是将散落的技术栈、项目、证书和成就整理成统一数据格式二是根据这份数据自动生成可视化技能图谱、README 文档和简历快照三是提供一套校验脚本确保技能数据的新鲜度和一致性避免出现“简历写的技能自己都不熟”的尴尬。1. 整体设计与思路拆解1.1 为什么“skills”项目值得做很多人觉得技能清单就是在一张纸上列关键词或者做一个酷炫的图表放在主页上就完事。但我实际操作下来的体会是没有结构化底座的技能展示本质上只是“看起来好看”的摆设。技术栈是动态变化的项目经验是不断累积的如果这些信息散落在 README、个人网站、招聘平台的多个地方维护成本会指数级上升。最后的结果通常是个人网站展示的还是半年前的技术栈简历里的项目和实际做过的东西对不上面试官问起来只能现场翻手机。“skills”项目解决的就是这个问题。它把技能数据从“展示层”抽离出来放到一个独立的、可版本控制的、可自动校验的数据层里。这样你只需要维护一处数据源通过脚本自动生成所有面向用户的呈现形式。这个思路在企业级开发里叫“单一数据源”放在个人项目里同样适用而且收益更明显。1.2 方案选型背后的逻辑我最初纠结过几种实现方式。第一种是纯 Markdown直接在 README 里手写技能模块好处是简单坏处是没法自动化技能和项目之间也无法建立关联。第二种是 JSON 数据文件加前端渲染好处是结构化强坏处是自己得写一个可视化页面工作量不小。第三种是 YAML 配静态站点生成器好处是生态成熟坏处是如果只看重技能清单这个功能引入整套建站框架有点过度设计。最终我选择了“JSON 数据文件 轻量脚本 简单可视化页面”的组合原因很直接JSON 是通用性最好的数据格式几乎所有语言和平台都有原生支持脚本负责生成 markdown 版本和校验数据完整性逻辑简单不依赖重型框架可视化页面用原生 HTML 加一点 CSS 就能完成不需要构建打包随手就能打开查看。这套方案的核心优势是每一层都足够简单出了问题可以快速定位。2. 内容架构设计2.1 技能分类的颗粒度如何处理技能数据的核心难题不是“怎么展示”而是“如何定义”。如果颗粒度太粗比如只写“AI”“前端开发”那等于没有信息量如果颗粒度太细比如把所有 JavaScript 生态里的库名全部列上数据会迅速膨胀且难以维护。我最终采用了三层结构领域、方向、具体技能。领域对应大的技术范畴比如“人工智能”“后端开发”“工程效能”方向是领域下的具体分支比如“人工智能”下面可以有“机器学习算法”“自然语言处理”“LLM 应用开发”具体技能就是可衡量、可被面试追问的技术点比如“PyTorch 模型调优”“LangChain 工具链编排”。这个三级分类的好处是既可以用领域做快速了解也可以下钻到具体技能做深度匹配。数据中大概三十个方向、上百个具体技能配合活跃度字段信息密度就出来了。2.2 项目与技能之间的关联设计技能清单如果没有项目支撑那就是一张空头支票。这个项目里我专门设计了“技能到项目的映射关系”每条技能都维护一个related_projects数组记录哪些项目实际使用了这项技能。这个设计带来的好处是双向的。从展示角度看访问者可以点击技能直接看到对应的项目案例形成“我会这个”到“我做过的证据”的闭环从自我审视的角度来看当我发现某个技能没有任何关联项目时就会意识到这个技能可能只是停留在“了解”层面要么找机会落地一个项目要么诚实地降低熟练度评分。这种自我校验机制非常有用它逼着你不去写那些“看起来应该会”的技能。3. 数据格式与核心实现3.1 数据文件的结构设计整个项目的核心是一个skills.json文件。为了让读者直接能参考我把最关键的字段结构列出来{ meta: { owner: 某开发者, updated_at: 2025-01-15, version: 2.1.0 }, categories: [ { name: 人工智能, icon: ai, directions: [ { name: 机器学习算法, skills: [ { name: PyTorch 模型调优, level: 4, tags: [深度学习, GPU 优化, 分布式训练], related_projects: [某图像处理Demo], experience_days: 420 } ] } ] } ] }这个结构看起来不复杂但有几个字段值得解释一下设计意图。level用 1 到 5 的整数表示熟练度刻意避免“精通”“熟练”这类模糊词汇因为整数既可以用于排序也可以用于可视化展示。experience_days记录的是累计投入天数而不是工作年限这样更准确因为有些技能虽然接触得久但实际坚持的时间没那么多。这两个字段配合起来就能得出一个“技能可信度”的计算逻辑。3.2 技能可信度计算逻辑纯靠主观打分总觉得心里没底所以我设计了一个简单的可信度公式用来过滤那些“自我感觉良好”的技能可信度分数 熟练度(level) * 权重系数 经验天数(experience_days) * 权重系数 关联项目数(related_projects) * 权重系数实际实现中我对不同类型技能采用不同权重。比如对于通用技能沟通、协作等虽然本项目主要聚焦技术技能但保留扩展位熟练度权重高一些对于工具类技能经验天数和项目数的权重会更高因为这类技能的熟练程度高度依赖于实际项目中的反复打磨。推荐的最小阈值是任何技能如果没有至少一个关联项目或者累计经验天数低于 90 天就不应该出现在展示页面上。这是我从多次面试和被别人问倒的经历中总结出来的硬规则。3.3 自动生成 README 的脚本实现有了结构化的数据接下来就是把它变成人类友好且方便在 GitHub 等代码托管平台展示的内容。参考实现中我基于 Python 的标准库中的json与datetime模块编写了一个运行于命令行环境的小工具它会读取skills.json动态生成一段带进度条效果的 Markdown 内容并写进 README 文档。我最看好的部分就是“当数据文件更新后无需手动调整展示文本”。#!/usr/bin/env python3 import json from pathlib import Path def load_skills(): with open(skills.json, r, encodingutf-8) as f: data json.load(f) return data def build_readme(data): lines [ # 个人技能清单, , f 最近更新{data[meta][updated_at]} 数据版本{data[meta][version]}, , ## 技能总览, , ] total_projects len({p for cat in data[categories] for d in cat[directions] for s in d[skills] for p in s[related_projects]}) lines.append(f覆盖 {len(data[categories])} 个领域、{sum(len(d[skills]) for cat in data[categories] for d in cat[directions])} 项具体技能、{total_projects} 个落地项目。) lines.append() for cat in data[categories]: lines.append(f### {cat[name]}) lines.append() for direction in cat[directions]: lines.append(f#### {direction[name]}) lines.append() for skill in direction[skills]: bar_len min(skill[level], 5) bar * * bar_len - * (5 - bar_len) proj ,.join(skill.get(related_projects, [])) or 暂无关联项目 lines.append(f- {skill[name]} {bar} {skill[experience_days]}天关联{proj}) lines.append() return \n.join(lines) if __name__ __main__: data load_skills() readme build_readme(data) Path(README.md).write_text(readme, encodingutf-8) print(README.md 已更新)这段脚本的思路借鉴了持续集成里的“生成物”概念——README 不是手写的展示文件而是由数据文件生成的产物这样能保证 README 和 JSON 永远处于同步状态。3.4 可视化页面的轻量实现为了让技能数据不只在代码托管平台上可读还能方便地分享给非技术背景的人我写了一个单文件的index.html可视化页面。页面不依赖任何前端框架纯浏览器原生 API 实现按 JSON 数据渲染“领域卡片”和“技能进度条”。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title个人技能图谱/title style :root { --gap: 16px; --radius: 12px; } * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; background: #f5f6fa; color: #2d2f33; padding: 24px; } .container { max-width: 960px; margin: 0 auto; } .card { background: #fff; border-radius: var(--radius); padding: 20px; margin-bottom: var(--gap); box-shadow: 0 2px 8px rgba(0,0,0,0.06); } .card h2 { font-size: 20px; margin-bottom: 8px; } .skill-item { display: flex; align-items: center; margin: 10px 0; gap: 12px; flex-wrap: wrap; } .skill-name { width: 180px; font-weight: 600; } .bar-wrap { flex: 1; min-width: 180px; background: #edf0f3; border-radius: 20px; height: 10px; overflow: hidden; } .bar-fill { height: 100%; background: #4a7eff; border-radius: 20px; } .meta { font-size: 13px; color: #6b7280; } /style /head body div idapp classcontainer h1个人技能图谱/h1 p idmeta classmeta/p div idcontent/div /div script async function init() { const res await fetch(./skills.json); const data await res.json(); document.getElementById(meta).innerText 最近更新${data.meta.updated_at} | 版本${data.meta.version}; const container document.getElementById(content); data.categories.forEach(cat { const card document.createElement(div); card.className card; let html h2${cat.name}/h2; cat.directions.forEach(dir { html p classmeta${dir.name}/p; dir.skills.forEach(skill { const pct skill.level * 20; const proj (skill.related_projects || []).join(, ) || 暂无; html div classskill-item span classskill-name${skill.name}/span div classbar-wrapdiv classbar-fill stylewidth: ${pct}%/div/div span classmeta${skill.experience_days}天 · ${proj}/span /div; }); }); card.innerHTML html; container.appendChild(card); }); } init(); /script /body /html之所以坚持单文件实现是因为这类项目大概率不需要引入前端工程化的复杂度。一个 JSON 加一个 HTML随便找个静态托管服务传上去就能用连构建步骤都省了后续维护起来心理负担很小。3.5 结构化校验脚本自动化校验是最能减少“实际维护惰性”的部分。我会在本地提交前跑一遍校验脚本validate.py主要检查几类问题#!/usr/bin/env python3 import json, sys with open(skills.json, r, encodingutf-8) as f: data json.load(f) errors [] cnt 0 for cat in data[categories]: for direction in cat[directions]: name direction[name] all_skills direction[skills] if not all_skills: errors.append(f方向 {name} 下没有技能) for skill in all_skills: cnt 1 level skill.get(level) if level is None or not (1 level 5): errors.append(f技能 {skill[name]} 的 level 必须是 1-5 的整数) if not skill.get(related_projects): errors.append(f技能 {skill[name]} 没有关联项目会被过滤) if not skill.get(name): errors.append(存在无名称技能) if skill.get(experience_days, 0) 0: errors.append(f技能 {skill[name]} 的经验天数为负数) print(f共校验 {cnt} 项技能) if errors: print(发现以下问题) for e in errors: print(f - {e}) sys.exit(1) else: print(全部校验通过。)这套校验规则是根据实践经验总结出来的不一定适用于所有人但核心原则很有参考价值数据文件必须自带“防呆设计”让错误在进入展示层之前就被拦截掉。4. 实操过程与关键环节记录4.1 从零搭建的完整步骤我建议按下面这个顺序来搭建每一步都建立在之前的基础上方便排查问题初始化目录结构创建一个新目录名字就叫 skills内部包含数据目录、脚本目录、展示目录。编写 skills.json先梳理当前具备核心竞争力的技能用领域、方向、具体技能三级分类组织。编写校验脚本先定义数据结构规范再写 python 脚本进行校验确保数据格式符合预期。生成 README 脚本基于标准库用最少的代码读取 JSON渲染出易读的 Markdown。制作可视化页面将数据渲染到浏览器上做成相对直观的图谱。建立关联信息为每项技能添加项目链接和累计经验天数这是最有价值的一步也是最花时间的。跑通全链路修改 JSON 数据后依次执行 validate.py、build_readme.py确认输出一致。部署并持续更新推到代码托管平台并在新项目、新技能出现时同步更新 JSON 数据。4.2 数据迁移过程实录我当时有一个旧版的个人主页技能分散在各种 HTML 片段里没有统一结构。迁移时我先把旧的技能文本逐条写成了 JSON 数组这一步不算难难在确定每条技能的level和experience_days。实际操作时我给自己定了几条辅助判断标准。对于level能用这项技能独立完成至少两个完整项目且不需要频繁查文档打 4 分能说清楚原理但动手需要辅助参考打 3 分只知道概念但没实际用过打 2 分或直接不录入。对于experience_days不要凭印象去翻代码仓库、博客文章、任务管理工具的记录把实际投入的核心时间累加那些只是“接触”的时间严格不算。迁移过程中最大的收获是你会被迫承认很多技能其实并不像自己以为的那么熟练。这种诚实的评估对后续技术规划非常有帮助。4.3 展示层与数据的联动效果改完数据后体验还是很直观的。以前我更新个人主页的技能模块需要同时改 HTML、改 README、改简历经常出现漏改或改出不一致的情况。现在只需要动一处 JSON然后跑两个脚本所有产物都会自动更新。最满意的一个细节是 README 里自动生成的进度条虽然风格比较素但信息传达很清楚一眼就能看出来哪些技能是主力哪些技能只有两三分功力。这种呈现方式在面试和对外合作时很好用直接把链接甩过去就行不用再长篇大论地自我介绍。5. 常见问题与排查技巧实录5.1 技能数据更新不及时的问题这个问题几乎必然发生。JSON 文件一旦不常维护过几个月再打开就会觉得陌生。我的解法是给项目加了一个“提醒清单”每次更新完代码后顺手把项目里用到的关键技能同步到skills.json的related_projects里。这件事不用做得非常完美只要保持较低的操作摩擦就行重点是“顺手”二字。5.2 熟练度评分忽高忽低评分完全靠主观会有很大偏差今天觉得某个技能很熟练明天看别人实现得更好就瞬间觉得自己是个初学者。后来我引入了一个校准标准用“能不能独立交付”和“能不能讲清楚底层原理”两个维度来辅助打分。能独立交付且有成型项目成果的保底 3 分能讲解原理并教会别人的给到 4 分以上。这样打分虽然有主观成分但至少有了相对稳定的标尺。5.3 可视化页面加载本地 JSON 被拦截如果你直接在本地双击打开 index.html浏览器可能会因为跨域策略拦截fetch(./skills.json)的请求。解决方式有两种一是把它放到本地静态服务下通过 HTTP 协议访问二是切换到 build 分支时把 JSON 数据作为 JavaScript 对象直接嵌入 HTML 中。我的建议是方式一更符合真实使用场景毕竟这个页面最终是给外部访问者看的。5.4 旧项目技术栈与当前技能不一致经验累积过程中很容易出现“以前用过现在不用了”的技能。我的原则是只要在近半年内没有实际使用记录就把该技能的level限制为不超过 2或者干脆归入“探索过”的分类里。因为面试或合作方真正关心的是你现在能做什么不是两年前你碰过什么。6. 这个项目带给我的方法论沉淀6.1 技能数据化比技能本身更稀缺很多人积累了大量项目经验但从来不回头看自己的技能到底是什么状态。通过把技能拆解成结构化数据你会清晰看到自己有哪些能力缺口和优势不再凭感觉做规划。这个价值甚至超过了项目本身的代码实现。6.2 个人项目的“单一数据源”原则在团队协作中单一数据源是降低沟通成本的重要方法。在个人项目里这个原则同样适用只要能让所有展示层从一个源头派生就会极大减少不一致的问题。任何“需要同时维护多个副本”的设计都值得警惕。6.3 留好扩展位从技能清单到个人数据枢纽“skills”项目目前只管理技能数据但数据格式已经在向“个人数据枢纽”的方向扩展。例如后续可以把项目、文章、证书、获奖记录都通过统一数据源管理起来进一步延伸为个人知识沉淀的索引。架构上保持数据层与展示层分离扩展时就很轻松。最后分享一个实际使用中的小心得这个项目做完后我在跟别人介绍自己的技术背景时自信心明显更足因为每一条技能背后都有真实项目、真实数据和真实经验天数做支撑简历里那些抽象的技术词第一次有了具象的证据。如果你也想重新梳理自己的技术能力建议从建一个skills.json开始复杂程度并不高但长期回报非常可观。