Skilldo CLI은(는) 무엇을 하나요?
Skilldo는 소프트웨어 라이브러리를 위한 SKILL.md 파일을 생성하는 7단계 LLM 파이프라인입니다: 추출(extract) → 매핑(map) → 학습(learn) → 팩트(facts) → 생성(create) → 검토(review) → 테스트(test)
1-3단계는 라이브러리 메타데이터(소스 파일, 문서, 의존성, 버전)를 수집합니다. 4단계(facts)는 1-3단계에서 부정 어설션(negative assertions)이 포함된 간결한 진리표를 추출합니다. 5단계는 SKILL.md를 생성합니다. 6단계는 정확성/안전성을 검토합니다. 7단계는 생성된 테스트 코드로 검증합니다.
설치
# Homebrew
brew install skilldoai/tap/skilldo
# 소스에서 설치
cargo install --path .
빠른 시작
# 현재 레포지토리의 SKILL.md 생성
skilldo generate
# 특정 레포지토리 경로에 대해 생성
skilldo generate /path/to/library
# 언어 명시적으로 지정
skilldo generate --language python
# 특정 설정 사용
skilldo generate --config skilldo.toml
설정 (skilldo.toml)
Skilldo는 TOML 설정 파일을 사용합니다. skilldo.toml을 레포지토리 루트에 배치하거나 --config로 전달하세요.
최소 설정 (단일 제공자)
[llm]
provider_type = "anthropic" # anthropic, openai, gemini, openai-compatible, chatgpt
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY" # 키를 포함하는 환경 변수 이름
[generation]
max_retries = 10 # 린트/테스트 실패 시 재시도 횟수
# telemetry = true # 옵트인: ~/.skilldo/runs.csv에 실행 기록
단계별 모델 재정의
검토 및 테스트 단계에 다른 모델을 사용할 수 있습니다:
[llm]
provider_type = "anthropic"
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"
[generation]
enable_test = true
enable_review = true
test_mode = "thorough" # thorough, quick, adaptive, minimal
[generation.review_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"
[generation.test_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"
로컬 모델 (Ollama)
[llm]
provider_type = "openai-compatible"
model = "qwen3-coder:latest"
base_url = "http://localhost:11434/v1"
api_key_env = "none" # Ollama는 키가 필요 없음
CLI 제공자 (기존 CLI 도구를 LLM 백엔드로 사용)
[llm]
provider_type = "cli"
model = "claude-sonnet-4-6"
cli_command = "claude"
cli_args = ["-p", "--no-session-persistence", "--output-format", "text", "--dangerously-skip-permissions"]
request_timeout_secs = 900
지원되는 CLI 도구: claude, codex, gemini. 프롬프트는 stdin을 통해 파이프되며, 응답은 stdout에서 캡처됩니다.
선택 사항: CLI가 시스템 프롬프트를 기본적으로 수용하는 방식 선언:
cli_system_args = ["--system-prompt-file"] # claude의 경우 (임시 파일에서 읽음)
# cli_system_args = ["-s"] # codex의 경우
cli_system_args가 설정되면 명령어가 stdin에 연결되지 않고 네이티브 시스템 채널을 통해 전달됩니다.
사용자 정의 기본 URL (Bedrock, Vertex AI, 프록시)
모든 제공자는 사용자 정의 엔드포인트를 위한 선택적 base_url을 지원합니다:
# AWS Bedrock을 통한 Anthropic
[llm]
provider_type = "anthropic"
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"
# Google Vertex AI를 통한 Gemini
[llm]
provider_type = "gemini"
base_url = "https://us-central1-aiplatform.googleapis.com"
컨테이너 설정 (선택 사항)
[generation.container]
runtime = "podman" # docker 또는 podman
timeout = 120 # 초
cleanup = true
# setup_commands = ["apt-get update && apt-get install -y cmake"] # 의존성/테스트 전에 실행
명령어
skilldo generate [PATH]
라이브러리 레포지토리에 대한 SKILL.md를 생성합니다.
주요 플래그:
--language <LANG>— 언어 강제 지정 (python, javascript, rust, go, java). 생략 시 자동 감지--config <PATH>— 설정 파일 경로 (기본값:./skilldo.toml또는~/.config/skilldo/config.toml)--model <MODEL>— LLM 모델 재정의--provider <PROVIDER>— LLM 제공자: anthropic, openai, chatgpt, gemini, openai-compatible--base-url <URL>— openai-compatible 제공자를 위한 기본 URL-i, --input <PATH>— 업데이트 참조용 기존 SKILL.md 경로-o <PATH>— 출력 파일 (기본값: SKILL.md)--debug-stage-files <DIR>— 디버깅을 위해 각 파이프라인 단계의 원시 출력을 덤프--replay-from <DIR>— 이전--debug-stage-files실행에서 캐시된 extract/map/learn 출력을 로드하여 LLM 호출을 건너뜀. 반복 시간을 약 15분에서 약 5분으로 단축--no-test— 테스트 검증 건너뛰기--no-review— 검토 검증 건너뛰기--no-security-scan— YARA/유니코드/인젝션 스캐닝 건너뛰기--no-parallel— extract/map/learn을 순차적으로 실행 (로컬 모델용)--best-effort— 오류가 있어도 종료 코드 0--telemetry/--no-telemetry— 실행 로깅 전환--container— 컨테이너에서 테스트 에이전트 실행 (기본값: uv/cargo를 사용한 베어메탈)--install-source <MODE>— 테스트 에이전트가 라이브러리를 설치하는 방식:registry(crates.io/PyPI/npm에서, 기본값),local-install(로컬 레포지토리를 마운트하고 패키지 관리자로 빌드),local-mount(레포지토리를 마운트하고 모듈 경로를 직접 설정, 빌드 단계 없음)--source-path <PATH>— local-install/local-mount 모드를 위한 로컬 소스 경로--test-mode <MODE>—thorough는 모든 패턴을 테스트 (기본값),quick는 최대 3개 테스트 (빠른 반복),minimal은 1개 테스트,adaptive는 1개로 시작하여 확장--review-model <MODEL>/--review-provider <PROVIDER>— 검토 단계만 모델/제공자 재정의--test-model <MODEL>/--test-provider <PROVIDER>— 테스트 코드 생성 단계만 모델/제공자 재정의--max-retries <N>— 생성→검증 최대 재시도 횟수 (기본값: 설정 파일 참조)--skill-version <VER>— 자동 감지 대신 프론트매터에 특정 라이브러리 버전 강제 지정 (예: "2.1.0")--version-from <STRATEGY>— 버전 감지 방식:package(Cargo.toml/pyproject.toml),git-tag,branch,commit-q, --quiet— 정보 출력 억제 (경고/오류만 출력)-v, --verbose— 상세 디버그 출력 표시 (RUST_LOG=debug와 동일)--request-timeout <SECS>— LLM 요청 시간 제한 재정의 (초 단위, 기본값: 120)--dry-run— 테스트용 모의 LLM 클라이언트 사용 (API 호출 없음)
skilldo lint <PATH>
SKILL.md의 구조적 오류(프론트매터, 섹션, 코드 블록)를 린트합니다.
skilldo review <PATH>
기존 SKILL.md에 대한 LLM 기반 정확성 및 안전성 검토.
주요 플래그:
--config <PATH>— LLM 설정이 포함된 설정 파일
skilldo config check --config <PATH>
설정 파일의 정확성을 검증합니다.
skilldo auth login|status|logout
OAuth를 사용하는 제공자(예: ChatGPT)의 OAuth 토큰을 관리합니다.
지원 언어
| 언어 | 생태계 | 감지 방식 |
|---|---|---|
| Python | pip/uv, pyproject.toml, setup.py | *.py, pyproject.toml |
| JavaScript/TypeScript | npm, package.json | *.js, *.ts, package.json |
| Go | go modules, go.mod | *.go, go.mod |
| Rust | cargo, Cargo.toml | *.rs, Cargo.toml |
| Java | Maven/Gradle, pom.xml, build.gradle | *.java, pom.xml, build.gradle |
설정 (skilldo.toml)
핵심 [generation] 필드:
| 필드 | 값 | 설명 |
|---|---|---|
language | python, javascript (또는 typescript/ts/js), rust, go, java | 자동 감지 재정의 |
security_context | "api-client" 또는 생략 | API 키/인증을 논의하는 API 클라이언트 SDK에 대한 보안 스캔 완화 |
redact_env_vars | ["VAR_NAME", ...] | 테스트 출력/로그에서 ***REDACTED***로 마스킹될 환경 변수 값 |
custom_instructions | """...""" | 생성 단계를 위한 레포지토리별 지침 (스타일/내용 규칙 재정의) |
enable_test | true/false | 테스트 검증 전환 (기본값: true) |
enable_review | true/false | 검토 검증 전환 (기본값: true) |
test_mode | thorough/quick/minimal/adaptive | 모든 패턴/최대 3개/1개/1+개 패턴 테스트 |
max_retries | 정수 | 생성→검증 최대 재시도 횟수 (기본값: 10) |
모델 통신
모델은 최종 SKILL.md에서 제거되기 전에 HTML 주석을 통해 출력에서 불확실성을 보고합니다:
<!-- SKILLDO-CONFLICT: 설명 -->— 문서와 코드 간 충돌 발견<!-- SKILLDO-UNVERIFIED: 설명 -->— 모델이 소스에서 확인할 수 없는 API
RUST_LOG=info 또는 RUST_LOG=debug로 확인하세요. CONFLICT는 info 수준, UNVERIFIED는 warn 수준으로 로깅됩니다.
일반적인 워크플로우
Anthropic으로 생성
source ~/.anthropic
skilldo generate --provider anthropic --model claude-sonnet-4-6
OpenAI로 생성
source ~/.openai
skilldo generate --provider openai --model gpt-5.2
로컬 Ollama로 생성
skilldo generate --provider openai-compatible --model qwen3-coder:latest --base-url http://localhost:11434/v1
일괄 생성 (여러 레포지토리)
for repo in /path/to/repos/*/; do
skilldo generate "$repo" --config shared-config.toml --best-effort
done
API 클라이언트 SDK에 대한 생성
# skilldo.toml — API 키/인증을 논의하는 라이브러리용
[generation]
security_context = "api-client"
redact_env_vars = ["MY_API_KEY"]
export MY_API_KEY="..." # 테스트 검증에 필요
skilldo generate . --config skilldo.toml
재생을 통한 빠른 프롬프트 반복
# 캐시를 한 번 캡처
skilldo generate /path/to/lib --debug-stage-files /tmp/cache -o /tmp/baseline.md
# 프롬프트 반복 (생성 단계만 실행, 약 5분 vs 약 15분)
skilldo generate /path/to/lib --replay-from /tmp/cache -o /tmp/variant.md
파이프라인 단계 디버깅
skilldo generate . --debug-stage-files ./debug-output/
# 다음 파일 작성: 1-extract.md, 2-map.md, 3-learn.md, 4-create-raw.md, 4-create-system.md, facts.md,
# 5-review-*.txt, 6-normalized.md
기존 SKILL.md 검토
skilldo review SKILL.md --config skilldo.toml
원격 측정
telemetry = true인 경우, 각 실행은 ~/.skilldo/runs.csv에 행을 추가합니다:
- 타임스탬프, 언어, 라이브러리 이름, 버전
- 사용된 모델 및 제공자 (생성, 검토, 테스트)
- 성공/실패, 재시도 횟수, 지속 시간, 실패 세부 정보
데이터는 로컬 전용이며 어디로도 전송되지 않습니다.
문제 해결
- "테스트 파일을 찾을 수 없음" — 오류가 아닌 경고입니다. 파이프라인은 테스트 파생 패턴 없이 계속됩니다. 감지가 잘못된 경우
--language를 사용하여 재정의하세요. - 테스트 실패 반복 — 첫 번째 패스로
--test-mode minimal또는--no-test를 시도하세요. - 속도 제한 — 설정에서
retry_delay를 늘리거나 로컬 모델로 전환하세요. - OAuth 오류 —
skilldo auth status --config <path>를 실행하여 토큰 상태를 확인하세요. - 비Python에서 install_source 오류 —
local-install/local-mount는 Python에서만 작동합니다. 다른 언어는 기본registry를 사용하세요.
문서
전체 문서 — 설정, 언어, 아키텍처, 인증, 모범 사례 및 원격 측정: docs/