scaffold-exercises

Tổng quan về skill scaffold-exercises

scaffold-exercises là một skill thiên về thiết lập, dùng để tạo các thư mục bài tập khớp với quy ước đặt tên và linting của repository. Skill này hữu ích nhất khi bạn cần thêm một section mới, tạo các stub cho exercise, hoặc chuẩn hóa bố cục problem/solution/explainer mà không phải đoán cấu trúc thư mục. Công việc thực sự ở đây không chỉ là “tạo thư mục” mà là “tạo một scaffold bài tập hợp lệ, sẵn sàng cho nội dung, review và pnpm ai-hero-cli internal lint.”

scaffold-exercises dùng để làm gì

Hãy dùng skill scaffold-exercises khi bạn đã biết nội dung học tập mình muốn thêm, nhưng cần một khung thư mục gọn gàng để chứa nội dung đó. Đây là lựa chọn phù hợp cho tác giả khóa học, người bảo trì repo, và các agent cần tạo cấu trúc bài tập lặp lại ở nhiều section.

Khi nào skill này phát huy tác dụng nhất

Skill này mạnh nhất khi repository có các quy ước chặt chẽ: section được đánh số, exercise được đánh số, và mỗi thư mục biến thể đều bắt buộc có file readme.md. Việc cài đặt scaffold-exercises đặc biệt hữu ích nếu workflow của bạn thường xuyên tạo stub, vì nó giảm lỗi định dạng trước khi nội dung được viết.

Skill này kỳ vọng gì từ bạn

Skill này giả định bạn có thể cung cấp số section, số exercise, tên exercise, và loại biến thể dự kiến. Nếu brief của bạn còn mơ hồ, scaffold vẫn có thể được tạo, nhưng kết quả sẽ tốt hơn khi đầu vào phân biệt rõ các trường hợp dùng problem, solution, và explainer.

Cách sử dụng skill scaffold-exercises

Cài đặt scaffold-exercises

Cài skill scaffold-exercises bằng:

npx skills add mattpocock/skills --skill scaffold-exercises

Đây là đường dẫn cài đặt scaffold-exercises thực tế được dùng trong repo. Sau khi cài, hãy dùng nó như một workflow tạo thư mục, không phải như một prompt viết nội dung chung chung.

Đưa cho skill một brief có cấu trúc

Cách dùng scaffold-exercises tốt nhất là bắt đầu bằng một kế hoạch ngắn gọn, nêu rõ section đích, exercise, và biến thể mong muốn. Ví dụ: “Tạo exercises/02-generation/02.01-rerank-basics/ với các stub explainer/ và solution/; giữ naming dạng dash-case; đảm bảo mỗi readme đều có nội dung.” Cách này tốt hơn nhiều so với “scaffold một bài học”, vì nó cho skill biết cần tạo những path nào và những file nào phải tồn tại.

Đọc đúng file trước

Hãy bắt đầu với SKILL.md, sau đó xem các quy ước exercise của repository liên quan đến cách đặt tên section, các thư mục con bắt buộc, và nội dung stub. Nếu repo có hướng dẫn bổ sung ở chỗ khác, hãy đọc các file đó trước khi tạo bất kỳ thứ gì. Với scaffold-exercises, các điểm quyết định then chốt là định dạng thư mục, variant mặc định, và liệu có cần file code hay chỉ cần stub chỉ có readme là đủ.

Đi theo mẫu tối thiểu hợp lệ của repo

Một cách dùng scaffold-exercises an toàn là tạo thư mục trước, sau đó thêm các file readme.md không rỗng, rồi mới thêm main.ts chỉ khi biến thể đó thực sự chứa code. Nếu bạn đang tạo stub, mặc định explainer/ thường sạch sẽ hơn là bịa ra các file problem khiến người đọc hiểu nhầm là bài làm của học viên còn dang dở. Giữ tiêu đề khớp với tên exercise và tránh các link hỏng trong placeholder ở bước đầu.

FAQ về skill scaffold-exercises

scaffold-exercises chỉ dùng cho exercise mới thôi sao?

Không. Skill scaffold-exercises cũng hữu ích khi bạn thêm một section mới hoặc chuẩn hóa một chuỗi exercise đã có. Nó phù hợp bất cứ lúc nào bạn cần cấu trúc exercise của repo trở nên hợp lệ trước khi viết nội dung chi tiết.

Tôi có cần dùng skill này thay vì prompt bình thường không?

Hãy dùng skill này khi cấu trúc quan trọng hơn văn phong. Một prompt bình thường có thể mô tả ý tưởng, nhưng scaffold-exercises sẽ tốt hơn khi output phải tuân theo quy tắc đặt tên, thư mục bắt buộc, và các stub thân thiện với lint.

scaffold-exercises có thân thiện với người mới không?

Có, nếu bạn xác định được tên exercise và thư mục đích. Lỗi phổ biến nhất của người mới là chỉ định chưa đủ rõ về loại biến thể hoặc bỏ qua sơ đồ đánh số section/exercise, khiến tạo ra các path nhìn có vẻ hợp lý nhưng lại không khớp với repo.

Khi nào tôi không nên dùng scaffold-exercises?

Đừng dùng scaffold-exercises nếu bạn chỉ cần nội dung bài học, brainstorm, hoặc một bản nháp markdown dùng một lần mà không có ràng buộc thư mục. Đây là skill về cấu trúc repository, không phải lối tắt để tạo nội dung.

Cách cải thiện skill scaffold-exercises

Nêu path chính xác hơn và ý định của từng biến thể

Cải thiện chất lượng lớn nhất đến từ việc chỉ rõ thư mục chính xác và vai trò của từng thư mục con. Một yêu cầu tốt sẽ nói rõ cần tạo gì, ví dụ: “Tạo exercises/03-ranking/03.02-bm25-tuning/ với các readme cho problem/, solution/, và explainer/; thư mục problem/ nên có TODOs, solution/ nên có dàn ý tham chiếu, còn explainer/ chỉ nên mang tính khái niệm.” Điều này giúp skill scaffold-exercises dựng đúng cấu trúc ngay từ lần đầu.

Chú ý các lỗi thường gặp

Những vấn đề phổ biến nhất là đánh số sai, thiếu readme.md, placeholder rỗng, và thêm file code khi một exercise chỉ cần stub là đủ. Một lỗi hay gặp khác là trộn tên ở cấp section và cấp exercise trong cùng một path. Hướng dẫn scaffold-exercises hoạt động tốt nhất khi bạn tách rõ quy ước đặt tên và kỳ vọng về nội dung.

Lặp lại sau scaffold đầu tiên

Sau khi generate xong, hãy kiểm tra mỗi thư mục có đủ file bắt buộc chưa và cách diễn đạt trong từng readme có khớp với đúng loại exercise hay không. Nếu sau này bạn quyết định exercise cần code, hãy thêm main.ts chỉ ở nơi nó thực sự thay đổi trải nghiệm học tập. Với scaffold-exercises, vòng cải thiện nhanh nhất là: scaffold, lint, chỉnh tên, rồi mở rộng nội dung.