SKILL.md
k-skill
Skill by ara.so — Daily 2026 Skills collection.
한국인을 위한 AI 에이전트 스킬 모음집. Claude Code, Codex, Cursor 등 코딩 에이전트에서 SRT 예매, KBO 조회, 로또 확인, 카카오톡 전송, 서울 지하철 도착정보, HWP 변환, 우편번호 검색 등을 자동화할 수 있습니다.
설치
전체 스킬 설치 (권장)
# npx로 전체 스킬 설치
npx k-skill install또는 전역 설치
npm install -g k-skill
k-skill install
### 선택 설치
SRT만 설치
npx k-skill install srt
KBO + 로또만 설치
npx k-skill install kbo lotto
### 설치 후 초기 설정
k-skill-setup 스킬 실행 (sops+age 설정, secrets 파일 생성, 런타임 확인)
k-skill-setup
초기 설정 순서:
- `k-skill install` 실행
- `k-skill-setup` 실행 → `sops + age` 키 생성, 공통 secrets 파일 초기화
- secrets 값 로컬에 안전하게 등록 (채팅창에 붙여넣기 금지)
- 각 기능별 문서 확인
## 보안 및 시크릿 관리
**절대 금지:**
- 채팅 메시지에 비밀번호/API 키 직접 입력
- `.env` 파일을 git에 커밋
- 코드 내 하드코딩
**표준 환경변수 이름:**
SRT
export SRT_USERNAME="your_id"
export SRT_PASSWORD="your_password"
KTX/Korail
export KORAIL_USERNAME="your_id"
export KORAIL_PASSWORD="your_password"
서울 지하철 (공공데이터포털 API 키)
export SEOUL_METRO_API_KEY="your_api_key"
**sops + age로 암호화 저장 (권장):**
age 키 생성
age-keygen -o ~/.config/sops/age/keys.txt
secrets 파일 암호화
sops --age $(cat ~/.config/sops/age/keys.txt | grep "public key" | awk '{print $4}') \
--encrypt secrets.yaml > secrets.enc.yaml
복호화하여 환경변수 주입
sops --decrypt secrets.enc.yaml | k-skill env inject
## 기능별 사용법
### 1. SRT 예매
열차 조회, 예약, 예약 확인, 취소를 지원합니다.
const { SRTClient } = require('k-skill/srt');
const client = new SRTClient({
username: process.env.SRT_USERNAME,
password: process.env.SRT_PASSWORD,
});
// 로그인
await client.login();
// 열차 조회
const trains = await client.searchTrains({
departure: '수서',
arrival: '부산',
date: '20260401', // YYYYMMDD
time: '080000', // HHmmss
passengers: 1,
});
console.log(trains);
// [{ trainNo: 'SRT123', departTime: '08:00', arrivalTime: '10:30', price: 59800, seats: 'available' }, ...]
// 예약
const reservation = await client.reserve({
trainNo: trains[0].trainNo,
passengers: 1,
seatType: 'normal', // 'normal' | 'window' | 'aisle'
});
console.log(reservation.reservationId);
// 예약 확인
const myReservations = await client.getReservations();
console.log(myReservations);
// 예약 취소
await client.cancelReservation(reservation.reservationId);
**에이전트 프롬프트 예시:**
"4월 1일 수서→부산 SRT 08시 이후 첫 열차 창가석으로 예약해줘"
### 2. KTX 예매
⚠️ 현재 작동하지 않습니다. 향후 지원 예정.
const { KTXClient } = require('k-skill/ktx');
// KTX/Korail 열차 조회, 예약, 예약 확인, 취소 지원 목표
// 현재 개발 중 — 사용 불가
### 3. 카카오톡 Mac CLI
macOS에서 `kakaocli`를 사용한 대화 조회, 검색, 메시지 전송. 인증 불필요.
const { KakaoTalkMac } = require('k-skill/kakaotalk-mac');
const kakao = new KakaoTalkMac();
// 대화 목록 조회
const conversations = await kakao.listConversations();
console.log(conversations);
// [{ name: '홍길동', lastMessage: '안녕', unread: 2 }, ...]
// 특정 대화 검색
const results = await kakao.searchConversations('개발팀');
// 테스트 전송 (실제 전송 전 확인)
const preview = await kakao.previewSend({
to: '홍길동',
message: '안녕하세요!',
});
console.log(preview); // { to: '홍길동', message: '안녕하세요!', confirmed: false }
// 실제 전송 (사용자 확인 후)
await kakao.send({
to: '홍길동',
message: '안녕하세요!',
confirmed: true, // 반드시 사용자 동의 후 true
});
**중요:** 에이전트는 사용자가 명시적으로 확인한 경우에만 `confirmed: true`로 실제 전송합니다.
**CLI 직접 사용:**
대화 목록
kakaocli list
메시지 전송
kakaocli send --to "홍길동" --message "테스트 메시지"
대화 내용 조회
kakaocli read --name "홍길동" --count 20
### 4. 서울 지하철 도착정보 조회
공공데이터포털 API 키 필요.
const { SeoulSubway } = require('k-skill/seoul-subway');
const subway = new SeoulSubway({
apiKey: process.env.SEOUL_METRO_API_KEY,
});
// 역 이름으로 실시간 도착정보 조회
const arrivals = await subway.getArrivals('강남');
console.log(arrivals);
/*
[
{
line: '2호선',
station: '강남',
direction: '성수방면',
nextTrain: '1분 후',
followingTrain: '5분 후',
trainNo: '2234'
},
...
]
*/
// 특정 노선 필터링
const line2 = await subway.getArrivals('강남', { line: '2호선' });
// 역 코드로 조회
const byCode = await subway.getArrivalsByCode('0222');
**에이전트 프롬프트 예시:**
"지금 강남역 2호선 외선순환 다음 열차 언제 와?"
### 5. KBO 경기 결과 조회
인증 불필요.
const { KBOClient } = require('k-skill/kbo');
const kbo = new KBOClient();
// 오늘 경기 일정/결과
const today = await kbo.getGames();
console.log(today);
// 특정 날짜
const games = await kbo.getGames({ date: '20260401' }); // YYYYMMDD
// 팀별 필터링
const lgGames = await kbo.getGames({
date: '20260401',
team: 'LG',
});
console.log(lgGames);
/*
[
{
homeTeam: 'LG',
awayTeam: 'KIA',
homeScore: 5,
awayScore: 3,
status: 'final', // 'scheduled' | 'live' | 'final'
stadium: '잠실',
startTime: '18:30'
}
]
*/
// 팀 목록
const teams = kbo.getTeamList();
// ['LG', 'KIA', 'SSG', 'NC', 'KT', '두산', '한화', '롯데', '삼성', '키움']
### 6. 로또 당첨 확인
인증 불필요.
const { LottoClient } = require('k-skill/lotto');
const lotto = new LottoClient();
// 최신 회차 당첨번호
const latest = await lotto.getLatestResult();
console.log(latest);
/*
{
round: 1162,
date: '2026-03-28',
numbers: [3, 14, 22, 31, 40, 43],
bonusNumber: 7,
prizes: {
first: { winners: 12, amount: 2500000000 },
...
}
}
*/
// 특정 회차
const specific = await lotto.getResult(1100);
// 내 번호 대조
const myNumbers = [3, 14, 22, 31, 40, 43];
const check = await lotto.checkNumbers(myNumbers);
console.log(check);
/*
{
round: 1162,
myNumbers: [3, 14, 22, 31, 40, 43],
matched: [3, 14, 22, 31, 40, 43],
bonusMatched: false,
rank: 1, // 1~5등 또는 null
prize: 2500000000
}
*/
### 7. HWP 문서 처리
`.hwp` 파일을 JSON/Markdown/HTML로 변환, 이미지 추출, 배치 처리 지원. 인증 불필요.
const { HWPProcessor } = require('k-skill/hwp');
const hwp = new HWPProcessor();
// HWP → Markdown 변환
const markdown = await hwp.toMarkdown('./document.hwp');
console.log(markdown);
// HWP → JSON 변환
const json = await hwp.toJSON('./document.hwp');
console.log(json.paragraphs);
// HWP → HTML 변환
const html = await hwp.toHTML('./document.hwp');
// 이미지 추출
const images = await hwp.extractImages('./document.hwp', {
outputDir: './extracted-images',
});
console.log(images); // ['./extracted-images/image_001.png', ...]
// 배치 처리 (디렉토리 내 전체 HWP 파일)
const results = await hwp.batchConvert('./hwp-files/', {
format: 'markdown',
outputDir: './converted/',
});
// Windows 직접 제어 (한글과컴퓨터 앱 설치된 경우)
const winHwp = new HWPProcessor({ useWindowsApp: true });
const nativeResult = await winHwp.toMarkdown('./document.hwp');
**CLI 사용:**
단일 파일 변환
k-skill hwp convert document.hwp --format markdown
배치 변환
k-skill hwp batch ./hwp-folder/ --format json --output ./output/
이미지 추출
k-skill hwp extract-images document.hwp --output ./images/
### 8. 우편번호 검색
공식 우체국 우편번호 API 사용. 인증 불필요.
const { ZipcodeClient } = require('k-skill/zipcode');
const zipcode = new ZipcodeClient();
// 주소 키워드로 검색
const results = await zipcode.search('강남구 테헤란로');
console.log(results);
/*
[
{
zipcode: '06236',
roadAddress: '서울특별시 강남구 테헤란로 152',
jibunAddress: '서울특별시 강남구 역삼동 736',
building: '강남파이낸스센터'
},
...
]
*/
// 정확한 건물명으로 검색
const exact = await zipcode.search('롯데월드타워');
// 우편번호로 역조회
const byZip = await zipcode.getByZipcode('05510');
## 공통 패턴
### 에러 핸들링
const { SRTClient, SRTError, SRTAuthError } = require('k-skill/srt');
try {
const client = new SRTClient({
username: process.env.SRT_USERNAME,
password: process.env.SRT_PASSWORD,
});
await client.login();
const trains = await client.searchTrains({ ... });
} catch (err) {
if (err instanceof SRTAuthError) {
console.error('로그인 실패. 아이디/비밀번호를 확인하세요.');
} else if (err instanceof SRTError) {
console.error('SRT 오류:', err.message, err.code);
} else {
throw err;
}
}
### 환경변수 로드 패턴
// .env 파일 사용 시
require('dotenv').config();
// sops 복호화 후 환경변수 주입 시
// sops --decrypt secrets.enc.yaml | k-skill env inject 실행 후 자동 주입됨
const { SRTClient } = require('k-skill/srt');
const client = new SRTClient({
username: process.env.SRT_USERNAME, // 환경변수 참조
password: process.env.SRT_PASSWORD,
});
## CLI 전체 명령어 요약
설치 및 설정
k-skill install # 전체 스킬 설치
k-skill install srt kbo lotto # 선택 설치
k-skill-setup # sops+age 설정, secrets 초기화
k-skill env inject # 환경변수 주입
SRT
k-skill srt search --from 수서 --to 부산 --date 20260401 --time 080000
k-skill srt reserve --train SRT123 --passengers 1
k-skill srt list # 예약 목록
k-skill srt cancel --id RES456 # 예약 취소
KBO
k-skill kbo today # 오늘 경기
k-skill kbo games --date 20260401
k-skill kbo games --team LG
로또
k-skill lotto latest # 최신 회차
k-skill lotto result --round 1100
k-skill lotto check --numbers 3,14,22,31,40,43
지하철
k-skill subway arrivals --station 강남
k-skill subway arrivals --station 강남 --line 2호선
HWP
k-skill hwp convert doc.hwp --format markdown
k-skill hwp batch ./folder/ --format json
k-skill hwp extract-images doc.hwp
우편번호
k-skill zipcode search "강남구 테헤란로"
k-skill zipcode lookup 06236
카카오톡 (macOS)
k-skill kakao list
k-skill kakao send --to "홍길동" --message "메시지"
## 트러블슈팅
### SRT_USERNAME 환경변수가 없다는 오류
환경변수 확인
echo $SRT_USERNAME
.env 파일에 등록
echo 'SRT_USERNAME=your_id' >> .env
echo 'SRT_PASSWORD=your_password' >> .env
sops로 암호화 관리 권장
k-skill-setup # 다시 실행하여 secrets 등록
### HWP 변환 실패
의존 패키지 확인
npm install -g hwp.js
Python 백엔드 사용 시
pip install python-hwp
Windows에서 한컴 앱 직접 제어 시
k-skill hwp convert doc.hwp --use-native
### 카카오톡 CLI (macOS) 실행 안 됨
kakaocli 설치 확인
which kakaocli
없으면 설치
brew install kakaocli
또는
npm install -g kakaocli
### 서울 지하철 API 키 오류
공공데이터포털에서 API 키 발급
https://data.seoul.go.kr → 서울시 지하철 실시간 도착정보
export SEOUL_METRO_API_KEY="발급받은_키"
### Node.js 버전 오류
node --version # v18 이상 권장
nvm으로 버전 변경
nvm install 20
nvm use 20