Reusable Skills (.claude/skills/)
Bộ skill tái sử dụng cho các workflow lặp lại của Nemo12, gọi bằng /<tên-skill> trong Claude Code. Nội dung thực thi nằm trong .claude/skills/<tên>/SKILL.md (cùng repo, cùng version control).
Danh mục đầy đủ, chia nhóm: Danh mục skill của agent (SRC-1285). Trang ấy SINH từ frontmatter của từng skill bằng scripts/gen-skills-catalog.mjs, nên không thể lệch với .claude/skills/ như bảng viết tay từng nằm ở đây (bảng cũ liệt kê 18 trong 37 skill khi bị thay ngày 07.10.2026). Trang này giữ phần máy không sinh được: quy ước viết skill và lịch sử các đợt rà.
Quy ước viết skill (SRC-1285)
| Trường frontmatter | Luật |
|---|---|
name | trùng tên thư mục |
description | câu mục đích, rồi "Dùng khi ..." (hoặc "Chạy ...") nói khi nào dùng; máy tách hai phần cho danh mục |
group | một id trong GROUPS của scripts/gen-skills-catalog.mjs: curriculum, articles, ux, engineering, release, audit, docs, social |
owner | platform, content hay growth: ai giữ skill khớp thực tế |
last_reviewed | YYYY-MM-DD, ngày sửa hay đọc lại gần nhất |
- Docs phụ thuộc KHÔNG khai tay: danh mục nhặt mọi đường dẫn
docs/...mdvàCLAUDE.mdtrong thân skill. Muốn một doc hiện ở cột ấy thì trỏ tới nó trong thân bài (đằng nào skill cũng phải trỏ). - Skill là QUY TRÌNH, chuẩn nằm ở doc canonical; hai bên nói khác nhau thì doc thắng và sửa skill trong cùng commit.
- Thêm hay sửa skill: chạy
node scripts/gen-skills-catalog.mjsrồi commit cả trang danh mục.npm run check:docschạy bản--check: đỏ khi skill thiếu trường, nhóm lạ, hay danh mục lệch.
Bốn bộ skill: course, books, SEO, UI (08.10.2026, SRC-1293)
Chủ dự án 08.10.2026 yêu cầu tách skill thành bốn bộ, mỗi bộ chỉ lo một mảng, và tự chọn phương án đơn giản cho mọi câu hỏi thiết kế. Đã chốt:
| Quyết định | Chọn | Vì sao |
|---|---|---|
| Cấu trúc | Skill phẳng trong .claude/skills/, bộ = trường group trong frontmatter | Claude Code chỉ đọc skill ở cấp một; danh mục skills/index.md đã nhóm theo group |
| Tên skill cũ | Giữ nguyên | Đổi tên làm gãy mọi chỗ đang gọi /e2e-check, /new-page... |
| Bộ course | 12 skill course-* theo Course OS; /course-design thành cửa vào điều phối | Năng lực giao nhau bằng artifact YAML, workflow tách khỏi skill |
| Evals, Golden Courses | Để giai đoạn sau | Mỗi skill đã có Quality Criteria và Failure Conditions đo được |
| Bộ books | Thêm /book-cover, tách khỏi /program-books | Bìa của hai thư viện đã chung một bộ vẽ (SRC-1235), nên chỉ cần một skill |
| Bộ SEO | Thêm /seo-page (SEO một trang) và /seo-audit (rà toàn site) | Cụm bài viết đã có /article-*; SEO từng trang và rà định kỳ chưa có |
| Bản đồ từ khoá (SRC-1296, 08.10.2026) | Thêm /seo-keywords; /seo-page và /article-plan tra bản đồ trước khi chọn từ khoá | 200 nhóm x 5 cụm phụ huynh tìm, mỗi nhóm một URL, cổng keyword-coverage trong build web |
| Bộ UI | Thêm /ui-build, viết lại /audit-ui, chuẩn mới layout-standard, máy quét npm run audit:ui | Chủ dự án thấy component xô lệch, không chuẩn grid, spacing, màu, token; DS-001 chưa có thang spacing và lưới |
Mỗi bộ có một trang tổng quan sinh tự động (mục đích, luồng gọi giữa các skill, doc canonical): course · books · SEO · UI. Công cụ mà agent gọi (công cụ lõi, MCP, CLI, cổng): Công cụ của AI agent.
Cổng UI chạy theo kiểu file mình chạm thì phải sạch (npm run audit:ui -- --changed), chưa nối vào check:code: lượt đo đầu có 2.388 vi phạm nợ cũ, chặn CI ngay thì mọi phiên đứng.
Rà soát và nâng cấp skill (2026-10-07, SRC-1283..1286)
| Skill | Đổi gì |
|---|---|
/content-editor | MỚI: quy trình thêm một thực thể sửa được vào trình sửa nội dung của Dolphin (chỉ đọc mặc định, Sửa/Lưu/Huỷ, kiểm hợp lệ dùng chung, audit, phát hành), trỏ SDD-056 |
/journey-design | thêm trang lesson kiểu card Activity bên trái (SRC-1286) và tick bước lưu server (SRC-1283) |
/course-design | thêm mô hình Activity · Bước, id bước ổn định, và đường soạn qua trình sửa Dolphin sau khi chuyển (SDD-056 §11) |
/new-module, /api-test | thêm khuôn route tiến độ theo bước (chỉ learner ghi, phụ huynh/mentor đọc, bản kê bước từ nội dung, rate limit) |
/intake | bỏ mô tả khoá mkdir đã cũ: số SRC nay giành trên remote, và script nối dòng sau một dòng trống nên phải soát bảng |
/new-sdd | nhắc thêm dòng FILE_AREA cho thanh bên docs |
bốn skill audit-* | thêm câu "Dùng khi ..." để danh mục và máy chọn skill biết khi nào gọi |
Rà soát toàn bộ skill (2026-09-04)
Đợt rà thứ hai đọc lại cả 14 skill cũ đối chiếu với code và workflow đang chạy. Kết quả: 4 skill mới (đã dựng, có trong bảng trên) và 9 skill được vá, phần lớn vì luật production đã đổi mà skill còn dạy đường cũ.
| Skill | Đã lệch ở đâu | Đã sửa thành |
|---|---|---|
/deploy | Dạy cd <dir> && npx wrangler deploy và apply migration --remote từ máy — đúng thứ README cấm và đã gây lệch sổ d1_migrations hai lần. Còn tả CI như 11 workflow path-filtered, trong khi từ 2026-08-23 chúng đã gộp vào ci.yml | Viết lại: ci.yml là đường chính (migration áp tự động trước worker), deploy tay qua gh workflow run, mục "Cấm" tường minh, kiểm sau deploy bằng request thật (ba cổng nội bộ phải 302) |
/d1-migrate | Mục "Nạp dữ liệu" dạy wrangler d1 execute --file từ máy | Trỏ sang /seed-data; thêm mục "Xong khi" (số liên tục · migrate:dryrun · không còn pending · gen:reference không lệch) |
/trace-check | Viết "nếu có scripts/check-docs.mjs thì chạy" — nó tồn tại từ lâu và nay là 9 script | Chạy npm run check:docs trước, đọc tay sau; cảnh báo cây làm việc bẩn làm cổng nói dối; thêm QG-013 (trần nợ chỉ đi một chiều) |
/ui-feedback | Dạy đọc dòng "Nguồn tiếp theo" rồi ghi tay — đúng cách hai phiên cùng lấy một số SRC | Cấp SRC bằng scripts/src-new.mjs; thêm check:code; nối /e2e-check và /ship |
/new-module | Dừng ở "viết test", không nói chạy cổng nào trước khi commit | Nối /api-test; thêm bước typecheck · test workspace · contract:diff (+ contract:snapshot khi đổi hợp đồng) |
/new-page | Trang mới không có case smoke nào | Bắt buộc thêm case vào bộ e2e |
/lab-pipeline | seed-labs.mjs ngụ ý ghi thẳng production | Ghi rõ script chỉ sinh .sql, nạp qua /seed-data |
/intake, /new-sdd, /model-engine | Tham chiếu skill khác bằng chữ, kết thúc lửng ở check-docs.mjs | Đổi thành liên kết thật + npm run check:docs; model-engine thêm luật "engine không có test cho why/diff là engine chưa xong" |
Bốn skill không đổi vì vẫn khớp thực tế: /course-design, /ebook-chapter, /fb-post (vừa cập nhật 04/09 với các bẫy Substack/LinkedIn), /lab-extract.
Ba thứ vẫn không nên thành skill: npm run wt (một lệnh, CLAUDE.md đủ), các script gen:* (thêm skill chỉ là lớp gọi thừa), soạn item nội dung (đã thuộc /course-design + SDD-027).
Ba skill còn để dành, dựng khi có nhu cầu thật: /audit (26 báo cáo trong docs/quality/audits/), /new-app (13 app · 2 khuôn khác nhau), /dep-upgrade (luật ghim số), /incident (rollback → incident-log → SRC sửa gốc).
Nợ phát hiện trong lúc rà soát
Phần ngoài skills (cổng CI, test, nội dung trong code, scripts/, trần nợ) tách riêng ở rà soát nâng cấp nền tảng.
- Bảng trên từng liệt kê 6 trong 14 skill đang có — mục lục canonical lệch với
.claude/skills/suốt nhiều tuần. Đã bù đủ ở bản này; luật mới: skill mới chưa có dòng trong bảng thì coi như chưa xong. - Cây làm việc còn
wt-ref/và.claude/worktrees/*chưa dọn — chúng làm mọi lệnhfind/greptoàn repo trả về bản sao, và đã từng làm một lượt đếm test sai gấp đôi.
Quy ước (2026-09-04, nay máy thi hành): skill mới phải (1) có mô tả trong danh mục (nay tự sinh), (2) tham chiếu đúng doc canonical thay vì lặp nội dung, (3) được cập nhật khi doc gốc đổi (QG-001 kiểm link).