이 파일은 스킬 사용자를 위한 것이며, 기여자를 위한 것이 아닙니다. 개발 맥락 — 이 스킬이 어떻게 구축되고, 반복되고, 테스트되는지 — 는 AGENTS.md를 참조하세요.
문서 작업 공간 부트스트랩
이 스킬은 AI 에이전트가 빈(또는 거의 빈) 디렉토리에서 문서 작업 공간을 처음부터 구축하는 방법을 가르칩니다. 결과물은 버전 관리되고, 파일 시스템 기반이며, 완전히 자급자족하는 지식 기반입니다. 사용자가 소유하고, 무료이며, 벤더 종속성이 없고, 그 안에서 작업하는 에이전트가 조직, 서식, 도구에 대해 고민할 필요가 없도록 구조화되어 있습니다.
핵심 아이디어
부트스트랩된 작업 공간에는 자체 AGENTS.md — 작업 공간별, 주제별 "고정된 미니 스킬"이 포함되어 있으며, 에이전트는 진입 시 이 파일을 읽습니다. AGENTS.md는 이 스킬이 제공하는 템플릿에서 생성됩니다. 작업 공간이 생성되면 에이전트는 이 스킬이 아닌 AGENTS.md를 따릅니다. 이것이 전체 요점입니다: 규칙을 한 번 미리 결정하고, 이후에는 다시 유도하는 데 토큰을 소모하지 않습니다.
이 스킬을 사용해야 하는 경우
이 스킬은 다음 경우에만 사용하세요:
- 사용자가 명시적으로 문서 작업 공간, 문서 폴더 또는 지식 기반을 생성 / 설정 / 초기화 / 스캐폴딩하려는 경우.
- 대상 디렉토리가 비어 있거나 거의 비어 있는 경우(또는 사용자가 기존 파일에도 불구하고 명시적으로 동의한 경우).
- 대상 디렉토리에 이미
AGENTS.md가 없는 경우(이미 부트스트랩되었음을 의미).
대상에 AGENTS.md가 이미 존재하는 경우: 이 스킬을 실행하지 마세요. 기존 AGENTS.md를 읽고 따르세요. 사용자는 이미 부트스트랩된 작업 공간에 있습니다.
이 스킬을 사용하지 말아야 하는 경우
- 사용자가 기존 작업 공간 내에서 문서를 추가, 편집, 연결 또는 재구성하려는 경우 — 작업 공간 자체의
AGENTS.md가 이를 관리합니다. - 사용자가 GitHub에 푸시하거나, 브라우저에서 작업 공간을 렌더링하거나, 호스팅을 설정하려는 경우 — 다른 문제, 다른 스킬입니다.
- 사용자가 문서, 글쓰기 또는 메모 작성에 대한 일반적인 질문을 하는 경우 — 스킬이 필요하지 않습니다.
스킬이 생성하는 것
호출되면 이 스킬은 다음을 포함하는 작업 공간을 생성합니다:
| 파일 / 디렉토리 | 목적 |
|---|---|
AGENTS.md | 작업 공간별 "고정된 미니 스킬". 95% 규칙, 5% 주제 요약. 에이전트는 진입 시 이 파일을 읽습니다. |
README.md | 작업 공간 수준 개요. 더 풍부한 소개, 자동 생성된 인덱스, AGENTS.md 링크. |
index.yaml | 루트 디렉토리의 문서 순서. 기본적으로 비어 있음. |
.gitignore | 합리적인 기본값: 백업, OS 정크, 편집기 파일, Node. |
package.json | 개발 의존성: prettier, markdownlint-cli, js-yaml. 도구를 위한 npm 스크립트. |
.prettierrc | Prettier 설정: 120자 줄, proseWrap preserve. |
.markdownlint.json | nitpick 규칙이 비활성화된 markdownlint 설정. |
scripts/ | 도우미 스크립트: format.js, validate.js, hash.js, reindex.js. |
assets/ | 빈 공유 자산 디렉토리. 작업 공간 루트에 생성됨. |
git을 사용할 수 있으면 작업 공간에 Git 리포지토리가 초기화됩니다. Node와 npm을 사용할 수 있으면 개발 의존성이 설치됩니다.
부트스트랩 워크플로우
순서대로 단계를 따르세요. 표시된 모든 단계에서 사용자에게 확인을 받으세요. 가정하지 마십시오.
1단계 — 대상 위치 확인
사용자에게 물어보세요: "문서 작업 공간을 <cwd>에 부트스트랩하겠습니다. 맞습니까? (예 / 아니요 / 경로 지정)"
예: cwd를 대상으로 진행합니다.아니요: 올바른 경로를 묻고 확인한 후 진행합니다.- 사용자가 "이 폴더에" 또는 유사한 표현을 한 경우: cwd로 가정하지만 여전히 확인합니다.
2단계 — 대상이 비어 있는지 확인(또는 동의 얻기)
대상 디렉토리의 내용을 나열합니다(숨김 파일 .git은 제외).
비어 있으면: 3단계로 진행합니다.
비어 있지 않으면:
- 사용자에게 무엇이 있는지 보여줍니다.
- 설명: "이 디렉토리는 비어 있지 않습니다. 기본적으로 이 스킬은 비어 있지 않은 디렉토리로의 부트스트랩을 거부합니다. (a) 중단하거나, (b) 어쨌든 진행하기를 확인하면 기존 파일을 그대로 두거나, (c) 작업 공간을 생성할 하위 디렉토리를 지정할 수 있습니다."
- 명시적 확인을 기다립니다. 사용자가 확실한 긍정 확인을 하지 않으면 중단합니다.
- 사용자가 "계속" 또는 "예, 진행"이라고 말하면 — 이를 동의로 기록하고 계속합니다.
대상에 AGENTS.md가 이미 존재하는 경우: 중단합니다. 작업 공간이 이미 부트스트랩되었습니다. 사용자에게 알리고 기존 AGENTS.md를 읽겠다고 제안합니다.
git이 대상에 이미 초기화된 경우: 나중에 git init 단계를 건너뛰되 계속 진행합니다.
3단계 — 주제 요약 수집
사용자에게 물어보세요: "이 문서 작업 공간의 용도는 무엇입니까? 주제를 1~2개의 짧은 단락으로 설명해 주세요. 이 내용이 AGENTS.md의 주제 요약과 README.md의 소개 부분이 됩니다."
주제 요약 규칙:
- 1단락(권장), 최대 2단락
- 일반 산문, 서식 없음, 목록 없음
- 작업 공간이 문서화하는 내용에 대한 명확한 진술
사용자가 한 문장을 제공하면: 괜찮습니다, 그대로 사용합니다. 사용자가 더 긴 설명을 제공하면: (사용자 확인을 받아) 요약하거나 최대 2단락을 사용합니다. 사용자가 "당신이 결정하세요" 또는 "아직 모르겠습니다"라고 말하면: 최소한 한 문장을 요구합니다. 주제 요약은 AGENTS.md의 유일한 주제별 부분이며, 작업 공간에는 어느 정도 앵커가 필요합니다.
4단계 — 부트스트랩 스크립트 실행
다음을 확보한 후:
- 대상 경로
- 디렉토리가 적절하다는 확인
- 주제 요약
...부트스트랩 스크립트를 실행합니다:
node /assets/skill-scripts/bootstrap.js --target --topic ""
스크립트는 다음을 수행합니다:
- Node.js 가용성 확인(Node 종속 아티팩트 건너뛰고 없으면 경고)
- git 가용성 확인(없으면
git init건너뛰기) - 디렉토리 구조 생성
<skill-dir>/assets/templates/의 모든 템플릿을{{TOPIC_SUMMARY}}및{{CREATED}}를 대체하여 인스턴스화- 작업 공간에 포함된 스크립트(
format.js,validate.js,hash.js,reindex.js)를<target>/scripts/로 복사 npm install실행(Node + npm을 사용할 수 있는 경우)git init실행(git을 사용할 수 있는 경우)- 생성된 내용 요약 출력
스크립트가 실패하면(예: 권한 문제, 도구 누락), <skill-dir>/assets/templates/의 템플릿을 사용하여 수동 파일 생성으로 대체합니다. 각 템플릿을 대상에 수동으로 복사하고, 플레이스홀더를 대체하며, <skill-dir>/assets/workspace-scripts/에서 복사하여 scripts 디렉토리를 만듭니다.
5단계 — 사용자에게 생성된 내용 알림
스크립트가 완료된 후 요약:
- 생성된 파일과 디렉토리
git init실행 여부(또는 건너뛴 경우 알림 포함)npm install실행 여부(또는 건너뛴 경우 알림 포함)AGENTS.md가 이제 이 작업 공간의 관리 문서임- 작업 공간을 사용할 준비가 되었음
그런 다음 물어보세요: "문서 작업을 시작하시겠습니까, 아니면 먼저 구조를 검토하시겠습니까?"
템플릿
모든 템플릿 파일은 <skill-dir>/assets/templates/에 있습니다. 부트스트랩 스크립트가 복사하고 대체합니다.
| 템플릿 | 생성 결과 |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore (밑줄로 감싼 파일은 점 접두사가 됨) |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
사용된 플레이스홀더:
{{TOPIC_SUMMARY}}— 사용자의 주제 설명으로 대체됨{{CREATED}}— 오늘 날짜(YYYY-MM-DD)로 대체됨
부트스트랩 스크립트는 밑줄 감싸기 규칙을 자동으로 처리합니다(_foo_.template이라는 파일은 출력에서 .foo가 됨).
작업 공간에 포함된 스크립트
부트스트랩 후 작업 공간에는 scripts/에 다음과 같은 도우미 스크립트가 있습니다:
| 스크립트 | 목적 |
|---|---|
scripts/format.js | 모든 .md/.html/.json/.yaml 파일에 Prettier 실행 |
scripts/validate.js | 모든 .md 파일에 markdownlint 실행 |
scripts/hash.js | 파일의 SHA-256 해시를 계산하고, 선택적으로 assets/에 쓰고 매니페스트를 업데이트 |
scripts/reindex.js | README.md의 자동 인덱스 섹션을 재생성 |
모두 npm을 통해 호출 가능:
npm run formatnpm run validatenpm run hashnpm run reindex
참고 자료
특정 주제에 대한 더 깊은 맥락은 references/ 디렉토리를 참조하세요:
references/asset-management.md— 자산을 추가, 연결 및 마이그레이션하는 방법(콘텐츠 주소 지정 저장소, 매니페스트, 문서별 vs 공유)references/document-promotion.md— 단일 파일 문서가 하위 문서를 얻을 때 폴더로 승격하는 방법
이것들은 관련될 때만 컨텍스트에 로드됩니다. 기본 AGENTS.md는 일반적인 사례를 다루고, 참고 자료는 덜 일반적인 사례를 위한 것입니다.
에이전트를 위한 알림(부트스트랩 중)
- 주제 요약은 사용자가 제공하는 유일한 주제별 콘텐츠입니다. 다른 모든 것은 템플릿화됩니다. 파일 명명, 링크 스타일, 머리말 필드, 커밋 메시지 스타일 또는 기타 규칙에 대해 묻지 마십시오. 이러한 것들은 템플릿에 포함되어 있습니다.
- 사용자가 템플릿이 지원하지 않는 것을 요청하면 이를 표면화하십시오. 조용히 새로운 규칙을 발명하지 마십시오. 올바른 접근 방식은 (a) 향후 템플릿 개정을 위해 기록하거나, (b) 명시적 확인을 받아 예외로 구현하는 것입니다.
- 부트스트랩 후 이 스킬은 완료됩니다. 다음에 사용자가 작업 공간에서 무언가를 하고 싶을 때, 에이전트는
AGENTS.md를 읽고 따릅니다. 사용자가 명시적으로 다른 작업 공간을 부트스트랩하거나 기존 작업 공간을 다시 부트스트랩하지 않는 한 이 스킬은 다시 실행되지 않습니다.