Communitygithub.com

CodeSoul-co/theta-skill

사용자를 THETA 토픽 모델링 워크플로우의 의도 파악부터 결과 해석까지 안내하는 휴대용 에이전트 스킬입니다.

theta-skill란 무엇인가요?

이 스킬은 AI 에이전트(예: Claude Code, Cursor, Codex)를 위해 설계된 휴대용 THETA 토픽 모델링 워크플로우 안내자 역할을 합니다. 사용자의 의도를 파악하고, 저장소 확인, 환경 설정, 데이터 검사, 모델 추천, 명령어 생성 및 실행에 이르는 일련의 단계를 안내합니다. 핵심 특징은 **읽기 전용 검사**와 **변경이 필요한 작업**을 엄격히 구분하는 안전 프로토콜입니다. 저장소 구조 확인, 데이터셋 스키마 검사, 모델 추천 등은 별도 확인 없이 수행 가능하지만, 저장소 클론, 환경 생성, 데이터 수정, 모델 학습, 파일 쓰기 등은 표준화된 포맷으로 사용자 확인을 받아야만 실행합니다. 이를 통해 실수로 인한 비용 발생이나 데이터 손상을 방지합니다. 또한, `zero_shot` 워크플로우에서만 클라우드 임베딩을 사용하고, 미세 조정이 필요한 모드에서는 로컬 임베딩과 Qwen 호환 모델을 요구하여 데이터 프라이버시와 비용을 관리합니다. 이 스킬은 `SKILL.md`, `references/` 디렉토리의 문서, `scripts/inspect_theta_env.py` 스크립트를 활용하며, `$theta-workflow` 같은 명명된 호출 구문을 지원합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add CodeSoul-co/theta-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

THETA 워크플로우

이 휴대용 에이전트 워크플로우 스킬을 사용하여 의도 확인부터 결과 해석까지 THETA 토픽 모델링 작업을 안내합니다. 사용자의 언어에 맞춰 중국어 요청에는 중국어로, 영어 요청에는 영어로 응답합니다. Codex 특정 API를 가정하지 마세요. 핵심 워크플로우는 파일 읽기, 확인 요청, 확인 시 일반 셸 명령어 실행, 번들된 읽기 전용 Python 사전 점검 도우미 사용에 의존합니다.

핵심 안전 프로토콜

파일, 환경, 비용, 컴퓨팅 또는 git 상태를 수정하는 작업과 읽기 전용 검사를 구분합니다.

읽기 전용 검사 및 조언은 추가 확인이 필요하지 않습니다:

  • README, 문서, 스크립트, 구성 템플릿, 결과 파일을 읽습니다.
  • 저장소 구조, 파일 존재 여부, Python 버전, conda 존재 여부, .env 존재 여부, 모델 경로 존재 여부, git 상태, 사용 가능한 명령어를 확인합니다.
  • 데이터셋 스키마, 행 수, 열 이름, 누락된 텍스트, 중복 텍스트, 텍스트 길이, 시간 열, 공변량 열을 검사합니다.
  • 모델, 매개변수, 실험 설계, 명령줄을 추천합니다.
  • 기존 메트릭, 토픽 단어, 토픽 테이블, 시각화, 튜닝 제안을 요약합니다.

실행 전 명시적인 사용자 확인이 필요한 작업:

  • THETA 저장소를 클론하거나 풀, 브랜치 전환, 커밋, 병합, 푸시합니다.
  • conda 환경을 생성하거나, 종속성을 설치하거나 scripts/env_setup.sh를 실행합니다.
  • .env를 생성하거나 편집합니다. 채팅에 API 키를 출력, 저장 또는 에코하지 마세요.
  • 클라우드 임베딩 제공자를 구성하거나 사용합니다. 클라우드 API 호출은 비용이 발생할 수 있으며 텍스트가 외부 서비스에 노출될 수 있습니다.
  • Qwen, SBERT 또는 기타 로컬 모델을 다운로드합니다.
  • 데이터셋을 수정, 정리, 변환 또는 쓰고, 기본적으로 새 파생 파일을 생성하는 것을 선호하며 원본 데이터를 절대 수정하지 않습니다.
  • THETA 또는 베이스라인 학습, 다중 모델 비교, 튜닝 스윕, 대규모 로컬 모델, GPU 집약적 작업 또는 결과를 쓰는 명령어를 실행합니다.
  • 보고서 파일을 생성하거나, 출력을 덮어쓰거나, 캐시를 삭제하거나, 모델을 삭제하거나, 데이터를 삭제하거나, 결과 디렉토리를 정리합니다.

확인이 필요한 경우 다음 형식을 사용합니다:

我准备执行以下操作:

操作:
<간단한 작업>

命令:
<명령어 (있는 경우)>

影响的文件或目录:
<경로>

可能的资源消耗:
<로컬 컴퓨팅 / GPU / 스토리지 / API 비용 / 없음>

是否会覆盖已有文件:
<예 / 아니오>

请确认是否继续。

영어 사용자의 경우 일치하는 영어 형식을 사용합니다:

I am preparing to perform the following action:

Action:
<간단한 작업>

Command:
<명령어 (있는 경우)>

Affected files or directories:
<경로>

Potential resource usage:
<로컬 컴퓨팅 / GPU / 스토리지 / API 비용 / 없음>

Will this overwrite existing files:
<예 / 아니오>

Please confirm whether to continue.

确认, 可以, 继续, 执行, yes, proceed, run it과 같은 명시적인 확인 후에만 진행합니다. 답변이 모호한 경우 사용자의 언어로 한 번 더 질문합니다.

전체 확인 흐름, 예제 및 확인 테이블은 중국어의 경우 references/confirmation-flow.zh.md를, 영어의 경우 references/confirmation-flow.en.md를 읽으세요. 인입 질문은 references/user-questions.md를 읽으세요.

임베딩 규칙

zero_shot 워크플로우에 대해서만 클라우드 임베딩을 사용하며, API 비용, 제공자, 키 존재 여부, 데이터 유출 위험을 확인한 후에만 사용합니다.

supervised, unsupervised 또는 미세 조정이 필요한 모든 워크플로우의 경우 로컬 임베딩과 로컬 Qwen 호환 모델 경로가 필요합니다. 사용자가 미세 조정 가능한 모드에 대해 클라우드 임베딩을 요청하면, THETA가 해당 경로에 대해 로컬 모델이 필요하다고 설명하고 대신 로컬 구성을 제안합니다.

권장 워크플로우

  1. 요청이 THETA 토픽 모델링에 속하는지 식별합니다. 이 라우팅 결정에는 확인이 필요하지 않습니다.
  2. 환경 설정, 데이터 변환 또는 학습 계획 전에 사용 가능한 THETA 저장소가 있는지 즉시 확인합니다. README.md, .env.example, scripts/, src/models/run_pipeline.py가 있는지 확인합니다. 이 읽기 전용 확인은 확인이 필요하지 않습니다.
  3. THETA 저장소가 없으면 첫 번째 작업은 https://github.com/CodeSoul-co/THETA.git 클론 확인을 요청하는 것입니다. 저장소가 존재할 때까지 환경을 구성하거나, 종속성을 설치하거나, .env를 생성하거나, 데이터셋을 검사하거나, 학습 명령어를 생성하지 마세요.
  4. 저장소가 존재한 후에만 사용자의 언어로 필요한 작업 질문(데이터셋 경로, 텍스트 열, 언어, 시간 열, 공변량, 대상 결과, 리소스 제약 조건)을 합니다.
  5. 환경, .env 상태, 데이터셋을 읽기 전용으로 검사합니다. 결정론적 사전 점검이 유용한 경우 scripts/inspect_theta_env.py를 사용합니다.
  6. 데이터와 목표에 따라 모델군과 매개변수를 추천합니다.
  7. 실행하지 않고 검토할 명령어를 생성합니다.
  8. 변이, 고비용, 장기 실행, GPU 집약적 또는 파일 쓰기 명령어를 실행하기 전에 표준 형식을 사용하여 명시적인 확인을 받습니다.
  9. 실행 후 출력을 읽고 토픽 품질, 중복, 일관성, 다양성, 배타성 및 다음 튜닝 단계를 설명합니다.
  10. 추가 튜닝 실험을 실행하거나, 보고서 파일을 작성하거나, 출력을 덮어쓰거나, 무엇이든 삭제하기 전에 다시 확인합니다.

호출 동작

에이전트가 SKILL.md를 읽거나, skills/theta-workflow/ 디렉토리를 로드하거나, $theta-workflow와 같은 명명된 호출을 통해 이 스킬을 사용할 때, 현재 작업 공간을 첫 번째 후보 THETA 저장소로 취급합니다. 현재 작업 공간이 THETA가 아닌 경우 사용자가 제공한 경로를 검사합니다. 사용 가능한 저장소가 없으면 클론 확인 단계에서 중단합니다. 저장소 게이트가 충족될 때까지 데이터셋 질문을 하거나 환경 설정을 제안하지 마세요.

좋은 첫 사용자 프롬프트:

Use the THETA Workflow skill in skills/theta-workflow to help me run THETA topic modeling on a policy-text dataset.
使用 skills/theta-workflow 里的 THETA Workflow skill 帮我跑一个政策文本主题建模流程。

런타임이 명명된 스킬 구문을 지원하는 경우 $theta-workflow도 허용됩니다.

참조 라우팅

  • 전체 엔드투엔드 결정 흐름은 references/workflow.md를 읽으세요.
  • THETA 명령어를 생성하기 전에 references/commands.md를 읽으세요. 현재 저장소 진입점과 확인 요구 사항이 나열되어 있습니다.
  • 출력 파일을 해석하거나 튜닝을 추천할 때 references/result-analysis.md를 읽으세요.
  • 데이터셋, 언어, 목표, 리소스 또는 출력 기본 설정에 대해 사용자에게 질문할 때 references/user-questions.md를 읽으세요.
  • 자세한 중국어 확인 문구나 예제가 필요할 때 references/confirmation-flow.zh.md를 읽으세요.
  • 자세한 영어 확인 문구나 예제가 필요할 때 references/confirmation-flow.en.md를 읽으세요.

사전 점검 스크립트

읽기 전용 검사에만 이 스크립트를 실행합니다:

python skills/theta-workflow/scripts/inspect_theta_env.py \
  --dataset path/to/data.csv \
  --text-column content \
  --mode zero_shot

구조화된 출력이 필요한 경우 --json을 추가합니다. 이 스크립트는 파일을 쓰거나, 종속성을 설치하거나, API를 호출하거나, 학습을 시작해서는 안 됩니다.

관련 스킬