4부·14장 첫 번째 커스텀 스킬: 주간 보고서 자동 생성
4부·14장 첫 번째 커스텀 스킬: 주간 보고서 자동 생성
스킬을 이해하는 것과 스킬을 직접 만드는 것은 완전히 다른 경험이다. 전자는 설명을 읽고 고개를 끄덕이는 단계고, 후자는 내 업무 방식을 에이전트에게 실제로 이식하는 단계다. 이번 장에서는 그 경계선을 넘는다.
첫 실습 주제로 주간 보고서 자동 생성을 고른 이유는 단순하다. 거의 모든 1인 창업가, PM, 마케터, 개발자가 바로 써먹을 수 있기 때문이다. 흩어진 메모, 작업 로그, 회의 노트, 이슈 목록을 한 번에 정리해 이해하기 쉬운 보고서로 바꾸는 일은 생각보다 자주 반복된다. 실제 커뮤니티에서도 weekly-report 계열 스킬은 "흩어진 작업 노트를 빠르게 훑어볼 수 있는 요약으로 바꾸는" 대표 패턴으로 다뤄진다.1
이번 장의 목표는 거창하지 않다. 아주 작지만 제대로 된 스킬 하나를 만든다. 그리고 그 과정에서 디렉터리 구조, YAML frontmatter, 실행, 디버깅, 핫 리로드까지 한 번에 익힌다. 이 장을 끝낼 때쯤이면 당신은 더 이상 "좋은 스킬이 있나?"를 검색만 하는 사람이 아니라, "없으면 내가 만든다"라고 말하는 사람이 된다.
왜 첫 스킬은 주간 보고서여야 할까
주간 보고서 스킬은 첫 실습 주제로 아주 좋다. 이유는 세 가지다.
입력이 단순하다. 텍스트 메모 몇 개만 있어도 된다.
출력이 명확하다. 요약, 진행 상황, 막힘, 다음 계획으로 구조화하면 된다.
위험이 낮다. 결제, 배포, 삭제 같은 파괴적 작업이 없어 디버깅 부담이 작다.
무엇보다 이 스킬은 "에이전트가 내 일을 대신 생각하는 느낌"을 빨리 준다. 평소에는 아무 의미 없어 보이던 잡다한 메모가, 잘 만든 스킬을 통과하면 읽을 만한 보고서로 바뀐다. 이 순간이 꽤 짜릿하다. 바닷가재가 갑자기 비서처럼 보이기 시작하는 지점이다.
이번 장에서 만들 완성형
이번 실습에서는 기본 워크스페이스를 ~/.openclaw/workspace라고 가정하겠다. 다른 경로를 쓰고 있다면 그 경로로 바꿔서 따라 하면 된다.
우리가 만들 구조는 이렇다.
~/.openclaw/workspace/
├── skills/
│ └── weekly-report/
│ ├── SKILL.md
│ └── templates/
│ └── weekly-report-template.md
├── notes/
│ └── 2026-W17.md
└── reports/핵심은 간단하다. skills/weekly-report/ 안에는 스킬의 정의와 템플릿을 넣고, 실제 입력 자료는 notes/에 둔다. 결과물은 reports/에 저장하게 할 것이다. 이렇게 나누면 스킬 자체와 업무 데이터가 섞이지 않아 나중에 관리하기 쉽다.
OpenClaw 스킬은 기본적으로 하나의 디렉터리 + SKILL.md 구조다. 여기에 필요하면 스크립트, 참고 자료, 템플릿 같은 보조 파일을 덧붙인다.2 처음부터 거대한 자동화를 만들 필요는 없다. 이번 장에서는 "작동하는 작은 스킬"을 먼저 만들고, 그다음에 다듬는다.
1단계: 디렉터리 구조 만들기
먼저 폴더부터 만든다.
cd ~/.openclaw/workspace
mkdir -p skills/weekly-report/templates
mkdir -p notes reports여기서 중요한 것은 폴더 이름이다. 나중에 헷갈리지 않으려면 폴더 이름과 스킬 이름을 최대한 비슷하게 맞추는 편이 좋다. 사람도 덜 헷갈리고, 미래의 나도 덜 화를 낸다.
이제 입력 예시 파일도 하나 만들어 두자.
cat > notes/2026-W17.md <<'EOF'
- 랜딩 페이지 카피 1차 수정 완료
- 회원가입 전환율 2.8% -> 3.6% 개선
- 고객 인터뷰 3건 진행, 공통 불만은 가격표 위치가 눈에 안 띈다는 점
- 결제 오류 2건 재현, 원인은 모바일 Safari에서 약관 체크박스 렌더링 문제로 추정
- 블로그 글 2편 발행
- 파트너 제안서 초안 작성 중
- 다음 주 목표: 가격 섹션 개선, 결제 오류 수정, 제안서 발송
EOF이 메모는 일부러 조금 투박하게 만들었다. 실제 업무 메모는 원래 예쁘지 않다. 중요한 건 에이전트가 이런 거친 재료를 읽고도 사람다운 결과를 만들게 하는 것이다.
2단계: 출력 템플릿 만들기
초보자가 가장 많이 하는 실수는 스킬 본문에 모든 출력 규칙을 길게 적는 것이다. 물론 가능은 하지만, 금방 비대해진다. 그럴 때는 템플릿 파일을 분리하는 편이 낫다. OpenClaw 스킬은 SKILL.md 외에 템플릿이나 참고 파일을 함께 둘 수 있고, 본문에서 {baseDir}로 그 위치를 참조할 수 있다.3
아래 내용을 skills/weekly-report/templates/weekly-report-template.md로 저장하자.
# 주간 보고서
## 한 줄 요약
- 이번 주 핵심 성과를 1~2문장으로 정리한다.
## 이번 주에 끝낸 일
- 완료한 작업을 영향 중심으로 정리한다.
## 진행 중인 일
- 아직 끝나지 않았지만 의미 있는 진척이 있는 항목을 적는다.
## 막힘과 리스크
- 문제 원인, 영향, 확인이 더 필요한 점을 적는다.
## 다음 주 계획
- 다음 행동을 3개 이하로 정리한다.이 템플릿은 단순하지만 꽤 강력하다. 보고서 형식이 고정되면 결과가 안정되고, 에이전트가 쓸데없이 장르를 바꾸지 않는다. 어떤 날은 회고문처럼 쓰고, 어떤 날은 보도자료처럼 쓰는 불상사를 줄여 준다.
3단계: YAML frontmatter가 들어간 SKILL.md 작성하기
이제 진짜 주인공인 SKILL.md를 만든다. OpenClaw에서 스킬은 SKILL.md 상단의 frontmatter로 이름과 설명을 읽고, 아래의 마크다운 본문으로 실제 작업 절차를 이해한다. 최소한 name과 description은 있어야 한다.2
아래 내용을 skills/weekly-report/SKILL.md에 저장하자.
---
name: weekly-report
description: Turn weekly task notes or work logs into a concise Korean weekly report with accomplishments, blockers, and next steps.
user-invocable: true
---
# Weekly Report
Use this skill when the user asks for a weekly report, status update, 업무 요약, 주간 회고, or stakeholder update based on pasted notes or note files.
## Inputs needed
You need one of the following:
- note text pasted in chat
- one or more file paths that contain weekly notes
If the user provides neither, ask one short follow-up question asking for the note text or file path.
## Workflow
1. Read the supplied notes carefully.
2. Extract only concrete facts. Do not invent dates, numbers, or outcomes.
3. Merge duplicate items and group related work together.
4. Classify the material into completed work, in-progress work, blockers, and next steps.
5. Write the final answer in Korean.
6. Follow the structure in `{baseDir}/templates/weekly-report-template.md`.
7. Keep the report skimmable in under one minute.
8. If the user asks to save the report, write it to `reports/weekly-<year>-<week>.md`.
## Guardrails
- Prefer impact over raw activity.
- If a point is uncertain, mark it as `확인 필요`.
- Do not copy secrets, tokens, or credentials even if they appear in the notes.
- Do not turn assumptions into facts.
## Quality check before sending
- Can a busy stakeholder understand this in one read?
- Are blockers explicit?
- Are next steps concrete?
- Is every claim grounded in the supplied notes?여기서 눈여겨볼 부분이 있다.
첫째, description은 짧지만 구체적이어야 한다. 이 한 줄이 스킬의 간판이다. 너무 넓으면 아무 데나 불려 나가고, 너무 모호하면 아예 안 불린다. "업무를 도와주는 스킬" 같은 설명은 사실상 없는 것과 비슷하다.
둘째, 본문은 광고문이 아니라 작업 런북이어야 한다. "이 스킬은 아주 똑똑합니다" 같은 문장은 필요 없다. 대신 무엇을 읽고, 어떤 기준으로 정리하고, 무엇은 절대 하지 말아야 하는지를 적어야 한다.
셋째, {baseDir}를 쓴 부분이 중요하다. 이 경로는 현재 스킬 폴더를 가리키므로, 템플릿 파일을 안정적으로 참조할 수 있다.3
description이 중요한 이유
처음 스킬을 만들면 대부분 본문에 힘을 너무 많이 준다. 그런데 실제로는 description이 생각보다 큰 역할을 한다. 이 한 줄이 선명해야 에이전트가 "아, 이건 저 스킬 차례구나"라고 알아차린다.
예를 들어 아래 설명은 별로다.
description: Help with work summaries.너무 넓고, 너무 평범하다. 반면 아래 설명은 훨씬 낫다.
description: Turn weekly task notes or work logs into a concise Korean weekly report with accomplishments, blockers, and next steps.이 문장은 무엇을 입력으로 받고, 어떤 결과를 만들며, 어떤 구조를 기대하는지까지 드러낸다. 좋은 description은 에이전트에게 주는 미니 안내문이다. 짧을수록 좋다는 뜻이 아니라, 짧지만 식별 가능해야 한다는 뜻이다.
4단계: 스킬을 OpenClaw에 반영하기
스킬 파일을 만들었다고 즉시 끝나는 것은 아니다. OpenClaw가 새 스킬을 인식해야 한다. 가장 쉬운 방법은 에이전트에게 refresh skills라고 말하거나, 새 세션을 시작하거나, 필요하면 게이트웨이를 재시작하는 것이다.2
설정상 스킬 워처가 켜져 있으면 변경 사항은 다음 턴에 반영될 수 있다. 기본 설정에는 skills.load.watch: true가 들어가며, 수정 내용은 보통 다음 에이전트 턴에서 새 스냅샷으로 반영된다.4 다만 실제 환경에서는 세션 캐시 때문에 즉시 안 보일 때가 있으니, 처음에는 이렇게 기억하면 된다.
안 보이면 세 가지를 순서대로 해본다.
refresh skills를 요청한다.새 세션을 연다.
그래도 이상하면 게이트웨이를 재시작한다.
처음엔 이 정도면 충분하다. 세상 모든 버그를 한 번에 이해할 필요는 없다.
5단계: 첫 실행
이제 스킬을 불러본다. 가장 쉬운 테스트는 CLI다.
openclaw agent --message "notes/2026-W17.md를 바탕으로 이번 주 보고서를 작성해줘"또는 Telegram에서 이렇게 말해도 된다.
notes/2026-W17.md기준으로 주간 보고서 만들어줘.
스킬이 잘 잡히면 에이전트는 메모 파일을 읽고, 우리가 만든 템플릿 구조에 맞춰 한국어 보고서를 만든다. 예상되는 결과는 대략 이런 느낌이다.
# 주간 보고서
## 한 줄 요약
- 랜딩 페이지와 결제 흐름 개선에 집중했고, 회원가입 전환율이 2.8%에서 3.6%로 상승했다.
## 이번 주에 끝낸 일
- 랜딩 페이지 카피 1차 수정 완료
- 블로그 글 2편 발행
- 고객 인터뷰 3건 진행 후 주요 불만 포인트 정리
## 진행 중인 일
- 파트너 제안서 초안 작성 중
- 모바일 Safari 결제 오류 원인 분석 진행 중
## 막힘과 리스크
- 모바일 Safari에서 약관 체크박스 렌더링 문제로 결제 오류가 발생할 가능성이 있어 확인이 더 필요함
## 다음 주 계획
- 가격 섹션 가시성 개선
- 결제 오류 수정
- 파트너 제안서 발송여기서 중요한 것은 문장이 얼마나 멋지냐가 아니다. 입력 메모의 사실을 버리지 않으면서, 읽기 쉬운 구조로 바꿨느냐가 핵심이다.
6단계: 저장까지 시켜 보기
이번에는 보고서를 파일로 저장하게 해보자.
openclaw agent --message "notes/2026-W17.md를 바탕으로 주간 보고서를 만들고 reports/weekly-2026-W17.md에 저장해줘"우리가 SKILL.md의 워크플로에 "사용자가 저장을 요청하면 reports/에 쓴다"고 적어 두었기 때문에, 에이전트는 이 요구를 더 안정적으로 따른다. 이게 바로 스킬의 힘이다. 평소 같으면 같은 지시를 매번 길게 설명해야 하지만, 이제는 스킬이 그 문맥을 대신 기억한다.
이 시점에서 독자는 슬슬 이런 생각이 들 것이다. "아, 이건 그냥 프롬프트를 예쁘게 적는 게 아니구나." 맞다. 스킬은 반복 작업에 대한 조직화된 기억이다.
7단계: 잘 안 될 때 디버깅하는 법
첫 스킬은 거의 반드시 한 번쯤 삐끗한다. 하지만 대부분의 문제는 생각보다 단순하다.
스킬이 아예 안 보일 때
가장 먼저 볼 것은 경로와 파일명이다. 스킬은 디렉터리 안의 SKILL.md를 기준으로 로드된다.2 파일명이 skill.md처럼 소문자면 안 잡히는 경우가 있고, 폴더 위치가 skills/ 밖이면 당연히 인식되지 않는다.
그다음에는 frontmatter 문법을 확인한다. 여는 ---는 있는데 닫는 ---가 없거나, 들여쓰기가 이상하면 파싱에 실패할 수 있다. 아주 사소한 오타 하나가 스킬 전체를 유령으로 만든다.
스킬은 보이는데 호출이 안 될 때
이 경우는 보통 description이 흐리거나, 사용자의 표현과 스킬 설명이 잘 안 맞는 경우다. 예를 들어 스킬 설명에는 weekly report만 적혀 있는데, 사용자는 "업무 회고 정리해줘"라고 말하면 매칭이 약해질 수 있다.
이럴 때는 description이나 본문 첫 문장에 실제로 쓸 표현을 더 넣어 주면 된다. 이번 예시처럼 weekly report, status update, 업무 요약, 주간 회고를 같이 적는 방식이 초반에는 꽤 효과적이다.
결과가 너무 장황할 때
이건 스킬이 너무 자유롭다는 뜻이다. 해결책은 두 가지다. 템플릿을 더 빡빡하게 만들거나, Quality check 항목에 "1분 안에 읽히게 하라" 같은 기준을 넣는 것이다.
에이전트는 대체로 친절해서 문제다. 친절하다 못해 장광설을 늘어놓는다. 스킬은 그 친절함을 보고서형 절제미로 바꾸는 장치라고 생각하면 된다.
파일은 읽는데 저장이 실패할 때
경로가 실제로 존재하는지 먼저 확인하자. reports/ 디렉터리를 안 만들어 둔 채 저장만 시키면 실패할 수 있다. 권한 문제가 있는 환경이라면 워크스페이스 안에서 먼저 테스트하는 편이 안전하다.
게이트웨이 상태가 수상할 때
이럴 땐 감으로 때려맞히지 말고 기본 도구를 쓰는 편이 빠르다. openclaw logs --follow로 실시간 로그를 보고, openclaw doctor로 환경 문제를 검사하고, MCP 연동이 섞였다면 openclaw channels status --probe로 채널 상태를 확인할 수 있다.5
개발 중 잠깐 설정을 바꿔 보고 싶을 때는 /debug가 유용하다. 이 명령은 메모리에서만 바뀌고 디스크 설정은 건드리지 않으므로, 실험 후 reset으로 쉽게 원복할 수 있다.6
8단계: 핫 리로드를 이용해 스킬을 키우기
이제 가장 재미있는 구간이다. 스킬은 한 번 만들고 끝나는 문서가 아니다. 살아 있는 작업 습관이다.
예를 들어 첫 실행 결과가 너무 실무자 메모처럼 나오고, 경영진 보고서 느낌이 부족했다고 해보자. 그럼 templates/weekly-report-template.md를 이렇게 바꿔볼 수 있다.
# 주간 보고서
## 핵심 성과
- 이번 주 비즈니스에 영향을 준 성과만 3개 이하로 적는다.
## 주요 진척
- 완료하거나 크게 진전된 일을 적는다.
## 리스크와 대응 필요 사항
- 현재 문제와 필요한 결정을 적는다.
## 다음 주 우선순위
- 반드시 실행할 3가지 행동만 적는다.저장한 뒤 다시 요청하면 다음 턴부터 결과 톤이 달라진다. 워처가 켜져 있다면 이런 수정은 꽤 빠르게 체감된다.4
핫 리로드를 제대로 활용하면 스킬 개발이 무척 가벼워진다. 보통은 이런 루프로 움직인다.
실행한다.
어색한 결과를 본다.
SKILL.md나 템플릿을 조금 고친다.다시 실행한다.
더 좋아진 결과를 본다.
이 반복이 몇 번 쌓이면, 스킬은 어느새 "그럴듯한 데모"가 아니라 "내 스타일을 아는 실무 도구"가 된다.
첫 스킬을 더 유용하게 만드는 개조 아이디어
이번 장의 예제는 일부러 가장 단순한 버전으로 만들었다. 하지만 여기서 조금만 손보면 금방 실전형이 된다.
메모 파일을 하나만 읽는 대신,
notes/안 최근 7일 파일을 묶어 읽게 만들 수 있다.보고서 말투를
SOUL.md와 맞춰 더 딱딱한 경영 보고체나 더 친근한 팀 공유체로 바꿀 수 있다.저장 경로 규칙을 고정해
reports/weekly-YYYY-WW.md파일명을 자동 생성하게 다듬을 수 있다.
중요한 것은 기능을 마구 늘리는 것이 아니다. 반복되는 귀찮음을 한 번에 줄이는 방향으로만 키우는 것이다. 첫 스킬은 작을수록 성공 확률이 높다.
이 장에서 꼭 가져가야 할 감각
이번 실습에서 배워야 할 것은 문법 몇 줄이 아니다. 더 중요한 것은 다음 감각이다.
스킬은 거대한 코드 프로젝트가 아니라, 에이전트가 일을 더 일관되게 하도록 만드는 작은 운영 문서라는 것. 그리고 그 운영 문서가 템플릿, 경로 규칙, 금지 사항, 출력 기준을 품기 시작하는 순간, 단순한 프롬프트보다 훨씬 오래 살아남는 자산이 된다는 것이다.
주간 보고서 스킬은 그 첫 경험으로 아주 좋다. 결과가 눈에 보이고, 실패해도 안전하고, 조금만 다듬어도 바로 실무에 투입할 수 있기 때문이다.
이제 당신은 스킬을 설치하는 사람에서 스킬을 만드는 사람으로 넘어왔다. 다음 장에서는 이 개인 스킬을 넘어, 커뮤니티가 만든 스킬을 어떻게 골라 쓰고, 어떻게 가져다 내 워크플로우에 붙일지 살펴보게 된다. 하지만 그 전에, 방금 만든 weekly-report를 한두 번 더 고쳐 보자. 대개 진짜 실력은 두 번째 수정부터 붙기 시작한다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.