scaffold-exercises

scaffold-exercises 스킬 개요

scaffold-exercises 스킬은 엄격한 트레이닝 콘텐츠 규약에 맞는 연습문제 폴더 구조를 에이전트가 만들도록 도와줍니다. 예를 들어 번호가 붙은 섹션, 번호가 붙은 연습문제, problem/, solution/, explainer/ 같은 변형 하위 폴더, 그리고 lint 중심 검사를 통과할 만큼은 유효한 최소 파일 구성을 자동으로 맞춰줍니다. 코스 자료, 워크숍 실습, 구조화된 학습용 repo를 만들고 있다면, scaffold-exercises가 해결하는 일은 바로 이 “구조를 정확하게 깔아주는 작업”입니다.

scaffold-exercises가 가장 잘 맞는 용도

학습 계획은 이미 정해져 있고, 파일시스템 스캐폴딩을 빠르고 일관되게 정확히 만들어야 할 때 scaffold-exercises를 쓰는 것이 좋습니다. 특히 다음과 같은 상황에 잘 맞습니다.

• exercises/ 아래에 새 코스 섹션을 세팅할 때
• 커리큘럼 개요를 바탕으로 여러 개의 연습문제 스텁을 한 번에 만들 때
• problem, solution, explainer 변형을 네이밍 규칙 추측 없이 추가해야 할 때
• 나중에 repo lint에서 실패하는 불완전한 starter 디렉터리를 피하고 싶을 때

누가 scaffold-exercises를 설치하면 좋은가

가장 잘 맞는 사용자는 이미 연습문제 중심의 교육용 구조를 쓰는 repo에서 작업하는 사람입니다. scaffold-exercises skill은 특히 유지보수 담당자, 커리큘럼 작성자, AI 보조 repo 편집자처럼, 문장 생성보다 정확한 경로와 파일 플레이스홀더를 더 중요하게 여기는 사용자에게 유용합니다.

일반 프롬프트와 다른 scaffold-exercises만의 차이

일반 프롬프트로도 AI에게 “연습문제 폴더 좀 만들어줘”라고 시킬 수는 있습니다. 하지만 scaffold-exercises는 여기에 repo 규약에 맞춘 엄격함을 더합니다.

• 섹션 폴더는 XX-section-name 형식을 사용
• 연습문제 폴더는 XX.YY-exercise-name 형식을 사용
• 이름은 dash-case 사용
• 각 연습문제에는 최소 하나의 변형 폴더가 필요
• 각 변형에는 비어 있지 않은 readme.md가 필요
• main.ts 같은 코드 파일은 실제 코드가 있을 때만 필요

이 덕분에 경로 형식이 깨지는 일이 줄고, 빈 플레이스홀더도 줄며, 생성 후 손봐야 할 정리 작업도 적어집니다.

가장 먼저 판단해야 할 도입 기준

가장 큰 리스크가 콘텐츠의 독창성 부족이 아니라 구조 일탈이라면 scaffold-exercises를 설치할 가치가 큽니다. 이 스킬은 규약에 맞는 스캐폴딩에 초점이 있습니다. 반대로 전체 커리큘럼 설계, 레슨 작성, 코드 생성까지 한 번에 해주는 도구는 아닙니다.

scaffold-exercises 스킬 사용 방법

scaffold-exercises 설치는 보통 어떻게 이뤄지나

제공된 repo 발췌본 기준으로는 SKILL.md 안에 전용 설치기가 따로 공개되어 있지 않습니다. 따라서 사용 방식은 여러분의 skills 런타임에 따라 달라집니다. Skills 기반 환경에서는 보통 소스 repo를 추가한 뒤 scaffold-exercises 스킬을 이름으로 호출합니다. 환경이 지원한다면 흔한 패턴은 다음과 같습니다.

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

에이전트 플랫폼이 다른 방식으로 skills를 로드한다면 mattpocock/skills 저장소를 가리키고 scaffold-exercises를 선택하면 됩니다.

scaffold-exercises 사용 전 먼저 읽을 파일

가장 먼저 볼 파일은 다음입니다.

• scaffold-exercises/SKILL.md

이 스킬은 단순하고 자체 완결형에 가깝습니다. repo 미리보기 기준으로는 추가 rules/, resources/, 헬퍼 스크립트가 드러나지 않기 때문에, 실질적으로 중요한 동작 대부분이 이 파일 하나에 직접 들어 있습니다.

scaffold-exercises가 사용자에게서 필요로 하는 입력

이 스킬은 다음 네 가지가 포함된 계획을 받을 때 가장 잘 동작합니다.

1. 섹션 번호와 제목
2. 연습문제 번호와 제목
3. 각 연습문제에 어떤 변형을 넣을지
4. 스텁만 만들지, 실제 starter code까지 넣을지

이 정보가 없더라도 에이전트가 스캐폴딩을 만들 수는 있습니다. 다만 특히 explainer/와 problem/ 중 무엇을 써야 하는지 같은 부분에서는 원치 않는 기본값이 들어갈 가능성이 큽니다.

최소한으로도 작동하는 프롬프트

대략적이지만 실제로 쓸 수 있는 scaffold-exercises usage 프롬프트는 이런 형태입니다.

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

이 정도면 충분한 이유는 번호, 이름, 위치, 변형 유형이 모두 들어 있기 때문입니다.

출력 품질을 높여주는 더 강한 프롬프트

더 좋은 프롬프트는 기본값에 맡길 부분을 명시적으로 고정합니다.

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

이 프롬프트가 더 잘 먹히는 이유는 다음과 같습니다.

• 폴더 변형에 대한 모호함을 없앰
• 불필요한 코드 파일 생성을 막음
• 네이밍 규칙을 처음부터 고정함
• “non-empty”가 실제로 무엇을 의미하는지 에이전트에 분명히 알려줌

계획이 불완전할 때 예상해야 할 기본 동작

상위 스킬 정의에서 가장 중요한 디테일 중 하나는, 스텁을 만들 때 별도 지시가 없으면 기본값이 explainer/라는 점입니다. 개념 설명 중심 연습문제에는 유용하지만, 실제로는 학생 작업 공간이 필요한 경우 잘못된 선택이 될 수 있습니다. 실습형 과제를 원한다면 problem/을 명시해야 합니다.

scaffold-exercises가 생성하는 것

이 스킬은 다음과 같은 반복 가능한 디렉터리 패턴을 기준으로 동작합니다.

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

스텁 스캐폴드라면 readme만 있는 폴더도 허용됩니다. 나중에 코드를 추가할 경우에는 그때 main.ts가 있어야 하며, 한 줄짜리 형식적 플레이스홀더 이상은 들어 있어야 합니다.

실제 repo에서 scaffold-exercises를 쓰는 실무 워크플로

좋은 워크플로는 보통 다음 순서입니다.

1. 커리큘럼 개요를 먼저 평문으로 작성한다.
2. 이를 번호가 붙은 섹션명과 연습문제명으로 바꾼다.
3. 각 연습문제별 변형을 지정한다.
4. 에이전트에게 scaffold-exercises 실행을 요청한다.
5. 콘텐츠를 넣기 전에 경로 이름을 검토한다.
6. repo lint 또는 검증 단계를 실행한다.
7. 그다음에야 코드와 더 자세한 문서를 채운다.

이 순서가 중요한 이유는, 이 스킬이 가장 잘하는 일이 “먼저 구조를 맞추는 것”이기 때문입니다.

재작업을 가장 많이 부르는 네이밍 실수

가장 흔한 잘못된 입력은 다음과 같습니다.

• 숫자 접두어 누락
• dash-case 대신 공백 사용
• 섹션 번호와 연습문제 번호 체계를 혼동
• 폴더가 problem, solution, explainer 중 무엇이어야 하는지 빠뜨림

예를 들어 계획이 “BM25에 관한 연습문제 하나 만들어줘” 수준이면, 에이전트가 너무 많은 부분을 임의로 정해야 합니다. 반대로 “01-retrieval-skill-building 안에 01.03-retrieval-with-bm25를 만들고 problem/과 solution/을 넣어라”라고 말하면 결과가 훨씬 안정적입니다.

Skill Scaffolding 용도로서 scaffold-exercises 적합성

scaffold-exercises for Skill Scaffolding은 repo 형태와 일관성이 병목일 때 잘 맞습니다. 반대로 풍부한 교수 설계, 평가 문항, 완성도 높은 설명문까지 자동 생성해야 하는 상황에는 적합하지 않습니다. 이 도구는 교수 설계를 대체하는 시스템이 아니라, 구조를 강제하는 도구로 보는 편이 맞습니다.

scaffold-exercises 스킬 FAQ

scaffold-exercises는 초보자도 쓰기 쉬운가

네, 단 원하는 연습문제 구조를 이미 이해하고 있다는 전제에서는 그렇습니다. 스킬 자체는 단순합니다. 주로 네이밍, 폴더 레이아웃, 최소 필수 파일을 강제하는 역할을 합니다. 오히려 더 어려운 부분은 커리큘럼과 변형 구성을 미리 결정하는 일입니다.

언제 scaffold-exercises를 쓰지 말아야 하나

다음과 같은 경우에는 scaffold-exercises를 건너뛰는 편이 낫습니다.

• repo가 번호가 붙은 섹션/연습문제 폴더 구조를 쓰지 않을 때
• 연습문제 트리가 아니라 단일 markdown 레슨만 필요할 때
• AI가 코스 아키텍처를 처음부터 발명해주길 원할 때
• 프로젝트의 파일 규약이 readme.md + 선택적 main.ts와 다를 때

수동으로 폴더를 만드는 것과 scaffold-exercises는 어떻게 다른가

연습문제 하나만 만들 때는 수동 스캐폴딩으로도 충분합니다. scaffold-exercises usage의 가치는 연습문제를 여러 개 만들고, 그 과정에서 일관성을 유지해야 할 때 드러납니다. 잘못된 이름, 빈 readme, 뒤섞인 폴더 규칙 때문에 후속 검사에서 깨지는 일을 줄여줍니다.

scaffold-exercises가 연습문제 전체 내용을 생성해주나

아니요. 핵심 가치는 스캐폴딩에 있습니다. 최소한의 readme와 플레이스홀더 구조는 만들 수 있지만, 완전한 레슨 저작 시스템처럼 기대하면 안 됩니다.

매번 problem, solution, explainer를 모두 만들어야 하나

아니요. 상위 규칙상 최소 하나만 있으면 됩니다. 스텁의 경우 아무것도 지정하지 않으면 기본값은 explainer/입니다. 습관적으로 전부 넣기보다, 연습문제의 목적에 맞춰 변형을 선택하는 것이 좋습니다.

scaffold-exercises는 특정 repo 레이아웃에 묶여 있나

네, 꽤 의견이 강한 편입니다. 이 스킬은 exercises/ 계층과 특정 번호 규칙을 전제로 합니다. repo가 그 패턴을 따른다면 유용하지만, 그렇지 않다면 이 전제를 거스르느라 시간이 많이 듭니다.

scaffold-exercises 스킬을 더 잘 활용하는 방법

scaffold-exercises에는 주제 목록이 아니라 번호가 붙은 계획을 주기

scaffold-exercises에서 결과 품질을 가장 빨리 높이는 방법은, 주제 위주로 프롬프트를 쓰는 습관을 버리고 정확한 대상 경로를 주는 것입니다. 예를 들어:

Weak:

• “Add some exercises about retrieval.”

Strong:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

두 번째 프롬프트는 에이전트가 폴더 이름을 잘못 지을 여지를 거의 남기지 않습니다.

기본값에 맡기지 말고 변형 의도를 명시하기

변형 유형을 생략하면 스킬은 스텁에 대해 explainer/를 선택할 수 있습니다. 효율적이긴 하지만 실제 교육 설계와 맞지 않을 수 있습니다. 다음처럼 명확히 말해두는 것이 좋습니다.

• 학생 과제에는 problem/ 사용
• 정답/참고 자료에는 solution/ 사용
• 개념 설명 전용 자료에는 explainer/ 사용

이 한 줄의 구분만으로도 스캐폴드 품질이 체감될 정도로 좋아집니다.

최소하지만 유효한 readme를 요구하기

흔한 실패 패턴 중 하나는 파일은 만들어졌지만 실제로는 쓸모없는 플레이스홀더만 들어가는 경우입니다. 모든 readme.md에 제목과 한 문장 설명을 넣으라고 에이전트에 지시하세요. 그러면 파일이 비어 있지 않게 유지되고, 이후 저작 작업도 훨씬 쉬워집니다.

불필요한 코드 파일 생성을 막기

또 다른 흔한 실수는 모든 곳에 main.ts를 생성하는 것입니다. 상위 스킬 규칙은 readme-only 스텁에 대해 이를 요구하지 않습니다. 가벼운 스캐폴드를 원한다면 “코드가 명시적으로 필요하지 않으면 readme-only로”라고 분명히 말하세요. 첫 번째 패스가 훨씬 깔끔해집니다.

많은 연습문제를 만들기 전에 이름부터 검증하기

대량으로 생성할 때는 먼저 제안 경로 목록을 출력하게 한 뒤, 승인 후 생성하도록 요청하세요. 그러면 수십 개 폴더를 만든 뒤 이름을 다시 바꾸는 일 없이 번호 충돌이나 어색한 slug를 미리 잡아낼 수 있습니다.

첫 번째 scaffold-exercises 실행 후 한 번 더 다듬기

첫 실행 후에는 다음 항목을 검토하면서 결과를 개선하세요.

• 번호 체계의 연속성
• 변형의 누락 여부
• readme의 실용성
• 각 연습문제가 선택한 섹션에 정말 속하는지

그다음 수정만을 목표로 두 번째 패스를 에이전트에 요청하세요. 생성과 검토를 분리하면 scaffold-exercises guide의 결과 품질이 눈에 띄게 좋아집니다.

scaffold-exercises에서도 결국 사람 판단이 필요한 부분

scaffold-exercises skill은 올바른 교수 순서, 연습문제 난이도, 교육적 커버리지를 대신 판단해주지 못합니다. 가장 좋은 결과는 이 스킬로 구조를 자동화하고, 커리큘럼 논리에 대한 검토는 사람이 맡을 때 나옵니다.