agent-scripts

Juwon Park의 공용 Codex 가드레일, 재사용 가능한 스킬, 이식성 있는 헬퍼 스크립트 모음.

이 저장소는 Juwon이 여러 로컬 레포와 머신에서 공통으로 쓰는 agent 작업 흐름의 기준 미러입니다. 공용 AGENTS.MD, 작업별 스킬, 온보딩 문서, 작은 CLI 헬퍼를 한곳에 모아 두어, 하위 레포가 긴 지시문을 복사하지 않고 여기만 가리키도록 유지합니다.

이 저장소가 필요한 이유

• Codex 가드레일을 하나의 원본으로 유지
• 여러 레포에서 스킬을 반복 작성 없이 재사용
• 작고 이식성 있는 헬퍼 스크립트를 공용 자산으로 관리
• 새 머신 온보딩 절차를 반복 가능하게 정리
• 하위 레포를 pointer-style AGENTS.MD 구조로 유지

빠른 시작

1. ~/Projects 아래로 클론

cd ~/Projects
git clone https://github.com/juwonparkme/agent-scripts.git
cd agent-scripts

2. 온보딩 스크립트 실행

./scripts/onboarding-install

선택 옵션:

./scripts/onboarding-install --run-auth
./scripts/onboarding-install --with-peekaboo
./scripts/onboarding-install --force-write-config
./scripts/onboarding-install --dry-run

3. 필요할 때 바이너리 재빌드

bun build scripts/docs-list.ts --compile --outfile bin/docs-list
bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools

최초 실행 전제조건

이 저장소는 Juwon의 macOS 작업 환경과 경로 규칙을 전제로 합니다.

항목	기대값
macOS 사용자	bagjuwon
레포 위치	~/Projects/agent-scripts
Codex 홈	~/.codex
작업 루트	~/Projects
핵심 도구	git, gh, node, npm, pnpm, bun, rg, jq, trash

전체 체크리스트는 docs/onboarding.md를 보면 됩니다.

여기 들어있는 것

경로	용도
AGENTS.MD	Juwon의 Codex 작업 규칙 원본
skills/	문서, 프론트엔드, 미디어, 자동화, 네이티브 앱, 운영 작업용 재사용 스킬
scripts/	온보딩, 커밋, 문서 점검, 브라우저 자동화 등 작은 헬퍼 스크립트
docs/	온보딩, 릴리즈, slash command, concurrency, agent 관련 문서
tools.md	로컬 머신 도구 카탈로그
bin/	scripts/에서 빌드한 선택적 바이너리

저장소 흐름

flowchart LR
    A["agent-scripts"] --> B["AGENTS.MD"]
    A --> C["skills/*"]
    A --> D["scripts/*"]
    A --> E["docs/*"]
    B --> F["~/.codex/AGENTS.md"]
    C --> G["~/.codex/skills/*"]
    D --> H["하위 레포와 로컬 PATH 도구"]
    E --> H

Loading

자주 하는 워크플로

Pointer-style AGENTS

하위 레포는 긴 공용 지시문을 복사하지 말고, 최소 한 줄만 두고 여기로 연결합니다.

READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing).

이 방식이면 레포별 로컬 지시문은 짧게 유지하면서도 공용 규칙의 원본은 한 곳에서 관리할 수 있습니다.

공용 헬퍼를 다른 레포로 동기화

여기서 공용 가드레일이나 헬퍼 스크립트를 바꿨다면, 같은 워크플로를 쓰는 다른 레포에도 같이 반영합니다.

우선순위가 높은 동기화 대상:

• AGENTS.MD
• scripts/committer
• scripts/docs-list.ts
• 필요 시 bin/ 아래 빌드 산출물

로컬 도구 사용

scripts/committer "docs: onboarding 문구 다듬기" README.md docs/onboarding.md
bin/docs-list
bin/browser-tools --help

대표 스킬

이 저장소에는 여러 스킬이 들어있습니다. 그중 일상 작업 흐름에 가장 자주 걸리는 스킬만 먼저 정리하면 아래와 같습니다.

스킬	이런 때 사용	경로
frontend-design	흔한 AI 느낌 없이 완성도 높은 UI를 만들고 싶을 때	skills/frontend-design/SKILL.md
readme-generator	실제 레포 근거를 바탕으로 사람 중심 README를 쓰고 싶을 때	skills/readme-generator/SKILL.md
repo-readme-designer	repo snapshot 기반으로 더 구조적인 README 설계를 하고 싶을 때	skills/repo-readme-designer/SKILL.md
nano-banana-pro	OpenRouter 기반 이미지 생성/편집이 필요할 때	skills/nano-banana-pro/SKILL.md
song-cover-images	카드뉴스용 앨범 커버 이미지를 번호 순서대로 받을 때	skills/song-cover-images/SKILL.md
canva-cardnews-ops	Canva 카드뉴스 생성, 보정, 내보내기가 필요할 때	skills/canva-cardnews-ops/SKILL.md
domain-dns-ops	Cloudflare/DNS/리다이렉트 운영 작업을 할 때	skills/domain-dns-ops/SKILL.md
write-inc-business-report	소스 문서 기반 한국 상장사 영업보고서를 작성할 때	skills/write-inc-business-report/SKILL.md

전체 목록은 skills/ 아래에서 확인할 수 있습니다.

핵심 스크립트

스크립트	역할
scripts/onboarding-install	이 워크플로용 로컬 머신 초기 세팅 자동화
scripts/committer	지정한 파일만 stage해서 커밋 생성
scripts/docs-list.ts	문서 목록 출력 + front-matter 규칙 점검
scripts/browser-tools.ts	Chrome 탐색, eval, 스크린샷, inspect용 헬퍼
scripts/nanobanana	Nano Banana 이미지 작업용 편의 진입점
scripts/shazam-song	곡 식별 헬퍼
scripts/trash.ts	안전 삭제용 보조 로직

먼저 읽으면 좋은 문서

문서	이런 때 읽기
docs/onboarding.md	새 맥 세팅 또는 환경 드리프트 점검
tools.md	로컬 머신 도구 목록이 필요할 때
docs/subagent.md	subagent 워크플로를 쓰거나 설계할 때
docs/RELEASING.md	릴리즈나 릴리즈 노트를 준비할 때
docs/slash-commands/README.md	재사용 가능한 slash command를 찾을 때

참고

• 이 저장소는 공개 패키지가 아니라 내부 작업 흐름용 레포입니다.
• 많은 명령이 Juwon 개인 머신 경로와 도구 구성을 전제로 합니다.
• 헬퍼는 최대한 이식 가능해야 하므로, 거대한 공용 빌드 체인보다 작은 스크립트를 선호합니다.
• 동작이 바뀌면 같은 변경 안에서 문서도 함께 갱신하는 것을 기본으로 합니다.