cdsa-harness 0.14.0 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdsa-harness",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {

package/skills/answer.md

@@ -1,6 +1,11 @@
 ---
+argument-hint: "<민원 내용 또는 파일경로>"
 description: 민원 답변서(회신문) 초안 작성 [공공]
 ---
-다음 민원에 대한 답변서(회신문) 초안을 작성해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).
+아래 [민원]에 대한 답변서(회신문) 초안을 작성해줘.
+※ [민원]이 명백한 파일 경로면 read_file 로 읽고, 아니면 그 문장 자체를 민원으로 본다(파일을 찾지 마라).
 구성: 인사말 / 민원요지 요약 / 검토결과(근거·관련규정[   ]) / 조치사항 / 맺음말.
-정중하고 공감하는 공공 민원 답변 문체로. 단정이 어려운 부분은 '확인 후 안내' 로 표시.
+정중하고 공감하는 공공 민원 답변 문체로. 단정이 어려운 부분은 '확인 후 안내'로 표시.
+
+[민원]
+$ARGUMENTS

package/skills/briefing.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<보도협조 주제>"
 description: 보도협조(브리핑) 요청문·요약 작성 [공공]
 ---
 "$ARGUMENTS" 를 주제로 언론 보도협조 요청문을 작성해줘.

package/skills/budget.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<예산 내용 또는 파일경로>"
 description: 예산(안) 항목을 검토·요약하고 점검 포인트 제시 [공공]
 ---
 $ARGUMENTS (파일명이면 read_file 로 읽어)의 예산 내용을 한국어로 정리해줘.

package/skills/eli5.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<파일명 또는 개념>"
 description: 지정한 파일/개념을 5살도 알게 아주 쉽게 설명
 ---
 $ARGUMENTS 을(를) 다섯 살 아이도 이해할 수 있게 아주 쉬운 비유로 설명해줘.

package/skills/explain.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<파일명 또는 대상>"
 description: 파일/코드를 읽고 비개발자도 알게 쉽게 설명
 ---
 $ARGUMENTS 을(를) read_file 도구로 읽고, 무엇을 하는 코드/문서인지

package/skills/gongmun.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<공문 주제·내용>"
 description: 공문서(기안문) 초안 작성 — 제목/수신/본문/붙임 [공공]
 ---
 "$ARGUMENTS" 내용을 바탕으로 대한민국 행정 공문서(기안문) 초안을 작성해줘.

package/skills/haiku.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<주제 또는 파일명>"
 description: 파일이나 주제로 하이쿠(짧은 3줄 시) 짓기 — 재미용
 ---
 $ARGUMENTS (파일명이면 read_file 로 그 내용을 읽어)를 주제로,

package/skills/hwpx.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<파일.hwpx>"
 description: 한컴 HWPX(.hwpx) 문서를 읽어 핵심을 개조식으로 요약 [공공]
 ---
 $ARGUMENTS 파일을 hwpx_read 도구로 읽어 본문 텍스트를 추출한 뒤,

package/skills/insa.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<인사발령 내용>"
 description: 인사발령 공지문 초안 작성 [공공]
 ---
 "$ARGUMENTS" 내용을 바탕으로 인사발령 공지문 초안을 작성해줘.

package/skills/loop.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<요청>"
 description: 이 요청을 '에이전트 루프' 관점에서 어떻게 처리할지 메타 해설 (CDSA 특별)
 ---
 다음 요청을 실제로 수행하기 전에, CDSA Harness 의 에이전트 루프

package/skills/minutes.md

@@ -1,7 +1,10 @@
 ---
+argument-hint: "<회의 내용 또는 파일경로>"
 description: 회의 내용을 표준 회의록으로 정리(안건/논의/결정/조치) [공공]
 ---
-$ARGUMENTS (파일명이면 read_file 로 읽어)를 회의록으로 정리해줘.
-머리말: 일시[   ] / 장소[   ] / 참석[   ].
-본문: 안건별로 [논의내용] · [결정사항] · [조치사항(담당/기한)] 을 개조식으로.
-한국어로 깔끔하게. 파일은 수정하지 마.
+아래 [회의내용]을 회의록으로 정리해줘.
+※ [회의내용]이 명백한 파일 경로면 read_file 로 읽고, 아니면 그 문장 자체를 대상으로 본다.
+머리말: 일시[   ]/장소[   ]/참석[   ]. 본문: 안건별 [논의내용]·[결정사항]·[조치(담당/기한)]. 개조식. 파일은 수정하지 마.
+
+[회의내용]
+$ARGUMENTS

package/skills/minwon.md

@@ -1,7 +1,11 @@
 ---
+argument-hint: "<민원 내용 또는 파일경로>"
 description: 민원 내용을 분류(분야·담당부서·긴급도)하고 처리 방향 제안 [공공]
 ---
-다음 민원을 분석해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).
-표 형태로 한국어로 깔끔하게 정리해줘:
-1) 분야 분류  2) 담당 부서(추정)  3) 긴급도(상/중/하)  4) 핵심 요지 1줄  5) 처리 방향 제안
-개인정보(연락처·주민번호 등)가 보이면 마스킹해서 표시해줘. 파일은 수정하지 마.
+아래 [민원]을 분석해줘.
+※ [민원]이 `notes.txt`·`민원.hwpx` 같은 **파일 경로 형식**이면 먼저 read_file(.hwpx 는 hwpx_read)로 읽어 그 내용을 민원으로 삼고, 그 외 일반 문장이면 **그 문장 자체가 민원**이다(파일을 찾지 마라).
+표로 한국어 정리: 1) 분야 분류 2) 담당 부서(추정) 3) 긴급도(상/중/하) 4) 핵심 요지 1줄 5) 처리 방향 제안.
+개인정보가 보이면 마스킹. 파일은 수정하지 마.
+
+[민원]
+$ARGUMENTS

package/skills/notice.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<공고 주제·내용>"
 description: 공고문(모집·입찰·안내) 초안 작성 [공공]
 ---
 "$ARGUMENTS" 를 주제로 공공 공고문 초안을 작성해줘.

package/skills/plan.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<할 작업>"
 description: 시킨 작업을 '실행하지 말고' 단계별 계획만 세우기
 ---
 다음 작업을 실제로 수행하지 말고, 어떻게 처리할지 단계별 계획만 세워줘: $ARGUMENTS

package/skills/policyqa.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<질문>"
 description: 정책·제도 질문에 근거를 들어 설명(모르면 모른다고) [공공]
 ---
 다음 질문에 공공 정책·행정 관점에서 한국어로 답해줘: $ARGUMENTS

package/skills/press.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<보도 주제>"
 description: 보도자료 초안 작성(제목/부제/리드/본문/문의처) [공공]
 ---
 "$ARGUMENTS" 를 주제로 공공기관 보도자료 초안을 작성해줘.

package/skills/privacy.md

@@ -1,7 +1,10 @@
 ---
+argument-hint: "<점검할 텍스트 또는 파일경로>"
 description: 개인정보(주민번호·연락처·이메일·계좌 등) 점검 및 마스킹 제안 [공공]
 ---
-$ARGUMENTS (파일명이면 read_file 로 읽어)에서 개인정보로 보이는 항목
-(주민등록번호, 휴대전화, 이메일, 주소, 계좌·카드번호, 여권번호 등)을 찾아
-'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리해줘.
-하나도 없으면 없다고 명확히 말해줘. 파일은 절대 수정하지 말고 점검 보고만 해줘.
+아래 [대상]에서 개인정보로 보이는 항목(주민등록번호·휴대전화·이메일·주소·계좌/카드번호·여권번호 등)을 찾아줘.
+※ [대상]이 명백한 파일 경로면 read_file(.hwpx 는 hwpx_read)로 읽고, 아니면 그 문장 자체를 점검 대상으로 본다.
+'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리. 없으면 없다고 명확히. 파일은 수정하지 말고 점검 보고만.
+
+[대상]
+$ARGUMENTS

package/skills/quiz.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "[주제(선택)]"
 description: 작업 폴더 코드/문서로 학습 퀴즈 만들기
 ---
 작업 폴더를 list_dir / read_file 로 살펴보고, 이 코드·문서를 공부할 수 있는

package/skills/report.md

@@ -1,6 +1,10 @@
 ---
+argument-hint: "<요약할 내용 또는 파일경로>"
 description: 개조식 1쪽 보고서로 요약(추진배경/현황/문제점/개선방안) [공공]
 ---
-$ARGUMENTS (파일명이면 read_file 로 읽어)를 대한민국 공공 보고서 양식의 개조식으로
-1쪽 분량으로 요약해줘. 항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과.
-각 항목은 'ㅇ' 글머리로 간결하게. 파일은 수정하지 마.
+아래 [내용]을 대한민국 공공 보고서 양식의 개조식으로 1쪽 요약해줘.
+※ [내용]이 명백한 파일 경로면 read_file(.hwpx 는 hwpx_read)로 읽고, 아니면 그 문장 자체를 대상으로 본다.
+항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과. 각 항목 'ㅇ' 글머리. 파일은 수정하지 마.
+
+[내용]
+$ARGUMENTS

package/skills/review.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<파일명>"
 description: 파일을 읽고 버그 위험·개선점을 리뷰
 ---
 $ARGUMENTS 파일을 read_file 도구로 읽고, 버그 위험·가독성·개선점을 한국어로 짚어줘.

package/skills/rubberduck.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<고민·문제>"
 description: 러버덕 디버깅 — 답 대신 질문으로 스스로 찾게 돕기
 ---
 당신은 '러버덕(고무오리)' 디버깅 파트너입니다. 사용자의 고민: $ARGUMENTS

package/skills/summarize.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "<파일명>"
 description: 지정한 파일을 읽고 한국어 3줄로 요약
 ---
 $ARGUMENTS 파일을 read_file 도구로 읽은 다음, 핵심 내용을 한국어 3줄로 요약해줘.

package/skills/todo.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "[대상(선택)]"
 description: 작업 폴더에서 TODO/FIXME 주석을 모아 목록화
 ---
 작업 폴더의 파일들을 list_dir / read_file 로 훑어 TODO, FIXME, XXX, HACK 같은

package/skills/tour.md

@@ -1,4 +1,5 @@
 ---
+argument-hint: "[주제(선택)]"
 description: 작업 폴더를 둘러보고 이 프로젝트가 무엇인지 브리핑
 ---
 작업 폴더를 list_dir 로 살펴보고, 핵심으로 보이는 파일 2~4개를 read_file 로 읽어

package/src/builtins.js

@@ -2,7 +2,7 @@
 // 스킬/플러그인/버전을 바꾼 뒤 `node scripts/gen-builtins.mjs` 로 재생성하세요.
 import p0 from "../plugins/hwpx_read.mjs";
 
-export const VERSION = "0.14.0";
+export const VERSION = "0.14.2";
 
 export const BUILTIN_PLUGINS = [p0];
 
@@ -10,121 +10,145 @@ export const BUILTIN_SKILLS = [
   {
     "name": "answer",
     "description": "민원 답변서(회신문) 초안 작성 [공공]",
-    "body": "다음 민원에 대한 답변서(회신문) 초안을 작성해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).\n구성: 인사말 / 민원요지 요약 / 검토결과(근거·관련규정[   ]) / 조치사항 / 맺음말.\n정중하고 공감하는 공공 민원 답변 문체로. 단정이 어려운 부분은 '확인 후 안내' 로 표시."
+    "hint": "<민원 내용 또는 파일경로>",
+    "body": "아래 [민원]에 대한 답변서(회신문) 초안을 작성해줘.\n※ [민원]이 명백한 파일 경로면 read_file 로 읽고, 아니면 그 문장 자체를 민원으로 본다(파일을 찾지 마라).\n구성: 인사말 / 민원요지 요약 / 검토결과(근거·관련규정[   ]) / 조치사항 / 맺음말.\n정중하고 공감하는 공공 민원 답변 문체로. 단정이 어려운 부분은 '확인 후 안내'로 표시.\n\n[민원]\n$ARGUMENTS"
   },
   {
     "name": "briefing",
     "description": "보도협조(브리핑) 요청문·요약 작성 [공공]",
+    "hint": "<보도협조 주제>",
     "body": "\"$ARGUMENTS\" 를 주제로 언론 보도협조 요청문을 작성해줘.\n구성: 제목 / 협조요청 취지 / 핵심 메시지 3가지 / 일정·자료 / 담당자 연락처[   ].\n객관적이고 간결하게 한국어로. 과장 표현은 피해줘."
   },
   {
     "name": "budget",
     "description": "예산(안) 항목을 검토·요약하고 점검 포인트 제시 [공공]",
+    "hint": "<예산 내용 또는 파일경로>",
     "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)의 예산 내용을 한국어로 정리해줘.\n1) 총액·주요 항목 표(항목 / 금액 / 비중)  2) 전년 대비/특이사항  3) 점검 포인트(과다·누락·근거 불명).\n숫자는 그대로 인용하고, 계산이 필요하면 근거를 함께 보여줘. 파일은 수정하지 마."
   },
   {
     "name": "eli5",
     "description": "지정한 파일/개념을 5살도 알게 아주 쉽게 설명",
+    "hint": "<파일명 또는 개념>",
     "body": "$ARGUMENTS 을(를) 다섯 살 아이도 이해할 수 있게 아주 쉬운 비유로 설명해줘.\n파일 이름이면 read_file 로 읽고 설명해. 전문용어는 풀어서 쓰고, 그림 그리듯 비유를 들어줘.\n파일은 수정하지 마."
   },
   {
     "name": "explain",
     "description": "파일/코드를 읽고 비개발자도 알게 쉽게 설명",
+    "hint": "<파일명 또는 대상>",
     "body": "$ARGUMENTS 을(를) read_file 도구로 읽고, 무엇을 하는 코드/문서인지\n비개발자도 이해할 수 있게 한국어로 차근차근 설명해줘. 실제 수정은 하지 마."
   },
   {
     "name": "gongmun",
     "description": "공문서(기안문) 초안 작성 — 제목/수신/본문/붙임 [공공]",
+    "hint": "<공문 주제·내용>",
     "body": "\"$ARGUMENTS\" 내용을 바탕으로 대한민국 행정 공문서(기안문) 초안을 작성해줘.\n형식: 제목 / 수신 / (경유) / 본문(개조식, 'ㅇ' 글머리) / 붙임.\n정중한 공공 문체로. 사실이 불확실한 부분은 [   ] 로 비워 '채울 항목'임을 표시해줘."
   },
   {
     "name": "haiku",
     "description": "파일이나 주제로 하이쿠(짧은 3줄 시) 짓기 — 재미용",
+    "hint": "<주제 또는 파일명>",
     "body": "$ARGUMENTS (파일명이면 read_file 로 그 내용을 읽어)를 주제로,\n5-7-5 운율을 살린 한국어 하이쿠를 한 편 지어줘. 짧고 운치 있게.\n파일은 절대 건드리지 말고 시만 보여줘."
   },
   {
     "name": "hwpx",
     "description": "한컴 HWPX(.hwpx) 문서를 읽어 핵심을 개조식으로 요약 [공공]",
+    "hint": "<파일.hwpx>",
     "body": "$ARGUMENTS 파일을 hwpx_read 도구로 읽어 본문 텍스트를 추출한 뒤,\n핵심 내용을 한국어 개조식('ㅇ' 글머리)으로 요약해줘. 파일은 수정하지 마.\n(.hwp 구버전이면 .hwpx 로 저장 후 다시 시도하라고 안내해줘.)"
   },
   {
     "name": "insa",
     "description": "인사발령 공지문 초안 작성 [공공]",
+    "hint": "<인사발령 내용>",
     "body": "\"$ARGUMENTS\" 내용을 바탕으로 인사발령 공지문 초안을 작성해줘.\n형식: 제목 / 발령일자[   ] / 대상자(직위·성명·소속) 표 / 발령내용(전보·승진·신규 등) / 비고.\n정중한 공공 문체로. 확실하지 않은 항목은 [   ] 로 비워둬. 파일은 수정하지 마."
   },
   {
     "name": "loop",
     "description": "이 요청을 '에이전트 루프' 관점에서 어떻게 처리할지 메타 해설 (CDSA 특별)",
+    "hint": "<요청>",
     "body": "다음 요청을 실제로 수행하기 전에, CDSA Harness 의 에이전트 루프\n(컨텍스트 구성 → LLM 호출 → 도구 판단 → 실행 → 결과 되먹임) 관점에서\n어떤 도구를 어떤 순서로 부를 계획인지 단계별로 한국어로 먼저 설명해줘: $ARGUMENTS\n설명만 하고, 이번에는 실제 도구 호출(특히 write_file)은 하지 마."
   },
   {
     "name": "minutes",
     "description": "회의 내용을 표준 회의록으로 정리(안건/논의/결정/조치) [공공]",
-    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)를 회의록으로 정리해줘.\n머리말: 일시[   ] / 장소[   ] / 참석[   ].\n본문: 안건별로 [논의내용] · [결정사항] · [조치사항(담당/기한)] 을 개조식으로.\n한국어로 깔끔하게. 파일은 수정하지 마."
+    "hint": "<회의 내용 또는 파일경로>",
+    "body": "아래 [회의내용]을 회의록으로 정리해줘.\n※ [회의내용]이 명백한 파일 경로면 read_file 로 읽고, 아니면 그 문장 자체를 대상으로 본다.\n머리말: 일시[   ]/장소[   ]/참석[   ]. 본문: 안건별 [논의내용]·[결정사항]·[조치(담당/기한)]. 개조식. 파일은 수정하지 마.\n\n[회의내용]\n$ARGUMENTS"
   },
   {
     "name": "minwon",
     "description": "민원 내용을 분류(분야·담당부서·긴급도)하고 처리 방향 제안 [공공]",
-    "body": "다음 민원을 분석해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).\n표 형태로 한국어로 깔끔하게 정리해줘:\n1) 분야 분류  2) 담당 부서(추정)  3) 긴급도(상/중/하)  4) 핵심 요지 1줄  5) 처리 방향 제안\n개인정보(연락처·주민번호 등)가 보이면 마스킹해서 표시해줘. 파일은 수정하지 마."
+    "hint": "<민원 내용 또는 파일경로>",
+    "body": "아래 [민원]을 분석해줘.\n※ [민원]이 `notes.txt`·`민원.hwpx` 같은 **파일 경로 형식**이면 먼저 read_file(.hwpx 는 hwpx_read)로 읽어 그 내용을 민원으로 삼고, 그 외 일반 문장이면 **그 문장 자체가 민원**이다(파일을 찾지 마라).\n표로 한국어 정리: 1) 분야 분류 2) 담당 부서(추정) 3) 긴급도(상/중/하) 4) 핵심 요지 1줄 5) 처리 방향 제안.\n개인정보가 보이면 마스킹. 파일은 수정하지 마.\n\n[민원]\n$ARGUMENTS"
   },
   {
     "name": "notice",
     "description": "공고문(모집·입찰·안내) 초안 작성 [공공]",
+    "hint": "<공고 주제·내용>",
     "body": "\"$ARGUMENTS\" 를 주제로 공공 공고문 초안을 작성해줘.\n형식: 제목 / 공고번호[   ] / 목적 / 대상·자격 / 기간·일정 / 신청방법 / 문의처[   ] / 붙임.\n간결하고 명확한 공고 문체로 한국어 작성."
   },
   {
     "name": "plan",
     "description": "시킨 작업을 '실행하지 말고' 단계별 계획만 세우기",
+    "hint": "<할 작업>",
     "body": "다음 작업을 실제로 수행하지 말고, 어떻게 처리할지 단계별 계획만 세워줘: $ARGUMENTS\n필요하면 read_file / list_dir 로 사실만 확인하되, write_file 은 절대 호출하지 마.\n각 단계마다 '왜 그 단계가 필요한지'도 한 줄씩 덧붙여줘."
   },
   {
     "name": "policyqa",
     "description": "정책·제도 질문에 근거를 들어 설명(모르면 모른다고) [공공]",
+    "hint": "<질문>",
     "body": "다음 질문에 공공 정책·행정 관점에서 한국어로 답해줘: $ARGUMENTS\n필요하면 작업 폴더의 관련 문서를 read_file 로 확인해 근거로 삼아.\n확실하지 않은 부분은 추측하지 말고 '확인 필요'로 표시하고, 어디서/누구에게 확인하면 되는지 안내해줘."
   },
   {
     "name": "press",
     "description": "보도자료 초안 작성(제목/부제/리드/본문/문의처) [공공]",
+    "hint": "<보도 주제>",
     "body": "\"$ARGUMENTS\" 를 주제로 공공기관 보도자료 초안을 작성해줘.\n구성: 제목 / 부제 / 리드(핵심 1문단) / 본문(육하원칙) / 기대효과 / 문의처[   ].\n객관적이고 간결한 보도 문체로 한국어로 작성해줘."
   },
   {
     "name": "privacy",
     "description": "개인정보(주민번호·연락처·이메일·계좌 등) 점검 및 마스킹 제안 [공공]",
-    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)에서 개인정보로 보이는 항목\n(주민등록번호, 휴대전화, 이메일, 주소, 계좌·카드번호, 여권번호 등)을 찾아\n'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리해줘.\n하나도 없으면 없다고 명확히 말해줘. 파일은 절대 수정하지 말고 점검 보고만 해줘."
+    "hint": "<점검할 텍스트 또는 파일경로>",
+    "body": "아래 [대상]에서 개인정보로 보이는 항목(주민등록번호·휴대전화·이메일·주소·계좌/카드번호·여권번호 등)을 찾아줘.\n※ [대상]이 명백한 파일 경로면 read_file(.hwpx 는 hwpx_read)로 읽고, 아니면 그 문장 자체를 점검 대상으로 본다.\n'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리. 없으면 없다고 명확히. 파일은 수정하지 말고 점검 보고만.\n\n[대상]\n$ARGUMENTS"
   },
   {
     "name": "quiz",
     "description": "작업 폴더 코드/문서로 학습 퀴즈 만들기",
+    "hint": "[주제(선택)]",
     "body": "작업 폴더를 list_dir / read_file 로 살펴보고, 이 코드·문서를 공부할 수 있는\n객관식 퀴즈 3문제를 한국어로 만들어줘($ARGUMENTS 주제가 있으면 그쪽으로).\n각 문제에 보기 4개와 정답, 그리고 한 줄 해설을 달아줘. 파일은 수정하지 마."
   },
   {
     "name": "report",
     "description": "개조식 1쪽 보고서로 요약(추진배경/현황/문제점/개선방안) [공공]",
-    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)를 대한민국 공공 보고서 양식의 개조식으로\n1쪽 분량으로 요약해줘. 항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과.\n각 항목은 'ㅇ' 글머리로 간결하게. 파일은 수정하지 마."
+    "hint": "<요약할 내용 또는 파일경로>",
+    "body": "아래 [내용]을 대한민국 공공 보고서 양식의 개조식으로 1쪽 요약해줘.\n※ [내용]이 명백한 파일 경로면 read_file(.hwpx 는 hwpx_read)로 읽고, 아니면 그 문장 자체를 대상으로 본다.\n항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과. 각 항목 'ㅇ' 글머리. 파일은 수정하지 마.\n\n[내용]\n$ARGUMENTS"
   },
   {
     "name": "review",
     "description": "파일을 읽고 버그 위험·개선점을 리뷰",
+    "hint": "<파일명>",
     "body": "$ARGUMENTS 파일을 read_file 도구로 읽고, 버그 위험·가독성·개선점을 한국어로 짚어줘.\n실제 수정은 하지 말고, 무엇을 어떻게 고치면 좋을지 제안만 해줘."
   },
   {
     "name": "rubberduck",
     "description": "러버덕 디버깅 — 답 대신 질문으로 스스로 찾게 돕기",
+    "hint": "<고민·문제>",
     "body": "당신은 '러버덕(고무오리)' 디버깅 파트너입니다. 사용자의 고민: $ARGUMENTS\n바로 정답을 주지 말고, 문제를 좁히는 좋은 질문 3~5개를 한국어로 던져줘.\n필요하면 read_file 로 관련 파일을 살펴봐도 되지만, 절대 수정하지 마.\n마지막에 \"이 중 어디부터 확인해볼까요?\" 라고 물어줘."
   },
   {
     "name": "summarize",
     "description": "지정한 파일을 읽고 한국어 3줄로 요약",
+    "hint": "<파일명>",
     "body": "$ARGUMENTS 파일을 read_file 도구로 읽은 다음, 핵심 내용을 한국어 3줄로 요약해줘.\n파일을 수정하지는 말고, 요약만 보여줘."
   },
   {
     "name": "todo",
     "description": "작업 폴더에서 TODO/FIXME 주석을 모아 목록화",
+    "hint": "[대상(선택)]",
     "body": "작업 폴더의 파일들을 list_dir / read_file 로 훑어 TODO, FIXME, XXX, HACK 같은\n미완성 표시가 있는 곳을 찾아 '파일 — 해당 줄 내용' 형태의 한국어 목록으로 정리해줘.\n하나도 없으면 없다고 분명히 말해줘. 파일은 수정하지 마."
   },
   {
     "name": "tour",
     "description": "작업 폴더를 둘러보고 이 프로젝트가 무엇인지 브리핑",
+    "hint": "[주제(선택)]",
     "body": "작업 폴더를 list_dir 로 살펴보고, 핵심으로 보이는 파일 2~4개를 read_file 로 읽어\n이 프로젝트가 무엇이고 어떤 구조인지 한국어로 친절하게 브리핑해줘.\n$ARGUMENTS 가 있으면 그 주제에 초점을 맞춰. 파일은 절대 수정하지 마."
   }
 ];

package/src/cli.js

@@ -247,7 +247,7 @@ async function buildExtensions(cfg, mcp) {
     ...mcp.errors.map((e) => ({ error: `MCP ${e}` })),
   ];
   const skills = {};
-  for (const s of npm.skills) skills[s.name] = { name: s.name, description: s.description || "", body: s.body, source: "(npm)" };
+  for (const s of npm.skills) skills[s.name] = { name: s.name, description: s.description || "", hint: s.hint || "", body: s.body, source: "(npm)" };
   Object.assign(
     skills,
     loadSkills(cfg.workspacePath(), { importForeign: cfg.import_foreign_skills, extraDirs: cfg.skill_dirs || [] })
@@ -796,8 +796,12 @@ export async function main(argv = []) {
         return c.dim("📄 파일");
       };
       const lines = names.length
-        ? names.map((n) => `${c.cyan("/" + n)}  ${c.grey(skills[n].description || "")}  ${srcTag(skills[n])}`)
+        ? names.map((n) => {
+            const h = skills[n].hint ? " " + c.dim(skills[n].hint) : "";
+            return `${c.cyan("/" + n)}${h}  ${c.grey(skills[n].description || "")}  ${srcTag(skills[n])}`;
+          })
         : [c.dim("등록된 스킬이 없습니다.")];
+      lines.unshift(c.dim("사용법: /명령 뒤에  <필수> 또는 [선택] 표기대로 입력하세요."));
       lines.push(c.dim("추가: <작업폴더>/.cdsa/skills/*.md · ~/.cdsa_harness/skills/ · config.json 의 skill_dirs"));
       lines.push(c.dim("외부(.claude/commands 등)는 import_foreign_skills 로 끌 수 있음"));
       console.log(panel(lines, { title: "🎯 스킬 (프롬프트 템플릿, /이름 으로 실행)", color: "cyan" }));
@@ -808,7 +812,14 @@ export async function main(argv = []) {
     if (user.startsWith("/")) {
       const name = low.slice(1).split(/\s+/)[0];
       if (skills[name]) {
-        const argStr = user.split(/\s+/).slice(1).join(" ");
+        const argStr = user.split(/\s+/).slice(1).join(" ").trim();
+        const hint = skills[name].hint || "";
+        // 입력이 필요한 스킬(<...>)인데 비어 있으면, 실행 대신 사용법을 알려준다.
+        if (!argStr && hint.includes("<")) {
+          console.log(c.yellow(`사용법: ${c.bold("/" + name)} ${hint}`) + c.dim("  ← 명령 뒤에 내용을 입력하세요"));
+          if (skills[name].description) console.log(c.dim("  " + skills[name].description));
+          continue;
+        }
         console.log(c.dim(`(스킬 '/${name}' 실행)`));
         rule();
         try {

package/src/skills.js

@@ -44,7 +44,7 @@ function parseFrontmatter(text) {
   const meta = {};
   for (const line of m[1].split("\n")) {
     const i = line.indexOf(":");
-    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
   }
   return { meta, body: text.slice(m[0].length).trim() };
 }
@@ -54,7 +54,13 @@ function addSkill(skills, name, file) {
   try {
     const raw = fs.readFileSync(file, "utf8");
     const { meta, body } = parseFrontmatter(raw);
-    skills[name] = { name, description: meta.description || "", body, source: file };
+    skills[name] = {
+      name,
+      description: meta.description || "",
+      hint: meta["argument-hint"] || meta.args || meta.usage || "",
+      body,
+      source: file,
+    };
   } catch {
     /* ignore unreadable skill */
   }
@@ -89,7 +95,7 @@ export function loadSkills(workspace, { importForeign = true, extraDirs = [] } =
   }
   // 패키지 내장 기본 스킬(임베드) — 가장 낮은 우선순위(사용자 파일이 덮어씀)
   for (const s of BUILTIN_SKILLS) {
-    if (!skills[s.name]) skills[s.name] = { name: s.name, description: s.description || "", body: s.body, source: "(내장)" };
+    if (!skills[s.name]) skills[s.name] = { name: s.name, description: s.description || "", hint: s.hint || "", body: s.body, source: "(내장)" };
   }
   return skills;
 }