inject skill
이 skill은 세 facet을 담는다 — /ait:inject-devtools(devtools unplugin 주입), /ait:inject-debugger-client(on-device attach 패키지 설치), /ait:inject-tossface(이모지 서체 Tossface 배선). 셋 다 기존 프로젝트의 빌드 셋업을 최소 변경으로 패치하는 brownfield station 2 도구라 하나로 묶였다(agent-plugin#280 debugger-client facet 추가). 사용자가 어느 command로 진입했는지에 따라 아래 해당 facet으로 분기한다 — 세 facet은 독립이며 서로를 자동 실행하지 않는다.
목적
이미 @apps-in-toss/web-framework를 쓰는 기존 미니앱 프로젝트의 개발 환경을 확장한다.
new-miniapp이 greenfield(빈 디렉토리)라면 이 skill은 brownfield — 기존 파일을 최소한으로
수정하고, 이미 설정이 있으면 skip한다. 어느 facet이든 생성·수정하는 파일에 과장·홍보성 문구를
넣지 않는다.
세 facet은 목적이 다르다:
- devtools facet (
/ait:inject-devtools):@apps-in-toss/devtoolsunplugin을 빌드 config에 추가해 토스 앱 없이 브라우저에서 mock SDK로 개발·테스트한다. 인자 없음. - debugger-client facet (
/ait:inject-debugger-client):@apps-in-toss/debugger-client(on-device attach)을 **devDependencies**로 설치하고, 빌드 타임__DEBUG_BUILD__게이트 import를 진입점에, 그 값을 정하는define을 번들러 설정에 와이어업한다. 기본 빌드는 값이false라 번들에 attach 코드가 들어가지 않고,AIT_DEBUG_BUILD=1을 명시한 디버그 빌드만true가 되어 환경 3(intoss-private) on-device 디버깅에 attach 표면을 남긴다. 디버그 빌드는 검수·출시에 올리지 않는다. 인자 없음. - tossface facet (
/ait:inject-tossface): 이모지를 토스페이스 글리프로 렌더하도록 CDN 링크 또는 서체 subset 번들을 프로젝트 전역 스타일시트에 와이어업한다.designskill의 서체 정책상 본문 서체는 금지 대상이지만 이모지 서체(Tossface)는 권장 대상이다. 인자 없음.
devtools facet — /ait:inject-devtools
번들러는 스택을 가정하지 않고 프로젝트의 package.json scripts와 번들러 설정 파일에서 읽는다.
lockfile로 패키지 매니저를 감지해 @apps-in-toss/devtools를 devDep으로 설치한 뒤,
설치된 패키지 README(node_modules/@apps-in-toss/devtools/README.md)에서 그 번들러의 배선
절을 찾아 그대로 등록한다. 번들러별 코드는 이 skill이 들고 있지 않다. README가 다루지 않는
번들러면 사용자에게 알리고 묻는다. 이미 설정이 있으면 skip. 콘솔 인증 불필요 — 로컬 dev
전용이고, production 번들에는 넣지 않는다.
핵심 절차: (1) package.json 확인 → (2) 번들러 확인 → (3) PM 감지 → (4) idempotency
확인 → (5) devDep 설치 → (6) README의 해당 번들러 절대로 최소 변경 등록 → (6-1) dev 서버·빌드로
사후 검증 → (7) 완료 seam. README 읽는 법·지원 범위 밖 처리·유지할 앱인토스 고유 사실·하지
말아야 할 것은 —
상세가 필요하면 Read <이 skill의 base directory>/references/devtools.md.
debugger-client facet — /ait:inject-debugger-client
@apps-in-toss/debugger-client을 **devDependencies**로 설치하고(harness GitHub Release
tarball URL — npm 미발행), 진입점에 빌드 타임 게이트 import를 멱등하게 삽입한다.
declare const __DEBUG_BUILD__: boolean;
declare const __AIT_RELAY_KEYS__: ReadonlyArray<{ publicKey: string; notAfter: number }>;
if (__DEBUG_BUILD__) {
import('@apps-in-toss/debugger-client').then((m) =>
m.startDebugConsole({ relayPublicKeys: __AIT_RELAY_KEYS__ }),
);
}
__AIT_RELAY_KEYS__는 번들러 define이 디버그 빌드에서만 채운다.
define: { __AIT_RELAY_KEYS__: JSON.stringify(debugBuild ? await readRelayPublicKeys(process.cwd()) : []) }
처럼 @apps-in-toss/debugger/relay-keys의 readRelayPublicKeys를 쓴다. 이 함수는 키 에이전트(메모리 전용)에서
공개키와 만료 시각만 받아 오고, 디스크에 비밀을 만들지 않는다. 키는 기본 24시간 유효하므로 만료되면 디버그 번들을
다시 빌드해 업로드한다. 공개키는 커밋하지 않아도 된다. QR 테스트 호스트에서는 이 키로 attach URL의 서명을
확인하므로 키가 없으면 연결되지 않는다(blocked-relay-key).
__DEBUG_BUILD__는 번들러 define이 환경 변수 AIT_DEBUG_BUILD에서 읽어 정한다. 기본(release)
빌드는 false로 접혀 번들러가 패키지 그래프를 통째로 지우므로 배포 번들에 attach 코드가
남지 않는다. AIT_DEBUG_BUILD=1을 명시한 디버그 빌드만 true가 되고, 설정 파일에
'true'를 고정으로 쓰지 않는다. 릴리즈 빌드는 npm run build, 디버그 빌드는
AIT_DEBUG_BUILD=1 npm run build다. 디버그 빌드는 검수·출시에 올리지 않는다. 번들러는 package.json과
설정 파일에서 읽고, 하나로 좁혀지지 않으면 추측하지 않고 사용자에게 묻는다.
런타임 self-gate만 있는 /auto import는 코드가 번들에 남으므로 삽입하지 않는다.
프로젝트에 이미 /auto import가 있으면 사용자에게 알린 뒤 게이트 import로 바꾼다.
프로젝트에 0.3.0 이하의 옛 이름 @apps-in-toss/debug-console이 있으면 "이미 설치됨"으로 끝내지
않는다. 이름이 @apps-in-toss/debugger-client로 바뀌었고 debugger와 함께 0.4.0 이상이어야 연결되므로,
setup-debugger/references/upgrade-check.md의 마이그레이션 경로(0절·2-B절)로 안내한다.
이 패키지는 예전 @apps-in-toss/devtools의 ./in-app export였다 — devtools의 MCP
데몬·on-device attach 표면이 debugger 패키지(@apps-in-toss/debugger +
@apps-in-toss/debugger-client)로 분리되면서 나뉘었다.
핵심 절차: (1) package.json 확인 → (2) 기존 설치·와이어업 확인(idempotency, 게이트 없는
/auto 발견 포함) → (3) 번들러 감지 → (4) devDependencies로 설치 → (5) 진입점 감지 +
게이트 import 삽입 → (6) 번들러 define 추가 → (7) 빌드 두 번으로 검증(기본 빌드에서 마커
0건, 마지막 빌드는 릴리즈 빌드로 남김) → (8) 완료 seam. 하지 말아야 할 것은 —
상세가 필요하면 Read <이 skill의 base directory>/references/debugger-client.md.
tossface facet — /ait:inject-tossface
이모지를 토스페이스 글리프로 렌더한다. design skill의 서체 정책상 본문 서체(Toss Product Sans 계열)는 금지지만, 이모지 서체 Tossface(toss/tossface로 공개 배포)는
금지 대상이 아니라 권장 대상이다 — 시스템마다 모양이 갈리는 이모지 대신 어디서나
같은 글리프로 렌더된다. 먼저 기존 배선 여부를 grep으로 확인해(idempotency) 이미 있으면
skip한다. 콘솔 인증 불필요 — 로컬 작업이다.
두 모드 중 하나를 사용자 확인 후 진행한다 — **모드 A(CDN 링크)**는 번들 증가 0이고 토스 앱 webview에서 CDN 로드가 확인됐지만(2026-10-14, iOS·Android) 네트워크에 의존하고, **모드 B(subset 번들 포함)**는 네트워크 없이 결정적으로 동작하지만 담는 subset마다 약 520KB~1.9MB가 늘고 라이선스가 요구하는 저작권 고지·전문 동봉이 따른다.
핵심 절차: (0) 기존 배선 확인(idempotency) → (1) 두 모드 대가 계산 + 모드 확정 →
(2) 모드 A는 @import/<link> 삽입, 모드 B는 코드포인트 대조 → subset 선정(+ 선정
직후 재확정) → 원본 파일 배치 → 라이선스 동봉 → CSS 작성 → (3) font-family 맨
앞에 Tossface 추가 → (4) 완료 seam. @import 위치 제약(다른 규칙보다 항상 앞에
와야 한다)·정확한 CDN 스니펫·라이선스 근거는 —
상세가 필요하면 Read <이 skill의 base directory>/references/tossface.md.
다음 단계 (facet별 seam)
세 facet 모두 seam을 슬래시 + 자연어 2표면으로 인쇄한다(통일 규칙 —
로컬 docs/design/skill-conventions.md(repo 미포함 — maintainer-local) §9).
devtools facet 완료 후:
@apps-in-toss/devtools 설정 완료 · <config-file> 패치
다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
npm run dev # 브라우저에서 앱 실행 (프로젝트의 dev 스크립트, 하단에 AIT DevTools 패널)
# 말로: "브라우저에서 개발 서버 띄워줘"
/ait:debug # 브라우저 패널·window.__ait 상태로 디버깅
# 말로: "브라우저에서 앱 상태가 이상한데 디버깅해줘"
debugger-client facet 완료 후:
@apps-in-toss/debugger-client 설정 완료 · <진입점>에 __DEBUG_BUILD__ 게이트 import, <설정 파일>에 define 추가
다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
AIT_DEBUG_BUILD=1 npm run build # 디버그 빌드에만 attach 표면 포함 (기본 빌드에는 없음, 검수·출시에 올리지 않음)
# (2.x 폴백은 AIT_DEBUG_BUILD=1 npm run bundle:ait)
/ait:debug # 환경 3 QR attach로 on-device 디버깅
# 말로: "미니앱이 폰에서 이상하게 동작하는데 라이브 상태를 디버깅하고 싶어"
tossface facet 완료 후:
Tossface 배선 완료 · <모드 A: CDN 링크 추가 | 모드 B: subset <N>개 번들, +<증가량>>
다음 단계 (명령을 몰라도 됩니다 — 따옴표 안 문장을 그대로 말해도 같은 단계로 갑니다):
npm run dev # 브라우저에서 이모지 렌더 확인
# 말로: "브라우저에서 개발 서버 띄워줘"
/ait:design # 화면 렌더 무결성(G7 등) 판정으로 이어서 확인
# 말로: "화면 디자인 품질 점검해줘"
각 facet의 완전한 완료 블록(변경 요약·주의사항 포함)은 세 facet 모두 위 references 파일에 있다.
Out of scope (이 skill이 하지 않는 것)
- ❌ 새 프로젝트 생성 (greenfield) —
/ait:new(new-miniappskill). - ❌ 콘솔 인증·등록·업로드 — console MCP 도구(
miniapp_create/bundle_upload/bundle_upload_complete)의 역할. - ❌ 번들 설정(
apps-in-toss.config.ts) 최초 생성 — 정본 경로(create-ait-app)는/ait:new에 기본 포함,--local폴백만new-miniapp의 L-5 절차로 추가. - ❌ (devtools) 브라우저에서 panel이 실제로 뜨는지의 E2E 검증 — 사용자가 직접
npm run dev로 확인. (dev 서버·빌드가 에러 없이 도는지까지만 이 skill이 확인한다.) - ❌ (devtools) 라이브러리 빌드에 mock 주입 — 앱(미니앱) 전용.
- ❌ (devtools) README에 없는 번들러에 추측으로 배선 — 사용자에게 알리고 묻는다.
- ❌ 실행 중인 앱을 진단하는 것 — 이 skill은 패키지를 설치할 뿐이다. "폰에서 이상하게 동작한다", "라이브 상태를 보고 싶다"는
/ait:debug(debugskill). debugger-client facet은 그 진단을 가능하게 하는 준비물이지 진단 자체가 아니다. - ❌ (debugger-client) MCP 데몬 등록 —
/ait:setup-debugger가 프로젝트.mcp.json에 배선(/ait:debug§5 참조). - ❌ (debugger-client) 게이트 없는
import '@apps-in-toss/debugger-client/auto'삽입 — 배포 번들에 코드가 남는다. - ❌ (debugger-client) 번들러가 불확실한 채로
define을 추측해 쓰는 것 — 사용자에게 묻는다. - ❌ (tossface) 재-subsetting·포맷 변환 — 원본 파일을 그대로만 배치한다
(
references/tossface.md의 "tossface facet 하지 말아야 할 것" 절 참조). - ❌ (tossface) 본문 서체로 사용 — 이모지 서체다. 본문 서체 금지는
designskill의 "토스 브랜드·UI 모방 금지" 절이 다루는 별개 축이다.
참고
- create-ait-app 프로젝트에 IAP/IAA 예제 추가: 이 skill의 두 facet과는
무관한 별도 CLI 서브커맨드지만, 같은 brownfield 자리라 여기 남긴다 —
npx -y create-ait-app@latest add-sample [directory] --inline --sample iap,iaa(directory생략 시 기본값은 cwd.). 대상이 Apps in Toss 프로젝트로 인식될 때만 동작하고(inspectSampleProject()—@apps-in-toss/web-framework의존성 또는apps-in-toss.config.ts존재로 판정, 아니면 즉시 거부),--sample을 생략하면 interactive checkbox 프롬프트로 빠진다. 이 skill은 이 명령을 실행하지 않는다 —new-miniappskill의 Step 6 완료 안내가 같은 명령을 노출한다. - 표준 dev 환경 셋업(브라우저 mock·실기기 미리보기) 등 주제별 가이드는 docs MCP
(
searchDocumentation/getPage)로 조회한다. - devtools facet 상세:
<이 skill의 base directory>/references/devtools.md - debugger-client facet 상세:
<이 skill의 base directory>/references/debugger-client.md - tossface facet 상세:
<이 skill의 base directory>/references/tossface.md - 짝 skill:
new-miniapp(새 프로젝트 생성 — create-ait-app 호출 + devtools 후처리 배선),debug(devtools facet이 깔아둔 브라우저 panel 또는 debugger-client facet이 깔아둔 환경 3 attach 표면을 소비하는 디버깅),design(tossface facet 배선 후 화면 렌더 무결성 판정 — "토스 브랜드·UI 모방 금지" 절이 이모지 서체 정책의 정본). @apps-in-toss/devtools(mock+panel+unplugin, 브라우저 dev 전용) 소스 — 구 repo 이력에만 존재(재생성으로 링크 소멸, maintainer 로컬 백업 mirror에서 열람 가능)@apps-in-toss/debugger-client(on-device attach): https://github.com/toss/apps-in-toss-harness/tree/main/packages/debugger-client@apps-in-toss/debugger(MCP 데몬,/ait:setup-debugger가 프로젝트.mcp.json에 배선): https://github.com/toss/apps-in-toss-harness/tree/main/packages/debuggerTossface(공개 배포 이모지 서체): https://github.com/toss/tossface (LICENSE전문, 공개 안내 페이지https://toss.im/tossface/copyright).