wp-block-themes

wp-block-themes 스킬 개요

wp-block-themes가 다루는 범위

wp-block-themes 스킬은 WordPress 블록 테마 작업에 도움을 줍니다. theme.json, 템플릿, 템플릿 파트, 패턴, 스타일 변형, 그리고 흔히 겪는 “왜 스타일이 안 보이지?” 디버깅 흐름까지 포함합니다. 블록 테마에 대해 막연하게 묻는 대신, 파일 시스템을 이해하는 WordPress 전용 워크플로가 필요할 때 가장 유용합니다.

누가 사용하면 좋은가

블록 테마를 구현하거나 유지보수하는 경우, 클래식 테마를 블록 테마로 전환하는 경우, 또는 Site Editor 동작을 점검해야 하는 경우에 wp-block-themes 스킬을 사용하세요. 프런트엔드, 편집기, 사용자가 커스터마이즈한 스타일 전반에서 예측 가능한 결과가 필요한 디자인 구현 작업에 잘 맞습니다.

무엇이 다른가

이 스킬은 의사결정 중심입니다. 무엇부터 확인해야 하는지, 어떤 파일이 중요한지, WordPress가 테마 설정과 사용자 오버라이드를 어떻게 해석하는지 알려줍니다. 그래서 “블록 테마를 도와줘”라고만 모델에 요청하는 것보다 훨씬 실용적입니다. 범위, 호환성, 변경 위치에 대한 추측을 줄여주기 때문입니다.

wp-block-themes 스킬 사용 방법

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

다음 명령으로 설치합니다:
npx skills add WordPress/agent-skills --skill wp-block-themes

wp-block-themes의 설치와 설정에서는, 무엇을 바꾸기 전에 먼저 활성 테마의 루트 범위를 정확히 잡아야 합니다. 저장소에 테마가 여러 개 들어 있다면 정확한 테마 디렉터리와 대상 WordPress 버전을 먼저 확인하세요. theme.json 기능과 동작은 코어 버전에 따라 달라질 수 있습니다.

스킬에 올바른 입력을 주기

wp-block-themes 사용 패턴은 다음 정보를 분명히 줄 때 가장 잘 작동합니다:

• 테마 루트 또는 repo 루트
• 정확한 대상 영역: theme.json, templates/, parts/, patterns/, 또는 styles/
• 문제가 나타나는 위치: Site Editor, 글 편집기, 프런트엔드, 또는 셋 다
• 새로 만드는 작업인지, 변환 작업인지, 디버깅인지

좋은 프롬프트 예시는 다음과 같습니다: “활성 블록 테마의 theme.json을 수정해서 버튼이 편집기와 프런트엔드 모두에서 새 브랜드 색상을 쓰도록 해주세요. 다만 사용자 오버라이드는 유지하세요. 대상은 WordPress 6.9입니다. 필요하면 template parts도 확인해 주세요.”

먼저 읽어야 할 파일

먼저 SKILL.md를 읽고, 이어서 아래 파일들을 확인하세요:

• references/theme-json.md
• references/templates-and-parts.md
• references/patterns.md
• references/style-variations.md
• references/debugging.md
• references/creating-new-block-theme.md

저장소 구조가 불명확하다면 scripts/detect_block_themes.mjs도 확인하세요. wp-block-themes 가이드는 편집 전에 탐지 단계를 먼저 따를 때 가장 강합니다.

올바른 순서로 작업하기

실용적인 작업 순서는 다음과 같습니다:

1. 테마 루트 탐지
2. 문제가 나타나는 표면 확인
3. 관련 reference 파일 검토
4. 동작을 소유해야 할 가장 작은 파일 수정
5. 사용자 커스터마이즈와 캐시된 편집기 상태를 기준으로 테스트

이 순서가 중요한 이유는, “깨졌다”고 보이는 블록 테마 문제가 실제로는 잘못된 테마 파일이 아니라 스타일 계층 구조나 저장된 사용자 설정 문제인 경우가 많기 때문입니다.

wp-block-themes 스킬 FAQ

wp-block-themes는 고급 사용자만 쓰는 건가요?

아닙니다. 어떤 테마를 편집하는지 알고 있고, 바꾸려는 대상도 분명히 설명할 수 있다면 초보자에게도 충분히 친화적입니다. 이 스킬이 WordPress 특유의 경로와 판단을 처리해 주지만, 테마 맥락과 원하는 결과는 여전히 사용자가 제공해야 합니다.

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

일반적인 WordPress 플러그인 작업, 블록 테마 바깥의 PHP 템플릿 계층 디버깅, 또는 테마 파일을 건드리지 않는 시각 디자인 작업에는 wp-block-themes를 쓰지 마세요. 문제가 테마, 사용자 커스터마이즈, Site Editor 중 어디에 있는지 전혀 모를 때도 최적의 선택은 아닙니다.

일반 프롬프트와 뭐가 다른가요?

일반 프롬프트는 테마 파일 시스템, 호환 범위, 블록 테마 파일 위치를 확인하지 않은 채 변경을 제안할 수 있습니다. wp-block-themes 스킬은 theme.json, 템플릿, parts, styles 전반에서 체계적으로 wp-block-themes usage를 적용해야 할 때 더 강합니다. 특히 정확한 파일 배치가 중요한 디자인 구현 작업에서 차이가 큽니다.

도입을 막는 가장 흔한 이유는 무엇인가요?

가장 흔한 장애물은 테마 범위가 불명확한 것, WordPress 버전 목표가 빠진 것, 그리고 테마 기본값과 사용자가 선택한 스타일을 혼동하는 것입니다. 이런 정보를 미리 답할 수 없더라도 스킬이 완전히 무력해지는 것은 아니지만, 첫 결과의 정확도는 떨어질 수 있습니다.

wp-block-themes 스킬 개선 방법

디자인 입력을 더 구체적으로 주기

디자인 구현용 wp-block-themes 결과를 더 좋게 만들려면, 정확한 디자인 의도와 영향을 받는 블록 또는 영역을 제공하세요. 예를 들어 “테마를 더 깔끔하게 해주세요”보다 “모든 템플릿에서 기본 heading 간격과 button radius를 설정해 주세요”라고 말하는 편이 훨씬 좋습니다. 전자는 실행 가능한 지시이지만, 후자는 모델이 요구사항을 추측하게 만듭니다.

기본값과 오버라이드를 분리해서 말하기

흔한 실패 패턴 중 하나는 theme.json 변경이 사용자 커스터마이즈까지 덮어쓸 거라고 기대하는 것입니다. 실제 문제가 저장된 global styles나 선택된 style variation에 있다면 그 사실을 함께 알려야 합니다. 결과를 개선하려면 원하는 것이 다음 중 무엇인지 분명히 적으세요:

• 테마 기본값
• 편집기 컨트롤
• 스타일 변형
• 단일 템플릿 변경

가장 작은 실패 예제로 반복하기

첫 결과가 거의 맞지만 완전히 맞지는 않는다면, 다음 요청에서는 파일 하나와 증상 하나만 남기고 좁히세요. 예를 들어: “styles/blue.json이 선택되지만 새로고침 후 반영되지 않습니다. 이것이 예상 동작인지, 무엇을 테스트해야 하는지 설명해 주세요.” 이런 식의 요청이 넓은 재설계보다 훨씬 나은 디버깅 결과를 만듭니다.

저장소 규칙에 맞는지 검증하기

wp-block-themes 스킬은 편집 전에 저장소가 patterns, style variations, 또는 최소 테마 스캐폴드를 사용하는지 확인할 때 더 잘 작동합니다. 첫 결과가 너무 일반적으로 느껴진다면, repo 파일 경로, 활성 테마 이름, 그리고 적용하고 싶은 정확한 reference 파일을 함께 넣어 다시 실행하세요.