wp-interactivity-api

wp-interactivity-api skill 개요

이 skill이 하는 일

wp-interactivity-api skill은 WordPress Interactivity API 기능을 만들거나 디버깅할 때, directive, store 구조, 서버/클라이언트 연결을 추측하지 않도록 도와줍니다. data-wp-* 마크업, @wordpress/interactivity, viewScriptModule, wp_interactivity_*() 함수를 다루면서, 깨진 인터랙션을 실제 동작하는 상태로 되돌리는 실용적인 경로가 필요할 때 특히 유용합니다.

누구에게 적합한가

WordPress 블록, 테마, 플러그인에서 Frontend Development를 하면서 첫 렌더 이후에도 매끄럽게 유지되는 인터랙티브 UI가 필요하다면 wp-interactivity-api skill을 쓰세요. 이미 repo가 있고, hydration이 왜 실패하는지, directive가 왜 발동하지 않는지, 새 인터랙티브 영역을 어떻게 올바르게 구성해야 하는지 추적해야 할 때 잘 맞습니다.

설치할 만한 이유

가장 큰 가치는 판단 속도입니다. 무엇을 검색해야 하는지, 어떤 입력이 중요한지, block 기반 접근과 theme 수준 접근, plugin 확장 접근을 어떻게 구분해야 하는지 알려줍니다. 그래서 wp-interactivity-api guide는 실제 WordPress 6.9+ 제약과 이 API의 연결 방식을 반영한다는 점에서, 일반적인 prompt보다 훨씬 유용합니다.

wp-interactivity-api skill 사용하는 방법

올바르게 설치하고 범위를 잡기

디렉터리 진입점에서 wp-interactivity-api install 패턴을 사용한 다음, bash와 Node가 उपलब्ध한 filesystem-backed agent session 안에서 skill을 적용하세요. repository에는 WordPress 6.9+ 호환성과, 일부 workflow에서는 WP-CLI가 명시되어 있습니다. 환경이 project 파일을 검사할 수 없거나 WordPress command를 실행할 수 없다면 결과 품질은 떨어집니다.

시작 입력을 제대로 주기

wp-interactivity-api usage는 다음 정보를 제공할 때 가장 잘 동작합니다:

• repo root
• wp-project-triage의 triage output
• 영향 범위: frontend, editor, 또는 둘 다
• WordPress 버전과 module/build 제약 사항

약한 prompt 예시: “Interactivity API를 고쳐줘.”
더 강한 prompt 예시: “이 block의 frontend에서 data-wp-on--click이 왜 발동하지 않는지 디버깅해줘. WordPress 6.9이고 module scripts가 활성화되어 있으며, triage를 첨부했어. 문제는 navigation 이후에만 나타나.”

먼저 읽어야 할 파일

먼저 SKILL.md를 열고, 그다음 아래 파일을 확인하세요:

• directive 이름과 검색용 anchor를 위한 references/directives-quickref.md
• 실패 체크리스트를 위한 references/debugging.md
• PHP 측 설정과 hydration 규칙을 위한 references/server-side-rendering.md

현재 작업에 이 skill이 맞는지 판단하려는 경우, repo tree만 보는 것보다 이 세 파일이 실제 workflow를 더 빨리 보여줍니다.

실무 workflow를 따르기

이 skill은 다음의 단순한 순서를 중심으로 구성되어 있습니다:

1. data-wp-interactive, @wordpress/interactivity, viewScriptModule 검색으로 기존 사용 여부를 찾는다
2. store namespace를 식별하고, 마크업이 같은 이름을 기대하는지 확인한다
3. server-rendered context와 초기 state를 검증한다
4. 렌더된 HTML에서 root element, view script module, event directive가 모두 존재하는지 점검한다
5. 깨진 directive나 state 경로가 분리될 때까지 범위를 줄인다

새로운 interactive block을 만들 때는 구조를 처음부터 invent하지 말고 공식 scaffold template을 우선 사용하세요.

wp-interactivity-api skill FAQ

디버깅용만인가요?

아닙니다. wp-interactivity-api skill은 build와 debug 작업을 모두 다룹니다. block의 viewScriptModule로 interactivity를 추가할지, plugin의 기존 마크업을 확장할지, theme 수준 동작을 hydration이 깨지지 않게 연결할지 결정해야 할 때 특히 유용합니다.

일반적인 prompt와 뭐가 다른가요?

일반적인 prompt는 실제 성공 여부를 가르는 WordPress 전용 세부사항을 자주 건너뜁니다. directive 이름, store namespace 일치 여부, server-side context, WordPress 6.9 동작 변경이 그것입니다. 이 skill은 그런 점검을 기본값으로 포함하므로, 시행착오를 줄이고 agent가 먼저 읽어야 할 파일을 제대로 고르게 해줍니다.

초보자도 쓰기 쉬운가요?

네, 목표를 설명하고 agent를 올바른 repo 영역으로 안내할 수 있다면 그렇습니다. API 전체를 처음부터 배우는 tutorial은 아니지만, interactive root 누락, namespace 불일치, 잘못된 rendering path 같은 흔한 도입 실수를 피하는 데 큰 도움이 됩니다.

언제는 쓰지 말아야 하나요?

WordPress Interactivity API와 무관한 JavaScript UI 작업에는 쓰지 마세요. 또한 기능이 완전히 static해서 server-rendered directive가 필요하지 않은 경우에도 맞지 않습니다. 실제 repo 파일을 확인할 수 없다면 이 skill은 적합하지 않습니다. repo별 마크업과 PHP/JS integration 세부사항에 의존하기 때문입니다.

wp-interactivity-api skill 개선 방법

source context를 더 정확하게 제공하기

가장 좋은 결과는 현재 block, theme, plugin surface와 함께 검토받고 싶은 정확한 directive나 function을 보여줄 때 나옵니다. data-wp-interactive, data-wp-context, 그리고 대응하는 store namespace 주변 코드 조각을 포함하세요. 그래야 agent가 구현을 추측하는 대신 의도와 실제 코드를 비교할 수 있습니다.

증상만 말하지 말고 실패 양상을 적기

wp-interactivity-api skill에서 “버튼이 아무 반응이 없다”는 너무 모호합니다. 더 나은 입력은 관찰 가능한 문제와 기대 동작을 함께 적습니다. 예: “click handler는 연결되지만 server render 후 state가 업데이트되지 않는다”, 또는 “first load에서는 hydration이 되지만 client-side navigation 후에는 실패한다.” 이렇게 해야 directive 문제인지, state initialization 문제인지, module loading 문제인지 구분하기 쉬워집니다.

repository-reading output을 요청하고, 그다음 반복하기

좋은 wp-interactivity-api guide workflow는 다음을 요청하는 것입니다:

• 가장 가능성 높은 root cause
• 다음에 정확히 검사할 파일
• 최소 수정 코드
• WordPress 6.9 호환성 위험

그다음 첫 결과를 바탕으로 반복하세요. 문제가 server rendering과 관련 있다면 관련 PHP와 rendered HTML을 함께 넣으세요. event handling 문제라면 directive 마크업과 store actions 파일을 포함하세요. 그러면 이 skill이 단순한 검색 도구가 아니라 실제 구현 체크리스트가 됩니다.