kharmanskyi/open-steps

Open Steps – Claude Code, Codex, Cursor, Gemini 에이전트를 위한 쉬운 언어 "스킬"

개요

• Claude Code, Codex CLI, Cursor CLI, Gemini CLI에 추가할 수 있는 재사용 가능한 스킬(작은 프롬프트 템플릿과 몇 개의 셸 스크립트) 모음입니다.
• 각 스킬은 LLM 에이전트가 기술자가 아닌 사람과의 상호 작용을 평이하고 비기술적인 언어로 출력하고 구조화하는 방법을 지시합니다.
• 이 팩에는 각 에이전트 세션의 시작과 끝에 실행되는 두 개의 훅도 포함되어 있어 라우팅 테이블을 자동으로 삽입하고, 실제 작업이 수행된 경우 에이전트에게 간결한 "원스크린" 보고서 생성을 요청합니다.

주요 기능

스킬	제공 기능	실행 시점
os‑done‑or‑not	원스크린 판정: 완료? 예/아니요, 필요한 입력, 새로운 기술 부채, 안전하게 닫을 수 있는지 여부 플래그.	작업이 완료되었거나 "완료되었나요?"라고 물을 때.
os‑step‑by‑step	사용자가 따라야 할 번호 매겨진 비기술적 지침. 에이전트는 스스로 수행할 수 없는 작업만 사용자에게 요청합니다.	에이전트가 사용자에게 명령 실행, 클릭, 승인 등을 요청해야 할 때.
os‑ask‑simple	평이한 언어의 질문, 예상 비용, 단일 강조 표시된 권장 사항.	에이전트에게 결정 지점이 있거나 확인이 필요할 때.
os‑what‑could‑go‑wrong	프리모템 분석: 결정이 실패할 것이라고 가정하고 역산하여 최종 판정을 내립니다.	돌이킬 수 없는 조치(계약, 마이그레이션, 출시)를 실행하기 전.
os‑whats‑next	검증된 내용을 요약하고 다음 구체적인 작업을 일상적인 언어로 제안합니다.	"남은 것은 무엇인가요?"라고 물을 때 또는 보고서 작성 후.
os‑check‑work	이전 세션의 주장을 재검증하고 불일치 사항과 다음 단계를 보고합니다.	다른 세션이 작업이 완료되었다고 주장할 때.
os‑say‑simple	모든 텍스트 블록(보고서, 주석, 오류)을 사실을 유지하면서 평이한 언어로 다시 작성합니다.	기존 텍스트의 덜 기술적인 버전이 필요할 때.
os‑big‑picture	BIG‑PICTURE.md를 유지 관리하여 제품 기능, 상태, 사용되지 않는 부분, 백로그를 나열합니다. 승인 후 트래커에서 티켓을 열 수 있습니다.	전체 프로젝트 상태 또는 백로그 보기가 필요할 때.

작동 방식

• 각 스킬은 프롬프트를 정의하는 SKILL.md와 실제 예제가 포함된 references/ 폴더가 있는 자체 폴더(skills/os-*)에 있습니다.
• 두 훅(session-start.sh 및 stop-report.sh)은 작은 셸 스크립트입니다. 시작 훅은 라우팅 테이블(각 스킬을 언제 실행할지 에이전트에게 지시하는 작은 마크다운 테이블)과 최신 보고서를 LLM 컨텍스트에 주입합니다. 중지 훅은 세션 종료 시 리포지토리 상태를 시작 시 스냅샷과 비교하고 충분한 파일이 변경된 경우 에이전트에게 보고서 생성을 요청합니다.
• Claude Code의 경우 전체가 스킬과 훅을 자동으로 연결하는 플러그인으로 패키징됩니다. Codex CLI, Cursor CLI, Gemini CLI의 경우 스킬 폴더를 ~/.agents/skills/에 복사하고 각 구성 파일에 라우팅 블록과 훅 정의를 수동으로 추가합니다.
• 이 팩은 자율 병합도 수행할 수 있습니다. PR에 녹색 검사와 승인된 리뷰가 있으면 에이전트가 다시 검증하고 병합합니다(gh pr merge 또는 도구의 기본 병합 명령 사용). 권한은 Claude Code 플러그인 매니페스트의 allowed-tools 필드를 통해 제어됩니다.

설치 빠른 시작

1. git clone https://github.com/kharmanskyi/open-steps.git
2. Claude Code – claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps
   • 라우팅 블록을 ~/.claude/CLAUDE.md에 추가합니다(리포지토리에 기성 스니펫이 제공됨).
3. 기타 에이전트 – 스킬 폴더를 복사합니다:

   mkdir -p ~/.agents/skills && cp -R open-steps/skills/os-* ~/.agents/skills/
   

   • 라우팅 블록을 도구별 상시 지침 파일(Cursor의 경우 ~/.codex/AGENTS.md, 프로젝트 루트 AGENTS.md, 또는 ~/.gemini/GEMINI.md)에 삽입합니다.
   • docs/other-agents.md에 설명된 대로 두 훅을 연결합니다.
4. bash open-steps/doctor.sh를 실행하여 스킬, 라우팅 블록, 훅이 올바르게 설치되었는지 확인합니다.

평가

• 저자는 3개의 Claude 모델(Haiku 4.5, Sonnet 5.5, Opus 5.5)과 3개의 다른 에이전트에 걸쳐 25개의 대표적인 문구에 대한 스모크 테스트를 실행했습니다. 모든 스킬은 주제 관련 쿼리에서 올바르게 실행되었으며 Haiku에서는 전체 활성화율 89%, 최신 모델에서는 100%였습니다. 주제와 무관한 활성화는 관찰되지 않았습니다.
• 자세한 결과와 테스트 하니스는 evals/ 디렉토리(cases.md, results.md, run.sh)에 있습니다.

대상 독자

• 제품 빌더, 프로젝트 매니저, 또는 코드 관련 작업에 LLM 에이전트를 사용하고 싶지만 복잡한 엔지니어링 보고서를 해석하고 싶지 않은 모든 사람.
• 이미 Claude Code, Codex CLI, Cursor CLI, Gemini CLI를 사용하고 있으며 에이전트 출력 위에 일관된 평이한 언어 레이어가 필요한 팀.

라이선스 및 기여

• MIT 라이선스. 무료로 사용, 수정, 재배포할 수 있습니다.
• 기여를 환영합니다. 프로세스는 CONTRIBUTING.md를 참조하세요.

---

요컨대, Open Steps는 LLM 코딩 에이전트의 원시적인 기술적 대화를 간결하고 인간 친화적인 상태 보고서와 단계별 안내로 바꾸는 플러그 앤 플레이 프롬프트 템플릿과 작은 스크립트 세트입니다.