designpaca/research/skills/03-format-specs.md

03. 포맷 스펙과 변환 어댑터 설계

작성일: 2026-08-20 목적: designpaca를 Claude Code / Codex / Cursor(+ Windsurf, VS Code Copilot)에서 동일하게 동작시키기 위한 정확한 포맷 스펙과 변환 시 주의점.

중요한 전제 변화: 2026년 8월 현재, Cursor와 Codex 모두 Agent Skills 표준을 네이티브 지원한다. 따라서 "SKILL.md를 .mdc로 변환"하는 어댑터는 더 이상 1순위가 아니다. 1순위는 하나의 SKILL.md를 세 도구가 모두 읽을 수 있는 위치에 두는 것이다. 변환 어댑터는 레거시 경로(.cursor/rules/*.mdc, AGENTS.md) 지원용으로 남는다.

---

1. Agent Skills 오픈 표준 (모든 도구의 공통 분모)

출처: https://agentskills.io/specification (직접 fetch)

1.1 디렉터리 구조

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

1.2 프론트매터 — 허용 필드 6개 전부

Field	Required	Constraints (원문)
name	Yes	"Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen."
description	Yes	"Max 1024 characters. Non-empty. Describes what the skill does and when to use it."
license	No	"License name or reference to a bundled license file."
compatibility	No	"Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.)."
metadata	No	"Arbitrary key-value mapping for additional metadata (a map from string keys to string values)."
allowed-tools	No	"Space-separated string of pre-approved tools the skill may use. (Experimental)"

1.3 name 상세 규칙 (원문)

• Must be 1-64 characters
• May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)
• Must not start or end with a hyphen (-)
• Must not contain consecutive hyphens (--)
• Must match the parent directory name

무효 예시:

name: PDF-Processing  # uppercase not allowed
name: -pdf            # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed

Anthropic 플랫폼 문서는 여기에 두 가지를 더 추가한다:

name: ... Cannot contain XML tags. Cannot contain reserved words: "anthropic", "claude" description: ... Cannot contain XML tags — platform.claude.com Skill authoring best practices

→ designpaca 결론: name: designpaca. 예약어 없음, 하이픈 없음, 소문자만. 디렉터리명도 designpaca여야 한다.

1.4 Progressive Disclosure 3계층 (원문)

1. Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
2. Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
3. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.

1.5 파일 참조 규칙 (원문)

When referencing other files in your skill, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script: scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

Anthropic이 이유를 설명한다:

Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like head -100 to preview content rather than reading entire files, resulting in incomplete information.

그리고 100줄 초과 참조 파일에는 목차를 넣으라고 한다:

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.

1.6 검증 도구

Use the skills-ref reference library to validate your skills:

skills-ref validate ./my-skill

→ designpaca는 이 검증기를 CI에 걸어야 한다.

---

2. Claude Code SKILL.md

출처: https://code.claude.com/docs/en/skills (직접 fetch)

2.1 설치 위치와 우선순위

Location	Path	Applies to
Enterprise	managed settings 참조	조직 전체
Personal	~/.claude/skills/<skill-name>/SKILL.md	모든 프로젝트
Project	.claude/skills/<skill-name>/SKILL.md	해당 프로젝트만
Plugin	<plugin>/skills/<skill-name>/SKILL.md	플러그인 활성 범위

이름 충돌 해소 순서 (원문):

• Across levels, enterprise overrides personal, and personal overrides project.
• A skill at any of these levels also overrides a bundled skill with the same name, but not the bundled skill's aliases.
• Plugin skills use a plugin-name:skill-name namespace, so they can't conflict with other levels.
• If you have files in .claude/commands/, ... if a skill and a command share the same name, the skill takes precedence.

중첩 스킬 (모노레포용):

Skills also load from nested .claude/skills/ directories below your working directory. ... The nested one appears under a directory-qualified name, apps/web:deploy. Skills in nested .claude/skills/ directories below your starting directory aren't loaded at startup. They load the first time Claude reads or edits a file inside that subdirectory.

심링크 지원 (중요):

A <skill-name> entry in the enterprise, personal, or project locations can be a symlink to a directory elsewhere on disk. Claude Code follows the symlink and reads SKILL.md from the target directory, and if the same target is reachable from more than one location, Claude Code loads the skill once.

→ 이 사용자의 환경이 이미 이 방식이다. ~/.claude/skills/design-taste-frontend → ~/.agents/skills/design-taste-frontend. designpaca도 ~/.agents/skills/designpaca/를 정본으로 두고 심링크하는 것이 옳다.

2.2 프론트매터 전체 필드 (Claude Code 확장 포함)

All fields are optional. Only description is recommended so Claude knows when to use the skill. Boolean fields accept yes, no, on, off, 1, and 0 in any letter case, in addition to true and false.

Field	표준?	설명 (요약)
name	O	스킬 목록 표시명. 개인/프로젝트 스킬에서는 커맨드명을 바꾸지 못한다 (디렉터리명이 커맨드명). 플러그인 스킬에서만 마지막 세그먼트를 결정
description	O	무엇을 하고 언제 쓰는지. "the combined description and when_to_use text is truncated at 1,536 characters in the skill listing"
when_to_use	X	description에 덧붙는 추가 트리거 문구. 1,536자 상한에 함께 포함됨
argument-hint	X	자동완성 힌트. 예: [issue-number]
arguments	X	$name 치환용 명명 위치 인자
disable-model-invocation	X	true면 Claude가 자동 로드 못 함. "Description not in context"
user-invocable	X	false면 / 메뉴에서 숨김. Claude만 호출
allowed-tools	O(실험)	해당 턴 동안 승인 없이 쓸 도구. "The grant clears when you send your next message"
disallowed-tools	X	스킬 활성 중 제거할 도구
model	X	스킬 활성 시 모델 오버라이드
effort	X	low/medium/high/xhigh/max
context	X	fork → 포크된 서브에이전트에서 실행
agent	X	context: fork 시 서브에이전트 타입
background	X	context: fork 시 백그라운드 여부 (기본 true)
hooks	X	스킬 호출 시 등록되는 훅
paths	X	글롭 패턴. "Claude loads the skill automatically only when working with files matching the patterns"
shell	X	bash(기본) 또는 powershell
metadata	O	자유 형식 YAML 맵
license	O	Claude Code는 받아들이지만 아무 동작 안 함
compatibility	O	최대 500자. Claude Code는 받아들이지만 아무 동작 안 함

2.3 도구 밖으로 나갈 때의 하드 에러 (가장 중요한 제약)

원문:

Claude Code accepts every field in the table above. Outside Claude Code, you can use only the fields in the Agent Skills spec:

Distribution path	Frontmatter fields you can use
Claude Code skills at any level, including plugin skills	Every field in the table above
claude.ai skill uploads, the Skills API, and packaging with package_skill.py	name, description, license, compatibility, metadata, allowed-tools

If you include any field the spec doesn't allow, packaging or upload fails with a hard error instead of ignoring the field:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

→ designpaca 결정: 프론트매터는 name + description만 쓴다. 크로스툴 휴대성이 목표이므로 확장 필드는 전부 배제. 이는 로컬 커뮤니티 스킬 13개가 이미 도달한 결론과 같다.

(참고: 로컬 graphify의 trigger: /graphify는 스펙에 없는 필드다. Claude Code는 무시하지만 claude.ai 업로드/패키징 시 위 에러가 난다. designpaca는 이 패턴을 복제하면 안 된다.)

2.4 커맨드명이 결정되는 규칙

Skill location	Command name source	Example
~/.claude/skills/ 또는 .claude/skills/ 아래 디렉터리	디렉터리명	.claude/skills/deploy-staging/SKILL.md → /deploy-staging
중첩 .claude/skills/ (이름 충돌 시)	작업 디렉터리 상대 경로 + 스킬 디렉터리명	apps/web/.claude/skills/deploy/ → /apps/web:deploy
.claude/commands/ 아래 파일	확장자 뺀 파일명	.claude/commands/deploy.md → /deploy
플러그인 skills/ 하위	프론트매터 name 또는 디렉터리명 + 플러그인 네임스페이스	my-plugin/skills/review/ → /my-plugin:review
플러그인 루트 SKILL.md	프론트매터 name (없으면 플러그인 디렉터리명)	name: review → /my-plugin:review

2.5 컨텍스트 수명 (설계 제약)

원문 그대로:

When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session. ... Claude Code does not re-read the skill file on later turns.

When Claude re-invokes a skill whose rendered content is identical to the copy already in context, Claude Code adds a short note that the skill is already loaded rather than a second copy.

Auto-compaction carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens.

If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches. Strengthen the skill's description and instructions so the model keeps preferring it, or use hooks to enforce behavior deterministically.

→ 설계 결론 3개

1. SKILL.md 본문은 5,000토큰(약 500줄) 이내여야 컴팩션 후에도 온전히 살아남는다.
2. 가장 중요한 규칙은 파일 앞부분에 있어야 한다.
3. 여러 스킬을 쓰는 세션에서는 25,000토큰을 나눠 쓰므로, 큰 스킬은 다른 스킬을 밀어낸다.

2.6 스킬 목록 예산 (트리거 실패의 숨은 원인)

원문:

Claude Code loads a listing of skill names and descriptions into context so Claude knows what's available. The listing always contains every skill name, but if you have many skills, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window.

Run /doctor for an estimate of the listing's context cost and its biggest contributors. To raise the budget, set the skillListingBudgetFraction setting (e.g. 0.02 = 2%) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

→ description을 짧게 유지해야 하는 진짜 이유. 이 사용자 환경에는 스킬이 40개 이상 있다. 620자 description(imagegen-frontend-web)은 잘려나갈 위험이 크다. 200~350자를 권장.

2.7 프론트매터 파싱 실패 시

If the frontmatter YAML is malformed, Claude Code loads the skill body with empty metadata, so /skill-name still works but Claude has no description to match against. Run with --debug to see the parse error.

→ 조용히 실패한다. 검증기를 돌려야 하는 이유.

2.8 커스텀 커맨드와의 통합

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Files in .claude/commands/ support the same frontmatter, except name and paths, which Claude Code ignores in a command file.

---

3. Codex (OpenAI) — 두 가지 경로

Codex는 AGENTS.md(항상 로드되는 컨텍스트)와 Agent Skills(온디맨드 로드) 둘 다 지원한다. 이 둘은 역할이 다르다.

3.1 Codex Agent Skills

출처: https://learn.chatgpt.com/docs/build-skills (developers.openai.com/codex/skills 에서 308 리다이렉트)

스캔 위치 (우선순위 순, 원문 기반)

범위	경로
Repository	.agents/skills — 현재 작업 디렉터리와 상위 폴더들을 repo root까지
User	$HOME/.agents/skills
Admin	/etc/codex/skills
System	OpenAI 번들

"If two skills share the same name, Codex doesn't merge them; both can appear in skill selectors."

프론트매터

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Codex 문서의 description 지침이 특히 명확하다: "when this skill should and should not trigger" — 배제 조건을 스펙 수준에서 요구한다.

컨텍스트 예산

Skills use "progressive disclosure to manage context efficiently." The initial skills list uses at most "2% of the model's context window, or 8,000 characters when the context window is unknown", though full SKILL.md instructions load when a skill is selected.

→ 중대한 발견: Codex의 스킬 스캔 경로가 .agents/skills와 $HOME/.agents/skills다. 이 사용자 머신의 C:\Users\encep\.agents\skills\가 정확히 그 경로다. 즉 현재 설치된 디자인 스킬들은 Codex와 Cursor 양쪽에서 동시에 인식되도록 배치된 것이다.

3.2 Codex AGENTS.md

출처: https://agents.md/ (직접 fetch)

포맷 (원문)

No required fields. "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." 프론트매터를 쓰지 않는다.

중첩과 우선순위 (원문)

"The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything."

Codex 구현의 3계층 (검색 결과 종합, 다수 소스 일치):

1. ~/.codex/AGENTS.override.md (최고 우선순위 글로벌 오버라이드)
2. ~/.codex/AGENTS.md
3. 프로젝트: git root부터 현재 디렉터리까지 걸어가며 각 디렉터리의 AGENTS.override.md 또는 AGENTS.md

• 병합 순서: root부터 아래로 연결(concatenate), 가까운 파일이 앞의 것을 오버라이드
• 기본 크기 상한 32 KiB에서 중단

권장 섹션 (원문)

Project overview / Build and test commands / Code style guidelines / Testing instructions / Security considerations / Commit message/PR guidelines / Deployment steps

성격

"Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions"

지원 도구: OpenAI Codex, Google Jules, Factory, Aider, Zed, VS Code, Devin, GitHub Copilot, Cursor, Gemini CLI 외 15개 이상. 6만 개 이상의 오픈소스 프로젝트에서 사용.

→ AGENTS.md는 스킬이 아니다. 항상 로드된다. designpaca 전체를 AGENTS.md에 넣으면 모든 대화에서 토큰을 먹는다. AGENTS.md에는 포인터만 두고, 본체는 .agents/skills/designpaca/에 두는 것이 옳다.

---

4. Cursor — 두 가지 경로

4.1 Cursor Agent Skills (신규, 권장)

출처: https://cursor.com/docs/context/skills (직접 fetch)

로드 위치 4곳

• 프로젝트: .agents/skills/ 와 .cursor/skills/
• 사용자: ~/.agents/skills/ 와 ~/.cursor/skills/

Cursor "walks the skills root recursively and picks up any SKILL.md it finds."

프론트매터

필수:

• name — "Skill identifier. Lowercase letters, numbers, and hyphens only."
• description — "Describes what the skill does and when to use it."

선택 (Cursor 확장):

• paths — 글롭 패턴으로 스코프 제한
• disable-model-invocation — true면 /skill-name으로만 호출
• icon — "Icon shown on the badge when the skill is used as a Custom Mode"
• color — default, green, cyan, blue, purple, magenta, orange, yellow, red, brand
• metadata

"Skills in nested project directories are automatically scoped to files inside that directory."

→ ~/.agents/skills/designpaca/ 하나가 Cursor와 Codex 양쪽에서 인식된다. 이것이 크로스툴 배포의 정답이다.

4.2 Cursor Rules (.mdc) — 레거시 경로

출처: https://cursor.com/docs/rules (직접 fetch)

파일 위치

.cursor/rules/
  react-patterns.mdc
  frontend/
    components.mdc

프론트매터 필드는 정확히 3개 (문서에 명시된 것 전부):

Field	Type	설명 (원문)
alwaysApply	boolean	"Apply to every chat session"
description	string	"Helps Agent decide relevance; omitting it restricts to manual @-mention only"
globs	string	"File pattern(s) for auto-attachment; supports comma-separated patterns"

"No other frontmatter fields are specified in the documentation."

4가지 규칙 타입

Type	조건	동작
Always Apply	alwaysApply: true	모든 채팅 세션에 적용
Apply Intelligently	description 있음, globs 없음	에이전트가 관련성 판단
Apply to Specific Files	globs 있음	"Auto-attached when a matching file is in context"
Apply Manually	description·globs 둘 다 없음	"@-mention in chat (e.g., @my-rule)"

공식 베스트 프랙티스 (원문)

• "Keep rules under 500 lines"
• "Split large rules into multiple, composable rules"
• Reference files via @filename.ts rather than copying content
• Avoid duplicating style guides; use linters instead

중요한 스코프 제약

Rules apply only to Agent (Chat), not Cursor Tab or Inline Edit (Cmd/Ctrl+K).

Cursor의 AGENTS.md 지원

"AGENTS.md is a simple markdown file for defining agent instructions" without frontmatter. Supports nested placement: "You can place AGENTS.md files in any subdirectory" with hierarchical precedence.

---

5. Windsurf / Cascade Rules

출처: https://docs.windsurf.com/windsurf/cascade/memories → 307 리다이렉트 → https://docs.devin.ai/desktop/cascade/memories (직접 fetch)

주의: Windsurf 문서가 Devin 문서로 리다이렉트된다(Cognition의 Windsurf 인수 이후 통합). 아래는 리다이렉트된 최신 문서 기준이므로, .windsurf/ 경로는 "legacy"로 표기되어 있다.

5.1 파일 위치 3계층

범위	경로
Global	~/.codeium/windsurf/memories/global_rules.md (단일 파일, 항상 활성)
Workspace	.devin/rules/*.md (권장) 또는 .windsurf/rules/*.md (legacy), 그리고 legacy .windsurfrules
System (Enterprise)	macOS /Library/Application Support/Devin/rules/, Linux /etc/devin/rules/, Windows C:\ProgramData\Devin\rules\

5.2 문자 수 제한 (하드)

• Global rules: "Limited to 6,000 characters"
• Workspace rules: "Limited to 12,000 characters per file"

이것이 다른 어떤 포맷보다 강한 제약이다. designpaca 본문이 12,000자를 넘으면 Windsurf에서는 반드시 분할해야 한다.

5.3 활성화 모드 (trigger: 필드)

Mode	Trigger 값	동작 (원문)
Always On	always_on	"Full rule content is included in the system prompt on every message"
Model Decision	model_decision	"Description shown always; full content retrieved when Cascade deems relevant"
Glob	glob	"Applied when files matching specified patterns are accessed"
Manual	manual	"Activated only via @rule-name mention in input"

5.4 프론트매터 예시 (원문)

---
trigger: glob
globs: **/*.test.ts
---

All test files must use `describe`/`it` blocks and mock external API calls.

Global and root-level files don't require frontmatter and remain perpetually active.

주의: Windsurf의 trigger:는 값이 always_on/model_decision/glob/manual 중 하나다. Claude Code SKILL.md의 슬래시 커맨드 이름을 넣는 필드가 아니다. (graphify의 trigger: /graphify와 혼동 금지 — 서로 다른 스펙의 같은 이름 필드다.)

---

6. VS Code / GitHub Copilot Agent Skills

출처: https://code.visualstudio.com/docs/copilot/customization/agent-skills (직접 fetch)

로드 위치

• 프로젝트: .github/skills/, .claude/skills/, .agents/skills/
• 개인: ~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/
• 추가 경로: chat.agentSkillsLocations 설정

프론트매터

• name (필수): "A unique identifier for the skill. Only lowercase letters, numbers, and hyphens are allowed"
• description (필수): "A description of what the skill does and when to use it"
• argument-hint (선택)
• user-invocable (선택)
• disable-model-invocation (선택)
• context (선택, 실험): fork

custom instructions와의 차이 (원문)

skills are "task-specific, loaded on-demand" and work across multiple tools, while custom instructions are "Always applied (or via glob patterns)" and limited to "VS Code and GitHub.com only."

---

7. 포맷 비교 통합표

항목	Claude Code SKILL.md	Agent Skills 표준	Codex AGENTS.md	Cursor .mdc	Windsurf rules
파일 위치	~/.claude/skills/<n>/SKILL.md, .claude/skills/<n>/SKILL.md	<n>/SKILL.md	리포 루트 + 각 하위 디렉터리 AGENTS.md	.cursor/rules/*.mdc	~/.codeium/windsurf/memories/global_rules.md, .windsurf/rules/*.md
프론트매터	YAML, 22개 필드	YAML, 6개 필드	없음	YAML, 3개 필드	YAML, trigger + globs
필수 필드	없음 (description 권장)	name, description	없음	없음	없음
로드 시점	온디맨드 (description 매칭 or /이름)	온디맨드	항상	4모드 (always/글롭/설명매칭/수동)	4모드 (always_on/glob/model_decision/manual)
크기 제한	본문 500줄 권장, 컴팩션 시 5K 토큰 생존	본문 500줄 / 5,000토큰 권장	32 KiB 병합 상한	500줄 권장	6,000자(글로벌) / 12,000자(워크스페이스) 하드
description 상한	1,536자(+when_to_use 합산), 목록 예산 1%	1,024자	N/A	미명시	미명시
참조 파일	O (references/, scripts/, assets/)	O	X (별도 AGENTS.md 중첩으로 대체)	@filename 참조	X
스크립트 실행	O	O	X	X	X
네임스페이스	플러그인 plugin:skill, 중첩 dir:skill	X	경로 기반	X	X
심링크	O (중복 로드 방지 포함)	구현 의존	N/A	미명시	미명시

---

8. designpaca 배포 전략 (권장안)

8.1 단일 정본 + 심링크 (Tier 1)

정본 위치: ~/.agents/skills/designpaca/

이 한 곳이 다음 세 도구에서 변환 없이 인식된다:

• Cursor: ~/.agents/skills/ 를 직접 스캔
• Codex: $HOME/.agents/skills 를 직접 스캔
• VS Code Copilot: ~/.agents/skills/ 를 직접 스캔

Claude Code용 심링크:

# Git Bash / WSL
ln -s ~/.agents/skills/designpaca ~/.claude/skills/designpaca

# Windows PowerShell (관리자 또는 개발자 모드)
New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills\designpaca" -Target "$HOME\.agents\skills\designpaca"

Claude Code 문서가 이 방식을 명시적으로 지원한다:

A <skill-name> entry ... can be a symlink to a directory elsewhere on disk. Claude Code follows the symlink and reads SKILL.md from the target directory.

프로젝트 스코프: 리포에 .agents/skills/designpaca/를 두면 Cursor·Codex·Copilot이 전부 읽는다. Claude Code용으로 .claude/skills/designpaca 심링크를 추가한다.

8.2 파일 구조 (권장)

designpaca/
├── SKILL.md                          # 400~480줄. 절차 + 인덱스 + 핵심 게이트
├── references/
│   ├── anti-patterns.md              # AI 텔 카탈로그 (무엇/왜/대신)
│   ├── slop-gates.md                 # 출력 후 예/아니오 게이트 목록
│   ├── typography.md                 # 폰트 페어링, 스케일, 세리프 규율
│   ├── color.md                      # 팔레트 규칙, 금지 hex 패밀리, 대비
│   ├── layout.md                     # 매크로구조 인덱스 + 섹션 리듬
│   ├── motion.md                     # 이징, 스크롤, reduced-motion
│   ├── copy.md                       # 카피 규율 + 자가 감사 목록
│   ├── responsive.md                 # 브레이크포인트, 모바일 붕괴, 실무 버그
│   ├── design-systems.md             # 공식 DS 매핑 + 설치 명령 + 문서 링크
│   ├── redesign.md                   # 리디자인 프로토콜 (감사/보존/레버)
│   └── design-md-template.md         # 산출용 design.md 템플릿
├── assets/
│   └── themes/                       # 테마별 개별 파일 (인덱스-후-선택)
└── scripts/
    └── check_contrast.(js|py)        # 대비/팔레트 검증기 (선택)

모든 references 파일은 SKILL.md에서 1단계 링크로만 참조. 참조 파일끼리 서로 링크하지 않는다.

8.3 프론트매터 (확정안)

---
name: designpaca
description: <용도 + 트리거 문구 + 배제 조건. 200~350자. 3인칭.>
---

확장 필드를 쓰지 않는 이유:

1. claude.ai 업로드/패키징 시 하드 에러
2. Cursor·Codex·Copilot이 지원하는 필드 집합이 서로 다름
3. 로컬 커뮤니티 스킬 13개가 이미 같은 결론에 도달

8.4 레거시 어댑터 (Tier 2, 필요 시)

Agent Skills를 지원하지 않는 경로용 변환. 자동 생성 스크립트로 만들고 손으로 관리하지 않는다.

(a) → Cursor .mdc 규칙

.cursor/rules/designpaca.mdc

---
description: Use when building or reshaping web UI - landing pages, portfolios, marketing sites, product pages, or redesigns - and the visual result matters.
alwaysApply: false
---

<SKILL.md 본문>

<!-- references/ 는 @-참조로 대체 -->
See @.cursor/rules/designpaca-anti-patterns.mdc for the full anti-pattern catalogue.

변환 시 주의점

1. name 필드를 제거한다. .mdc는 description/globs/alwaysApply 3개만 인식. 다른 필드는 문서화되지 않았다.
2. alwaysApply: true를 쓰지 마라. Cursor 문서: "Use sparingly, this is your global config, not your per-feature config." 디자인 스킬은 항상 켜져 있으면 안 된다.
3. globs를 쓸지 말지: **/*.{tsx,jsx,vue,svelte,astro,html,css} 로 걸면 파일 컨텍스트 기반 자동 첨부가 되지만, "새 랜딩 만들어줘"처럼 파일이 아직 없는 경우 발동하지 않는다. 디자인 스킬은 description만 두는 "Apply Intelligently" 모드가 맞다.
4. 참조 파일 링크를 @경로로 바꾼다. .mdc는 references/*.md 상대 경로를 읽지 않는다.
5. 500줄 상한 준수. 넘으면 여러 .mdc로 쪼개고 서로 @로 연결.
6. Tab/Inline Edit에는 적용 안 됨을 문서에 명시.

(b) → Windsurf 규칙

.windsurf/rules/designpaca.md   (또는 .devin/rules/designpaca.md)

---
trigger: model_decision
description: Use when building or reshaping web UI ...
---

<SKILL.md 본문 — 12,000자 이내로 압축>

변환 시 주의점

1. 12,000자 하드 상한. SKILL.md가 이를 넘으면 반드시 분할. 파일 여러 개로 쪼개고 각각 trigger: model_decision.
2. trigger: model_decision을 쓴다. always_on은 6,000자 글로벌 규칙에만.
3. references/ 개념이 없다. 핵심만 남기고 나머지는 버리거나 별도 규칙 파일로.
4. name 필드 없음.

(c) → AGENTS.md

전체를 넣지 마라. AGENTS.md는 항상 로드되므로 디자인 스킬 본문을 넣으면 모든 대화에서 비용이 든다. 포인터만 넣는다:

## Design work

When building or changing UI in this repo, load the `designpaca` skill
(`.agents/skills/designpaca/SKILL.md`) before writing any markup or styles.
The project's locked design system lives at `design.md` at the repo root;
it overrides the skill's defaults.

변환 시 주의점

1. 프론트매터가 없다. YAML 블록을 넣으면 그냥 본문 텍스트로 읽힌다.
2. 32 KiB 병합 상한이 있으므로 짧게.
3. 중첩 시 가까운 파일이 이긴다. 모노레포에서 패키지별로 다른 디자인 지시를 줄 수 있다.

8.5 변환 시 절대 하면 안 되는 것

실수	결과
SKILL.md에 trigger: /designpaca 넣기	claude.ai 업로드/패키징 하드 에러. Windsurf trigger와 의미 충돌
.mdc에 name: 남기기	문서화되지 않은 필드. 무시되거나 파싱 실패
.mdc에서 references/x.md 상대 링크 유지	Cursor가 읽지 못함. @ 참조로 바꿔야 함
Windsurf 규칙에 alwaysApply 넣기	Cursor 필드다. Windsurf는 trigger를 쓴다
AGENTS.md에 YAML 프론트매터 넣기	본문으로 렌더링됨
SKILL.md name을 디렉터리명과 다르게	스펙 위반 ("Must match the parent directory name"). 개인/프로젝트 스킬에서는 어차피 디렉터리명이 커맨드가 되므로 혼란만 유발
description에 XML 태그	Anthropic 스펙 위반
description 1,024자 초과	Agent Skills 스펙 위반 (Claude Code는 1,536까지 받지만 표준은 1,024)
참조 파일이 다른 참조 파일을 링크	부분 읽기(head -100)로 정보 유실
참조 파일 100줄 초과인데 목차 없음	부분 읽기 시 전체 범위를 모름

8.6 검증 체크리스트

배포 전 확인:

• name이 소문자+숫자+하이픈만, 64자 이내, 연속 하이픈 없음, 디렉터리명과 일치
• description이 1,024자 이내, 3인칭, 용도+트리거+배제 3요소
• 프론트매터에 표준 6필드 외 필드 없음
• SKILL.md 본문 500줄 이내
• 가장 중요한 규칙이 앞 100줄 안에 있음
• 모든 참조 파일이 SKILL.md에서 1단계로 링크됨
• 참조 파일 중 100줄 넘는 것에 목차 있음
• 파일 경로에 백슬래시 없음 (전부 /)
• skills-ref validate ./designpaca 통과
• Cursor .mdc 변환본이 500줄 이내
• Windsurf 변환본이 12,000자 이내
• Claude Code에서 /doctor로 스킬 목록 예산 확인

---

9. 확인 못한 것

• Windsurf 공식 문서 원본: docs.windsurf.com이 docs.devin.ai로 리다이렉트되어, 리다이렉트된 문서 기준으로 정리했다. .windsurfrules 단일 파일 레거시 포맷의 정확한 상한과 파싱 규칙은 리다이렉트 문서에 "legacy"로만 표기되어 있고 상세 스펙은 확인하지 못했다.
• Cursor .mdc의 미문서화 필드: 커뮤니티 문서들이 alwaysApply/description/globs 외 필드를 언급하기도 하지만, 공식 문서는 "No other frontmatter fields are specified"라고 한다. 미문서화 필드는 사용하지 않는 것이 안전하다.
• skills-ref CLI의 실제 검증 항목 전체: 저장소 URL만 확인했고 실행해보지 않았다.
• Cursor Skills와 .mdc Rules가 동시에 있을 때의 우선순위: 공식 문서에 명시되어 있지 않다.