coreyhaines31/marketingskills 딥다이브
— SKILL.md 47개로 배우는 "AI 에이전트 스킬 설계·배포·운영법"

1프로젝트 한 줄 요약

marketingskills는 "AI 코딩 에이전트를 마케팅 전문가로 변신시키는 능력 팩"이다. Claude Code나 Cursor에 이 저장소를 설치하면, 평소엔 코드만 짜던 에이전트가 "이 랜딩페이지 전환율을 올려 줘", "콜드 이메일 시퀀스 써 줘", "이 사이트 SEO 감사해 줘" 같은 요청에 전문가 수준의 절차와 프레임워크를 따라 답하게 된다. 그 능력 하나하나가 스킬(Skill)이고, 이 저장소엔 마케팅 스킬이 47개 들어 있다.

각 스킬의 정체는 놀랄 만큼 단순하다 — SKILL.md라는 마크다운 파일 한 장이다. 맨 위에 "이 스킬이 무엇이고 언제 쓰는지"를 적은 YAML 머리말이 있고, 그 아래에 에이전트가 따라야 할 지시(프레임워크·체크리스트)가 이어진다. 코드가 아니라 잘 쓴 설명서가 곧 능력이 되는 것 — 이게 2026년 AI 에이전트 생태계를 관통하는 "Agent Skills" 표준의 핵심이다.

2왜 지금 주목받는가

2026년 TrendShift 상위권은 온통 "skills"다 — 이 리스트만 봐도 hallmark, mattpocock/skills, marketingskills, andrej-karpathy-skills 등 스킬 저장소가 줄줄이 올라 있다. AI 코딩 에이전트를 "프롬프트 하나"가 아니라 "설치형 능력 팩"으로 확장하는 흐름이 대세가 됐다는 신호다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.) marketingskills가 그중에서도 눈에 띄는 이유를 넷으로 본다.

주목 포인트 1 — "코딩 말고 마케팅"이라는 빈칸을 정확히 메웠다

대부분의 인기 스킬 팩은 엔지니어를 위한 것(테스트·리팩터링·디버깅)이다. marketingskills는 AI 에이전트를 "1인 창업자·마케터의 실무 도구"로 돌려세운다. 코드는 못 짜도 랜딩페이지·이메일·광고 카피·SEO가 급한 사람이 훨씬 많다. "개발자용 스킬"의 홍수 속에서 비개발 실무자라는 거대한 수요층을 겨눈 몇 안 되는 팩이다.

주목 포인트 2 — 이론이 아니라 "실무자가 직접 쓴" 노하우

저자 Corey Haines는 SaaS 마케팅으로 이름난 실무자(Swipe Files·Conversion Factory 운영)다. 스킬 안에 담긴 건 교과서 요약이 아니라 현장에서 검증된 프레임워크다 — 예컨대 ai-seo 스킬은 "AI가 인용해도 정작 경쟁사를 추천하더라"는 최신 연구 데이터(한 B2B 조사에서 자기 홍보성 글이 얻은 AI 인용의 69%가 경쟁사를 추천하는 답변에 딸려 왔다)까지 인용한다. 실무 감각이 문장마다 배어 있다.

주목 포인트 3 — 한 벌로 Claude·Codex·Cursor 다 된다 (크로스 에이전트)

이 저장소는 특정 도구에 묶이지 않는다. 공용 표준 Agent Skills 스펙(agentskills.io)을 따르고, 흥미롭게도 CLAUDE.md가 실제 파일이 아니라 AGENTS.md를 가리키는 심볼릭 링크다. "에이전트 공용 문서 한 장을 Claude Code도 그대로 읽게" 만든 것 — 덕분에 npx skills add 한 줄이면 Claude Code엔 .claude/skills/로, 범용 에이전트엔 .agents/skills/로 알아서 설치된다.

주목 포인트 4 — "지식"에 "실행 도구"까지 붙였다

스킬(무엇을·언제)만 있으면 에이전트는 조언만 한다. marketingskills는 여기에 실제 API를 호출하는 도구 64개(tools/clis/)를 딸려 보낸다 — GA4·Mixpanel·Ahrefs·Stripe·Klaviyo 같은 마케팅 툴을 의존성 0짜리 Node.js CLI로 감쌌다. "전환율을 분석해 줘"가 조언에서 끝나지 않고 실제 분석 데이터를 끌어오는 데까지 이어질 수 있다.

비슷한 선택지와의 비교

3기술 스택 전체 지도

가장 먼저 뒤집어야 할 통념 — 이건 빌드가 없는 저장소다. 총 418개 파일 중 296개가 마크다운(.md)이고, 컴파일할 소스도, node_modules도 없다. README도 "Skills are content-only, no build step"이라고 못 박는다. 그럼에도 배울 "기술"은 많다 — 스킬을 발견·배포·실행·유지시키는 네 개의 층이 겹겹이 쌓여 있기 때문이다.

계층 1 — 지식 포맷: Agent Skills 스펙 (SKILL.md + YAML 머리말)

모든 스킬은 SKILL.md 하나로 정의된다. 파일 맨 위 --- 사이에 든 YAML 머리말(frontmatter)이 스킬의 신분증이다. 필수 필드는 딱 둘 — name과 description. 아래는 skills/cro/SKILL.md의 실제 머리말이다.

# skills/cro/SKILL.md — 실제 머리말 (요약 인용)
---
name: cro
description: "When the user wants to optimize, improve, or increase
  conversions on any marketing page or form ... Also use when the user
  says 'CRO,' 'conversion rate optimization,' 'this page isn't
  converting,' ... For signup/registration flows, see signup.
  For post-signup activation, see onboarding."
metadata:
  version: 2.0.0
---

# Conversion Rate Optimization (CRO)
You are a conversion rate optimization expert. Your goal is to
analyze marketing pages and provide actionable recommendations ...

계층 2 — 실행 도구: 의존성 0짜리 Node.js CLI 64개

지식만으론 부족할 때를 위한 손발이다. tools/clis/에 GA4·Mixpanel·Ahrefs·Semrush·Klaviyo·Stripe·Apollo·Clay 등 마케팅 SaaS를 감싼 CLI 64개가 있다. 공통 규칙이 인상적이다 — 외부 패키지를 하나도 안 쓰고(Node 18+ 내장 fetch만), 인증은 환경변수로, 그리고 --dry-run으로 "실제로 호출하기 전에 어떤 요청이 나갈지" 미리 볼 수 있다.

# tools/clis/ga4.js — 헤드 (패턴 인용)
const ACCESS_TOKEN = process.env.GA4_ACCESS_TOKEN
if (!ACCESS_TOKEN) {
  console.error(JSON.stringify({ error: 'GA4_ACCESS_TOKEN required' }))
  process.exit(1)
}
async function api(method, baseUrl, path, body) {
  if (args['dry-run'])           # 실제 호출 대신 요청 미리보기만 반환
    return { _dry_run: true, method, url: `${baseUrl}${path}` }
  ...                              # 내장 fetch로 실제 API 호출
}

더 무거운 OAuth 툴(HubSpot·Salesforce·Meta/LinkedIn 광고 등)은 tools/composio/가 단일 MCP 서버로 접근을 대신한다. 툴 전체 지도는 tools/REGISTRY.md가 "툴 × API/MCP/CLI/SDK 지원 여부" 매트릭스로 정리한다.

계층 3 — 배포 매니페스트: plugin.json + marketplace.json

이 스킬 뭉치를 Claude Code 플러그인으로도 설치할 수 있게 하는 두 파일이 .claude-plugin/에 있다. plugin.json은 "이 플러그인의 이름·버전·스킬 폴더 위치"를, marketplace.json은 "마켓플레이스에 어떻게 노출할지"를 선언한다.

# .claude-plugin/plugin.json (전문)
{
  "name": "marketing-skills",
  "description": "Marketing skills for AI agents ...",
  "version": "2.8.10",
  "author": { "name": "Corey Haines" },
  "license": "MIT",
  "skills": "./skills"          # 스킬 폴더를 가리키기만 함
}

계층 4 — 유지·운영: GitHub Actions + 검증 스크립트

47개 스킬을 사람이 손으로 관리하면 곧 어긋난다. 그래서 CI가 자동 정리한다. sync-skills.yml은 skills/가 바뀌면 sync-skills.js를 돌려 marketplace.json·plugin.json·README의 스킬 표를 자동으로 다시 써서 커밋한다(README 안 <!-- SKILLS:START/END --> 구간이 생성물이다). validate-skill.yml과 validate-skills.sh는 머리말 유효성·"이름=폴더명" 일치·500줄 제한 등을 검사한다.

4아키텍처 심화 분석

이 저장소의 진짜 교재적 가치는 여기 있다. "스킬을 어떻게 조직하면 토큰은 아끼면서, 필요한 순간 정확히 펼쳐지고, 서로 안 밟게 할까?" 4개의 설계 원리로 나눠 본다.

4-1. Progressive Disclosure — "3계층 점진적 공개"

가장 중요한 원리. 에이전트의 컨텍스트 창(한 번에 읽을 수 있는 분량)은 비싸고 유한하다. 47개 스킬 본문을 전부 항상 로드하면 파산이다. 그래서 정보를 세 겹으로 나눠, 필요한 만큼만 아래로 내려가며 펼친다.

"500줄 미만" 규칙은 실제로 지켜진다 — 가장 큰 seo-audit/SKILL.md도 497줄이다. 세부는 전부 references/로 밀어냈기 때문. 본문에서 참고문서를 부르는 방식은 이렇게 링크일 뿐이다.

# ai-seo/SKILL.md 본문 안 — references를 "링크로만" 호출
For a deep dive on how each platform selects sources,
see [references/platform-ranking-factors.md](...).
...see [references/citations-vs-recommendations.md] for the
visibility ladder (retrieved → cited → mentioned → recommended).

4-2. description = "발견성 라우터" — 스킬의 운명을 가르는 한 문장

2층으로 내려갈지 말지는 순전히 1층 description이 결정한다. 그래서 이 저장소는 description을 세 요소로 정교하게 쓴다: ①무엇을 하는지 ②언제 쓰는지(사용자가 실제로 뱉을 법한 말) ③범위 경계(다른 스킬로 위임). cro의 description을 다시 뜯어보면:

4-3. 오케스트레이션 — product-marketing 루트 + 상호 참조

47개가 제각각 놀면 답이 어긋난다. 그래서 product-marketing 스킬이 뿌리 역할을 한다 — "모든 스킬이 작업 전에 먼저 읽는" 스킬로, 제품·타깃·포지셔닝 컨텍스트(.agents/product-marketing.md)를 파악한다. 그 위에서 클러스터끼리 서로를 참조한다.

예: customer-research가 뽑은 고객 언어는 copywriting·cro·competitors로 흘러가고, copywriting은 이메일이면 emails, 팝업이면 popups, 오퍼면 offers로 넘긴다. "한 스킬이 다 하려 들지 않고 명시적으로 핸드오프"하는 게 오케스트레이션의 핵심이다.

4-4. 품질 게이트 — evals.json (라우팅까지 테스트한다)

스킬이 제대로 작동하는지 어떻게 보장할까? 47개 중 45개에 evals/evals.json이 있다. 각 케이스는 프롬프트 → 기대 동작 → 어설션(검증 항목) 배열 구조다. 놀라운 건 "이 스킬이 다른 스킬로 제대로 위임하는지"까지 테스트한다는 점이다.

# skills/cro/evals/evals.json — 케이스 하나 (실제 인용)
{
  "id": 6,
  "prompt": "Our signup form has too many fields and people
             keep abandoning it halfway through. Can you help?",
  "expected_output": "Should recognize this is about signup form
             optimization ... defer to or cross-reference the signup skill",
  "assertions": [
    "Recognizes this as signup flow optimization",
    "References or defers to signup skill",
    "Does not attempt full cro analysis on a form"   # ← 월권 금지!
  ]
}

즉 이 저장소는 "cro가 signup 요청을 가로채면 실패"로 본다. 스킬의 경계 준수(월권 방지)를 자동 테스트로 지키는 것 — 다중 스킬 시스템을 건강하게 유지하는 정석이다.

5디렉토리 · 파일 구조 해부

폴더 구조 자체가 이 저장소의 설계 철학을 보여 준다 — 지식은 skills/, 실행은 tools/, 배포는 .claude-plugin/, 운영은 .github/로 관심사가 분리돼 있다.

6학습 포인트

배울 것 1 — 스킬 설계: 발견성부터 시작한다

스킬을 만들 때 초보는 본문부터 쓴다. 이 저장소는 description부터 쓴다. "사용자가 어떤 말로 이 스킬을 부를까"를 트리거 문구로 나열하고, "내가 안 할 일은 어느 스킬로 넘길까"를 명시한다. 스킬은 펼쳐지지 않으면 아무 소용이 없으므로, 발견성(description)이 1순위 설계 대상이다.

배울 것 2 — 토큰 예산: Progressive Disclosure를 몸에 익힌다

"500줄 미만 본문 + references/ 분리"는 단순한 스타일이 아니라 컨텍스트 비용을 통제하는 아키텍처다. 긴 지식은 무조건 참고문서로 빼고, 본문엔 "언제 그 문서를 열지"만 남긴다. 자기 프롬프트·스킬·문서를 쓸 때 그대로 적용할 수 있는 습관이다.

배울 것 3 — 다중 에이전트/스킬 오케스트레이션

product-marketing 루트 컨텍스트 + 클러스터 간 명시적 위임은, 여러 스킬(또는 서브에이전트)을 다룰 때의 역할 계약 패턴이다. "각자 자기 일만, 남의 일은 넘긴다"를 evals로 강제하는 것까지 세트로 배운다.

배울 것 4 — 지식과 실행의 분리 (skills ↔ tools)

skills/(무엇을·언제)와 tools/clis/(실제 API 호출)를 분리한 구조는 "판단은 지식이, 부작용은 도구가"라는 좋은 경계다. zero-dependency CLI + --dry-run + 환경변수 인증은 그 자체로 "안전한 에이전트 툴 만들기"의 모범 사례다.

배울 것 5 — 지식을 소프트웨어처럼 운영하기

2계층 버저닝(저장소 릴리스 vs 스킬별 metadata.version), CI 자동 동기화, VERSIONS.md 기반 self-update, 검증 스크립트 — 마크다운 더미도 CI·스펙·테스트로 관리하면 소프트웨어가 된다는 걸 보여 준다.

7시스템 · 실행 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크