Bensz Agent Skills

에이전트 스킬(Agent Skill)을 파일에서 시스템으로.

Agent Skills 오픈 표준을 따르는 재사용 가능한 Skill 세트, 개발 파이프라인, 그리고 Skill 실행 과정을 검사하고 추적하는 데 도움을 주는 도구들을 제공합니다.

Hosts

Bootstrap

License

빠른 시작 · Skill 탐색 · Kernel · 개발 및 검증 · English

Bensz Agent Skills 프로젝트는 Skill의 생성, 테스트, 문서화, 설치 및 배포를 재사용 가능한 엔지니어링 프로세스로 연결합니다. 나아가 실행 커널인 bensz-skill-kernel (약어: BSK)은 다음과 같은 질문에 답하려고 시도합니다. Skill이 에이전트 시스템의 장기적인 구성 요소가 되었을 때, 그것이 사용될 때 제대로 사용되었는가? 수행해야 할 단계가 누락된 것은 아닌가? 변경 후 성능이 저하되지는 않았는가? 오류 발생 시 어느 단계에서 문제가 발생했는지 확인할 수 있는가?

프로젝트가 하는 일

프로젝트는 세 부분으로 구성됩니다:

• 즉시 사용 가능한 범용 Skills: 자동 테스트, 다중 에이전트 협업, 병렬 작업 공간, 프롬프트 최적화, 연구 그림 그리기, Git 조작, 설치, 문서화 및 결함 피드백을 포괄합니다.
• Skills 개발 및 유지보수 파이프라인: 통일된 약속에 따라 개발 → 테스트 → 문서화 → 설치 → 사용 → 피드백 → 반복 과정을 연결합니다.
• Skill 실행 및 검사 도구: bensz-skill-kernel는 작업 단계 관리, 자동 검사, 작업 공간, 증거 기록(evidence record), 이벤트 장부(event ledger), 감사 및 실행 기록 재현을 제공하고 있습니다.

이러한 도구들은 Skill을 전통적인 프로그램으로 만들려고 하기보다는, 복잡한 에이전트 워크플로우의 핵심 단계, 검사, 그리고 증거를 더 명확하고 추적하기 쉽게 만듭니다.

이 프로젝트를 하는 이유

Skill의 수와 프로세스 복잡도가 증가함에 따라, 단순히 긴 SKILL.md만으로는 다음 질문에 답하기 어렵습니다: Skill이 올바르게 트리거되었는지, 단계가 누락되지는 않았는지, 수정 후 성능이 저하되지는 않았는지, 협업 과정이 추적 가능한지, 결과가 어떤 검사를 거쳤는지, 그리고 실패가 어디서 발생했는지. 본 프로젝트는 따라서 초점을 '단일 Skill 작성'에서 더 포괄적인 시스템화된 Skill 구축으로 옮기려고 시도합니다.

설계 원칙

• 개방 표준 우선: 특정 플랫폼에 얽매이지 않도록 합니다.
• Skill과 범용 도구 분리: 구체적인 워크플로우는 Skill에 남기고, 일반적인 실행, 검사 및 기록 기능은 Kernel에 배치합니다.
• 암시적 추측보다 명시적 상태 우위: 기본 신뢰보다는 검사를 선호하고, 비추적 가능성보다 재현 가능성을 선호합니다.
• 점진적 향상: 일반 Skill은 단순하게 유지하며, 더 강력한 실행 및 검사 기능이 필요할 때만 사용합니다.

30초 시작

저장소 클론 없이도 skills/alpha의 프로덕션 Skill을 설치할 수 있습니다 (Python 3.8+ 및 네트워크 필요):

python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --source general

저장소를 클론했고 로컬 개발이 필요한 경우:

python3 skills/alpha/install-bensz-skills/scripts/install.py --codex

설치기는 기본적으로 Skill을 ~/.codex/skills/와 ~/.claude/skills/에 복사합니다. 특정 Skill만 설치하려면 --skill git-commit을 추가할 수 있습니다. skills/beta/는 명시적으로 --source를 전달했을 때만 처리됩니다.

이 저장소가 제공하는 것

• 직접 설치 가능한 Skill: skills/alpha/에 위치하며, 각 디렉터리에는 사용자용 README.md와 AI용 SKILL.md가 있습니다.
• 개발 파이프라인: 초기화, Prompt 최적화, 문서 생성, 비판적 테스트, 다중 에이전트 협업, Git 배포 및 결함 피드백을 포괄합니다.
• 태스크 실행 코어: packages/bensz-skill-kernel/는 bsk CLI를 제공하며, 이를 통해 태스크 단계 관리, 검사 실행, 증거 저장, 이벤트 기록 및 실행 기록 재현이 가능합니다.
• 감사 가능한 협업: 태스크 과정 자료는 .bensz-api/에, 기여 기록은 docs/contribution.bac에 저장됩니다.

Skill 탐색

현재 skills/alpha/에는 16개의 프로덕션 Skill이 포함되어 있습니다:

물론, 제가 생각하기에 가장 좋은 방법은 다음과 같습니다: 당신의 Codex/Claude Code에 이 프로젝트 주소를 붙여넣고 AI로 탐색을 시작하는 것입니다!

설치 방식

원격 유도 설치

bootstrap_install.py는 Python 표준 라이브러리만 의존하며, 최소 Python 3.8이 필요합니다. 이는 이 저장소에서 Python 3.8, 3.9 및 3.10을 호환하는 최초/임시 진입점이며, 해당 호환 범위가 로컬 전체 설치기 또는 Kernel이 이러한 버전을 지원한다는 것을 의미하지는 않습니다. 기본 원격 소스는 skills/alpha/install-bensz-skills/config.yaml에 정의되어 있습니다:

# 미리보기, 파일에 쓰지 않음
python3 -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/huangwb8/skills/main/skills/alpha/install-bensz-skills/scripts/bootstrap_install.py').read())" --check

...

로컬 설치 및 개발

로컬 전체 설치기와 저장소 표준 개발 환경은 Python 3.11 이상을 통일하여 사용하며, --source, --skill, --force 및 --legacy-source 등의 매개변수를 지원합니다:

git clone https://github.com/huangwb8/skills.git
cd skills
python3 skills/alpha/install-bensz-skills/scripts/install.py
...

설치 기록, MD5 목록 및 원격 캐시는 사용자 디렉터리의 ~/.bensz-skills/installation/에 있습니다. 설치기는 beta Skill을 기본 소스에 섞지 않습니다.

이미 설치된 스킬 업데이트

로컬 설치기는 무음 증분 업데이트 진입점(--silent-update)을 제공합니다. 이는 72시간 TTL 만료 후 유지 관리되는 통일된 benszapi Conda 런타임을 통해 설치된 스킬을 업데이트하며, 설치/검사/필터링 매개변수와 함께 사용할 수 없습니다. 원격 설치는 빠른 버전 검사 스크립트를 사용합니다: 이는 원격 버전을 병렬로 읽고, 원격 버전이 더 높거나 로컬에 누락된 경우에만 원격 설치기를 호출하며, --check-only, --skill, --source-contains 등의 매개변수를 지원합니다.

# 무음 증분 업데이트 (TTL 만료 후 실행)
python3 skills/alpha/install-bensz-skills/scripts/install.py --silent-update

...

Kernel

bensz-skill-kernel의 현재 배포 버전은 2.1.6이며, Python 3.11 이상을 요구하고, 실행에 필요한 의존성은 PyYAML과 Python 표준 라이브러리뿐입니다. 일반적인 사용은 설치기에 의해 ~/.bensz-skills/envs/benszapi에 호스팅되며, ~/.bensz-skills/bin/bsk 고정 진입점을 통해 호출되어 프로젝트의 Python이나 PATH 내의 다른 bsk 또는 conda activate에 의존하지 않습니다.

이것은 bsk 명령을 제공하여 작업 단계 관리, 계층적 실행 신원 및 권한 단계 내 동작, 실행 검사, 증거 저장 및 실행 기록 재현에 도움을 줍니다. 일반 사용자는 위 명령을 직접 사용할 수 있습니다. 내부의 State, Verifier, Workspace 등의 개념은 주로 유지보수자를 대상으로 하며, 자세한 내용은 docs/state-id-naming.md, docs/verifier-id-naming.md, docs/state-identity-protocol.md 및 packages/bensz-skill-kernel/README.md를 참조하십시오.

2.1.4 비즈니스 증거 해시 추가 및 참조 바인딩; 2.1.5 bsk state transition이 source Gate을 명시적으로 소비하도록 하고, Gate/result/transition의 읽기 전용 바인딩 조회 기능을 제공합니다; 2.1.6 원자적(atomic) workspace initialize의 첫 번째 State identity가 선언된 도메인 초기 State로 직접 진입할 수 있게 합니다. 이력상의 비바인딩 이벤트는 여전히 읽을 수 있지만, 엄격한 완료 자격을 얻지는 못합니다.

소스 코드 개발은 여전히 저장소 자체의 격리 환경을 사용합니다:

python3 -m venv .bensz-api/.venv
.bensz-api/.venv/bin/python -m pip install -e packages/bensz-skill-kernel
.bensz-api/.venv/bin/bsk --version
...

자주 사용되는 진입점:

BSK="$HOME/.bensz-skills/bin/bsk"
"$BSK" capabilities
"$BSK" state list
...

디렉토리 및 작업 공간 (Directory and Workspace)

skills/alpha/                  # 배포 가능, 기본 설치 Skill
skills/beta/                   # 후보 Skill, 명시적으로 소스를 지정해야 함
packages/bensz-skill-kernel/   # 독립 Python 커널 패키지
...

저장되어야 하는 모든 논리적 작업은 .bensz-api/task-{yyyymmdd-hhmm}-{설명}/를 사용합니다. 공식 README, 소스 코드 및 계획은 프로젝트 약속 디렉토리에 작성되며 숨겨진 작업 공간에는 넣지 않습니다.

개발 및 검증 (Development and Verification)

# 루트 레벨 테스트 (캐시는 .bensz-api에 쓰기)
python3 -m pytest
...

Skill을 수정할 때는 SKILL.md, config.yaml, README 및 CHANGELOG를 동기화 상태로 유지해야 합니다. 중요한 저장소 변경 사항은 먼저 CHANGELOG.md의 [Unreleased]에 기록합니다.

호환성 및 경계 (Compatibility and Boundary)

• Agent Skills 파일 형식은 개방 표준을 따르며, 실제 트리거 능력은 호스트가 Skill 디렉토리를 지원하는지에 달려 있습니다.
• 저장소 개발, 로컬 전체 설치 프로그램 및 Kernel는 Python 3.11 이상을 요구합니다. 원격 부트스트랩(bootstrap)은 최초/비상 설치에 한해 Python 3.8+ 호환성을 유지합니다.
• Kernel의 프로세스 수준 타임아웃, 입출력 제한 및 fail-closed 옵션은 컨테이너나 운영체제 격리 환경이 아닙니다. 신뢰할 수 없는 코드는 여전히 독립된 환경에서 실행되어야 합니다.
• 원격 설치에는 GitHub 접근이 필요합니다. 네트워크 실패 시 로컬 설치 프로그램이나 기존 캐시를 사용할 수 있으며, 설치 종료 코드를 확인해야 합니다.

기여 및 라이선스 (Contribution and License)

먼저 AGENTS.md와 CLAUDE.md를 읽어보십시오. 본 프로젝트는 현재 소통 없이 제출되는 일반 PR은 받지 않습니다. 기여가 필요한 경우, 먼저 huangwb8에게 연락하십시오.

프로젝트는 MIT License를 채택했으며, LICENSE에서 확인할 수 있습니다.

추가 진입점 (More Entry Points)

아래의 진입점들은 각각 버전 변경, 결과 검사, 작업 단계 및 Skill 설치에 대해 소개합니다. 목표에 따라 선택하십시오.

• CHANGELOG.md: 이 프로젝트의 업데이트 로그로, 각 버전별로 추가된 기능, 수정된 문제점, 중요한 조정 사항을 기록합니다. 최근 변경 사항을 알고 싶다면 이곳부터 확인해 보세요.
• Gitee 미러: GitHub 접속이 불편할 경우 Gitee 미러에서 본 프로젝트를 가져올 수도 있습니다.
• docs/bsk-tutorial.md: bsk의 종합 튜토리얼입니다. 일반적인 예시와 Mermaid 다이어그램을 사용하여 State, Verifier, Gate, Contract Pack 네 가지 중요한 추상화 개념과 이들이 어떻게 협력하는지 소개합니다.
• skills/alpha/install-bensz-skills/README.md: Skill 설치기 사용 가이드입니다. 설치 방식, 매개변수 및 일반적인 사용법을 소개하며, Skill을 설치할 준비가 되었다면 이 가이드를 따라 진행할 수 있습니다.
• docs/templates/skill-body.md: Skill을 새로 만들거나 수정할 때 사용하는 4단 구조의 본문 골격입니다.
• docs/templates/verifier-body.md: VERIFIER.md를 새로 만들거나 수정할 때 사용하는 5단 경량 골격으로, 판단 목표, 입력 증거, 실행, 출력 판정, 실패 경계를 다룹니다.
• docs/templates/skill-common-constraints.md: 워크스페이스(workspace), BAC, 프라이버시 및 결함 협업을 위한 공통 제약 조건의 긴 버전입니다.