Muse Autoskill

muse-autoskill은 SKILL.md 기반 에이전트 스킬을 로컬 파일 시스템에서 만들고, 테스트하고, 등록하고, 다른 에이전트 스킬 경로로 내보내는 CLI-first 도구입니다.

핵심 방향은 명확합니다.

메인 제품: autoskill CLI
핵심 산출물: SKILL.md 스킬 패키지
기본 저장소: ~/.autoskill/skills
에이전트 연결: autoskill-runner 스킬
MCP: v1 범위 아님

설치

개발 모드 설치:

python -m pip install -e .

설치 확인:

autoskill --help

빠른 시작

autoskill init
autoskill catalog --format yaml

autoskill create \
  --from-session ./session-notes.md \
  --name pdf-excel-diff \
  --description "PDF와 Excel 결과를 비교하는 반복 작업"

autoskill test pdf-excel-diff
autoskill register pdf-excel-diff
autoskill export pdf-excel-diff --target codex
autoskill memory append pdf-excel-diff --message "표 병합 셀은 수동 검증이 필요했음."

기본 홈은 ~/.autoskill입니다. 다른 위치를 쓰려면:

export AUTOSKILL_HOME=/path/to/autoskill-home

디렉터리 구조

autoskill init을 실행하면 다음 구조가 만들어집니다.

~/.autoskill/
  catalog.json
  skills/
    autoskill-runner/
      SKILL.md
      .autoskill.json
      .memory.md
  staging/
  sessions/

skills/는 등록된 스킬 저장소입니다. staging/은 create --from-session으로 생성된 draft가 들어가는 곳입니다.

스킬 패키지 형식

<skill-name>/
  SKILL.md
  .autoskill.json
  .memory.md
  scripts/
  tests/
  resources/
  references/

필수 파일은 SKILL.md입니다. autoskill이 생성한 패키지는 lifecycle 추적을 위해 .autoskill.json도 포함합니다.

SKILL.md 최소 예시:

---
name: pdf-excel-diff
description: PDF 표와 Excel 데이터를 비교해 차이 보고서를 만든다.
---

# PDF Excel Diff

## When To Use

- PDF와 Excel 결과를 비교해야 할 때

## Workflow

1. 입력 파일을 확인한다.
2. 표 데이터를 추출한다.
3. 차이를 계산한다.
4. 결과 보고서를 작성한다.

명령어

autoskill init

Autoskill 홈 디렉터리를 초기화합니다. 내장 autoskill-runner 스킬도 등록합니다.

autoskill init

autoskill list

등록된 스킬 목록을 출력합니다.

autoskill list

autoskill catalog

에이전트에 먼저 보여줄 progressive-disclosure 카탈로그를 출력합니다. 전체 SKILL.md가 아니라 name, description, path만 보여줍니다.

autoskill catalog --format json
autoskill catalog --format yaml

autoskill inspect

스킬의 SKILL.md, .memory.md, .autoskill.json, 파일 목록을 출력합니다.

autoskill inspect pdf-excel-diff

autoskill create --from-session

세션 파일 또는 세션 디렉터리에서 draft 스킬을 생성합니다.

autoskill create \
  --from-session ~/.autoskill/sessions/example-run \
  --name invoice-audit \
  --description "인보이스 검증 워크플로우"

세션 디렉터리에 아래 파일이 있으면 우선적으로 SKILL.md에 반영합니다.

instruction.md
agent_message.md
memory.md
run_meta.json
profile.json
events.jsonl
agent.stdout.txt

생성 위치:

~/.autoskill/staging/<skill-name>/

autoskill test

스킬의 tests/를 실행합니다.

autoskill test invoice-audit

pytest가 있으면 pytest를 사용합니다. pytest를 사용할 수 없으면 표준 라이브러리 기반의 간단한 test_*.py runner로 fallback합니다.

테스트가 없으면 문서형 스킬로 보고 통과 처리합니다.

autoskill register

staging draft를 테스트한 뒤 등록합니다.

autoskill register invoice-audit

등록 위치:

~/.autoskill/skills/<skill-name>/

테스트 실패 시 등록하지 않습니다.

autoskill export

등록된 스킬을 다른 에이전트 스킬 경로로 내보냅니다. export 전에도 테스트를 다시 실행합니다.

Codex / Agent Skills:

autoskill export invoice-audit --target codex
autoskill export invoice-audit --target agents

출력 위치:

$HOME/.agents/skills/<skill-name>/

Claude Code:

autoskill export invoice-audit --target anthropic

출력 위치:

$HOME/.claude/skills/<skill-name>/

임의 경로:

autoskill export invoice-audit --target path --path ./exported-skills

autoskill memory append

스킬별 memory에 timestamped note를 append합니다. 기존 memory를 수정하거나 재정렬하지 않습니다.

autoskill memory append invoice-audit --message "OCR 결과가 흔들릴 때 표 좌표를 먼저 검증해야 함."

에이전트에서 사용하는 방식

에이전트가 autoskill을 자동으로 활용하려면 autoskill-runner 스킬을 에이전트가 읽을 수 있어야 합니다.

Codex

이 저장소 안에서는 repo-local 스킬이 이미 있습니다.

.agents/skills/autoskill-runner/SKILL.md

전역으로 설치하려면:

autoskill init
autoskill export autoskill-runner --target codex

설치 위치:

~/.agents/skills/autoskill-runner/SKILL.md

Claude Code

autoskill init
autoskill export autoskill-runner --target anthropic

설치 위치:

~/.claude/skills/autoskill-runner/SKILL.md

기타 에이전트

해당 에이전트가 SKILL.md 디렉터리를 읽는다면 --target path로 적절한 경로에 내보내면 됩니다.

autoskill export autoskill-runner --target path --path /path/to/agent/skills

스킬 디렉터리 개념이 없다면 system prompt나 agent instruction에 autoskill-runner/SKILL.md 내용을 넣어야 합니다.

보안 정책

현재 구현은 다음을 차단합니다.

• SKILL.md frontmatter의 악성 이름 예: ../../outside
• ../staging/<skill> 방식의 export 우회
• 테스트 실패 스킬의 register/export
• symlink가 포함된 스킬 패키지 복사
• export 대상 경로에 이미 같은 스킬이 있는 경우 덮어쓰기

개발 검증

pytest -q
python -m compileall autoskill

실제 CLI 설치 검증:

python -m venv /tmp/autoskill-venv
/tmp/autoskill-venv/bin/python -m pip install -e .
/tmp/autoskill-venv/bin/autoskill init
/tmp/autoskill-venv/bin/autoskill catalog --format yaml

설계 문서

CLI-first 결정을 포함한 설계 근거는 다음 문서를 봅니다.

docs/autoskill-cli-first-decision.md