🦞 14. SkillOps 운영전환 가이드

이 문서는 기존 스킬 운영이 실제로 어디서 막혔는지를 먼저 보여주고, 그 문제를 해결하기 위해 어떤 구조로 바꿨는지, 지금은 어떤 형태로 운영하는지를 서사형으로 정리한 실무 가이드다.

먼저: 스킬이 뭔지 30초 설명

스킬은 어렵게 보면 복잡하지만, 쉽게 말하면 AI에게 주는 작은 업무 매뉴얼이다.

• 사람에게 “이 일은 이렇게 처리해”라고 체크리스트를 주는 것처럼,
• AI에게도 “이 요청이 오면 어떤 순서로, 어떤 기준으로 처리해”를 문서로 정해두는 방식이다.

예시로 보면 더 쉽다.

• manage-skills-tw = 팀장 역할
  • 어떤 스킬을 새로 만들지, 기존 걸 고칠지 판단
• verify-implementation-tw = 검수 역할
  • 규칙 위반이 없는지 최종 점검

한 줄 요약: 예전에는 사람 기억으로 관리했고, 지금은 ‘매뉴얼 + 자동 검수’로 관리한다.

0) 전체 서사 한 장 요약

mindmap
  root((SkillOps 전환 스토리))
    과거 구성
      스킬별 수동 수정
      검증은 비정기
      담당자 기억 의존
    이슈 발견
      중복 이름
      frontmatter 불일치
      트리거 문구 약함
      검증 기준 부재
    개선
      단일 진입점
      통합 검증 게이트
      severity 리포트
      references/scripts 분리
    현재 구성
      manage-skills-tw
      verify-implementation-tw
      주기 점검 루프

1) 과거 구성: 왜 처음엔 괜찮았나

초기에는 아래 방식이 빠르고 직관적이었다.

• 각 스킬을 필요할 때 직접 수정
• 검증은 오류가 보일 때 수동 점검
• 규칙은 문서와 사람 기억으로 유지

즉, 작을 때는 빠른 구조였다. 하지만 스킬 수가 늘어나면서 문제가 보이기 시작했다.

2) 이슈 발견: 어디서 한계가 터졌나

2-1. 대표 증상

• 같은 스킬 이름이 서로 다른 경로에 중복 존재
• SKILL frontmatter 형식이 스킬마다 다름
• description 트리거 문구 품질 편차
• 릴리즈 전에 무엇을 반드시 확인해야 하는지 기준 불명확

2-2. 실제 점검에서 확인된 이슈

2026-02-18 기준 점검에서 다음 항목이 반복 발견됐다.

• pptx-creator 중복 이름(2개 경로)
• frontmatter extra key(homepage, metadata)

핵심은 “개별 수정” 자체가 문제가 아니라, 개별 수정을 통제하는 공통 게이트가 없었다는 점이다.

3) 개선 설계: 어떤 원칙으로 바꿨나

우리는 아래 4가지 원칙으로 구조를 다시 짰다.

1. 단일 진입점
   • 유지보수 시작은 manage-skills-tw에서만 수행
2. 통합 검증 게이트
   • 릴리즈 전 verify-implementation-tw를 필수 실행
3. 명시적 판정 체계
   • critical / major / recommended로 등급화
4. Progressive Disclosure 반영
   • SKILL 본문은 얇게, 상세 규칙은 references/, 반복검증은 scripts/

4) 현재 구성: 지금은 어떻게 운영하나

4-1. 배치 경로

• 팀 운영 기본: ~/.openclaw/workspace/skills/
• 공용 공유가 필요할 때만: ~/.openclaw/skills/

4-2. 핵심 스킬 2종

• manage-skills-tw
  • 변경 감지
  • CREATE/UPDATE/EXEMPT 판단
  • 유지보수 리포트
• verify-implementation-tw
  • 통합 검증 실행
  • 품질 게이트 판정

4-3. 폴더 구조

skills/
├─ manage-skills-tw/
│  ├─ SKILL.md
│  ├─ references/
│  │  ├─ decision-rules.md
│  │  └─ report-template.md
│  └─ scripts/
│     └─ audit_skills.py
└─ verify-implementation-tw/
   ├─ SKILL.md
   ├─ references/
   │  ├─ check-rubric.md
   │  ├─ report-format.md
   │  └─ coverage-registry.md
   └─ scripts/
      └─ verify_skills.py

5) 운영 흐름: 과거와 달라진 실제 실행 루프

flowchart TD
A[요청 또는 변경 발생] --> B[manage-skills-tw 실행]
B --> C[변경 스코프 수집]
C --> D[CREATE / UPDATE / EXEMPT 결정]
D --> E[스킬 수정 또는 생성]
E --> F[verify-implementation-tw 실행]
F --> G{게이트 통과?}
G -->|No| H[Critical/Major 우선 수정]
H --> F
G -->|Yes| I[머지/배포]

6) 기존 vs 현재 비교 (교육용 핵심 표)

항목	기존(수동 중심)	현재(SkillOps)
시작 방식	스킬별 개별 접근	manage-skills-tw 단일 진입
검증 시점	필요 시 수동	릴리즈 전 통합 검증 필수
품질 기준	암묵적	severity 명시적 기준
운영 리스크	누락/드리프트 누적	조기 탐지/수정 루프
팀 협업	담당자 의존	공통 리포트 언어

7) 실무 적용 체크리스트

칠판 치트시트

[작성 규칙]
- frontmatter: name, description만 유지
- description: Use when 트리거 문장 명확화
 
[구조 규칙]
- SKILL 본문은 짧게
- 상세는 references/
- 반복 검증은 scripts/
 
[게이트 규칙]
- Critical > 0 이면 배포 금지
- Major는 당일 수정 또는 owner/date 명시
- 리포트 없는 머지 금지

8) 현재 상태와 다음 액션

현재 상태

• SkillOps 2종 생성 완료
• 통합 검증 스크립트 실행 확인 완료
• 핵심 잔여 이슈는 기존 자산(pptx-creator) 정리 작업으로 수렴

다음 액션

1. 중복 스킬 경로 통합(사용자 확인 후 실행)
2. frontmatter 완전 표준화(name, description)
3. 주 1회 통합 검증 루틴 고정(cron 또는 고정 수동 루프)

AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성하고, 실제 운영 맥락에 맞춰 사람이 검토·수정한 결과물이다.

📚 다음 읽기

• 🦞 36. 스킬 실전 — 스킬 직접 만들고 운영하기
• 🦞 27. 블로그작성 Excalidraw 루프 — 스킬 조합으로 콘텐츠 생산
• 🦞 24. 11가지 핵 실전운영가이드 — 운영 전체 빠른 참조