Communitygithub.com

zhcmeng/shared-skills

当用户要求把英文文档翻译成中文、生成 `-中文版` 后缀的中文版文件、或要求「一比一翻译 / 完整翻译 / 中文化」某个英文 Markdown 文件(尤其 SKILL.md、技术文档)时使用。触发词:翻译、中文化、中文版、zh-CN、translate、一比一。

shared-skills란 무엇인가요?

이 스킬은 AI 에이전트(예: Claude Code, Cursor)가 영문 Markdown 문서(특히 SKILL.md 및 기술 문서)를 정확히 일대일로 중문으로 번역하여, 원본 파일과 동일한 디렉토리에 `-中文版` 접미사를 가진 새 파일을 생성하도록 안내합니다. 핵심은 "일대일" 규칙입니다. 즉, 제목 수준, 단락, 목록, 표, 코드 블록, 다이어그램이 원본과 완전히 동일하게 유지되며, 내용의 추가/삭제, 단락 병합/분할, 의역이 금지됩니다. 이 스킬은 원본 에이전트가 번역을 직접 수행하지 않고, 각 파일에 대해 전용 하위 에이전트(general-purpose, model: "haiku")를 병렬로 파견하여 처리함으로써 상위 컨텍스트의 오염과 길이 증가를 방지합니다. 사용자는 $ARGUMENTS를 통해 단일 파일, 디렉토리 또는 스킬 이름을 전달할 수 있으며, 하위 에이전트가 번역을 완료하면 원본 에이전트가 diff 검증을 통해 일대일 규칙 준수 여부를 확인하고 결과만 보고합니다. 디렉토리 모드에서는 기본적으로 이미 `-中文版` 파일이 있는 문서를 건너뛰어 중복 번역을 방지합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zhcmeng/shared-skills/tree/HEAD/plugin/skills/translate-docs

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

영문 문서 번역

개요

영문 Markdown 문서를 일대일로 중문으로 번역하여, 동일한 디렉토리에 X-中文版.md 파일(X.md → X-中文版.md)을 생성합니다. 핵심은 일대일입니다: 제목 수준, 단락, 목록, 표, 코드 블록, 다이어그램이 완전히 일치하며, 내용을 추가/삭제하거나 단락을 병합/분할하거나 의역하여 재구성하지 않습니다.

번역 과정은 전적으로 하위 에이전트에서 수행됩니다. 본 에이전트는 대상 파일을 찾고, 하위 에이전트를 파견하며, 결과를 검증하고 사용자에게 보고하는 역할만 담당합니다. 원문을 읽거나, 직접 번역하거나, 본 에이전트의 컨텍스트를 소모하지 않습니다.

번역 규칙 (일대일 규범)

다음 규칙은 하위 에이전트가 수행해야 할 규범이자, 본 에이전트가 결과물을 검증하는 기준입니다:

  1. 산출물: 영문 X.md → 동일 디렉토리의 X-中文版.md.
  2. frontmatter: name:은 원본 영문 유지; description:은 중문으로 번역; 나머지 필드(있는 경우)는 값에 따라 번역.
  3. 설명문: frontmatter 이후, 본문 제목 전에 한 줄의 인용 블록을 삽입: > 📝 본 문서는 \<원본 파일명>`의 중문 번역입니다. 영문 원본을 기준으로 하며, 차이가 있을 경우 원본을 우선합니다.만약 출처 버전을 알고 있다면번역 출처: <프로젝트> v<버전>`으로 작성.
  4. 코드 블록 미번역: 모든 fenced code block(, dot, mermaid, bash` 등)의 내용은 원본 그대로 유지하며, 번역, 들여쓰기 변경, 행 삭제를 하지 않음.
  5. 인라인 코드 유지: 백틱 내부 내용(스킬명, 파일 경로, 명령어, 식별자, URL)은 영문 그대로 유지.
  6. 용어 최초 표기: 기술 용어가 처음 등장할 때는 「중문(English)」 형태로 표기, 이후에는 중문만 사용 가능.
  7. 표: 표 헤더와 텍스트 셀은 번역; 순수 코드/경로/식별자 셀은 유지.
  8. 링크: URL은 유지하고, 링크 텍스트는 번역.
  9. 각주: 각주 정의([^n]: url)는 URL 유지, 설명문 번역; 본문 내 [^n] 참조는 그대로 유지.
  10. 줄바꿈: 영문 원본 파일의 하드 줄바꿈은 중문에서 유지하지 않음(중문 단락 내 줄바꿈 없음); 단락 경계와 빈 줄은 유지.

워크플로우

단일 문서든 디렉토리든, 항상 하위 에이전트를 파견하여 번역하며, 본 에이전트는 직접 번역하지 않습니다.

  1. 대상 찾기: $ARGUMENTS를 가져옵니다. 이 값은 번역할 파일 경로, 디렉토리, 또는 스킬명(예: superpowers:brainstorming → 해당 SKILL.md 파일의 경로를 찾음)입니다. $ARGUMENTS가 비어 있으면 호출 시 대상을 제공하지 않은 것이므로 오류를 보고하고 즉시 종료하며, 추측하지 않습니다.
  2. 번역 대상 파일 결정:
    • 단일 문서 → 해당 파일 1개.
    • 디렉토리 → 디렉토리 내 모든 .md 파일을 나열하고, 이미 대응하는 -中文版.md 파일이 있는 경우 제외(건너뛰고, 중복 번역하지 않음).
  3. 병렬 하위 에이전트 파견: 각 번역 대상 파일에 대해 general-purpose 하위 에이전트를 하나씩 파견합니다. model: "haiku"를 사용하며, 프롬프트는 아래 템플릿에 대상 파일 경로를 채워 넣습니다. 모든 하위 에이전트를 한 번의 메시지로 동시에 파견합니다(여러 Agent 호출을 병렬로 실행).
  4. 검증 및 보고: 하위 에이전트가 반환되면, 본 에이전트는 각 산출물에 대해 diff 검증(위 규칙과 대조)을 수행하여 일대일 규칙을 준수했는지 확인합니다. 사용자에게는 결과만 보고(성공/실패/누락 목록)하고, 번역 과정은 보고하지 않습니다.

하위 에이전트 프롬프트 템플릿

general-purpose 하위 에이전트는 본 스킬의 규칙을 상속받지 않으므로, 프롬프트는 자체적으로 완결되어야 합니다:

당신은 영문 문서 번역 에이전트입니다. 지정된 영문 Markdown 파일을 일대일로 중문으로 번역하여, 동일한 디렉토리에 `X-中文版.md` 파일(`X.md` → `X-中文版.md`)을 생성하세요.

규칙:
- 일대일: 제목 수준, 단락, 목록, 표, 코드 블록, 다이어그램이 완전히 일치해야 하며, 내용을 추가/삭제하거나 단락을 병합/분할하거나 의역하여 재구성하지 않습니다.
- frontmatter: name은 영문 유지, description은 중문으로 번역.
- frontmatter 후, 본문 제목 전에 한 줄의 인용 블록 삽입: > 📝 본 문서는 <원본 파일명>의 중문 번역입니다. 영문 원본을 기준으로 하며, 차이가 있을 경우 원본을 우선합니다.
- 코드 블록 미번역: 모든 fenced code block(dot/mermaid 포함)의 내용은 원본 그대로 유지.
- 인라인 코드는 영문 유지(스킬명, 파일 경로, 명령어, URL).
- 용어 최초 표기 시 「중문(English)」 형태 사용.
- 표: 텍스트 셀은 번역, 코드/경로 셀은 유지; 링크: URL 유지, 텍스트 번역; 각주: URL 유지, 설명문 번역.
- 중문 단락 내 하드 줄바꿈 금지.

대상 파일: <절대 경로>
이 파일 하나만 번역하고, 작업 완료 후 한 줄 요약(파일명 + 성공/실패)을 반환하세요.

제약 사항

  • 일대일은 엄격한 요구사항입니다: 내용을 추가/삭제하지 않고, 단락을 병합/분할하지 않으며, 의역하여 재구성하지 않습니다.
  • 코드 블록은 절대 번역하지 않습니다(dot/mermaid 다이어그램 포함, 다이어그램 내 노드 레이블도 영문 유지).
  • 영문 파일명/경로/스킬명/명령어는 모두 그대로 유지합니다.
  • 번역 과정은 항상 하위 에이전트에서 수행되며, 본 에이전트는 원문을 읽거나 직접 번역하지 않습니다.
  • 번역 대상은 $ARGUMENTS로부터 전달받습니다. 만약 값이 스킬명(예: superpowers:brainstorming)인 경우, 본 에이전트가 해당 스킬의 SKILL.md 파일 경로를 스스로 찾되, 로컬 절대 경로를 가정하지 않습니다.
  • 디렉토리 모드에서는 기본적으로 이미 -中文版.md 파일이 있는 문서는 건너뜁니다. 사용자가 명시적으로 요청할 때만 덮어쓰고 재번역합니다.

관련 스킬