에이전트 스킬

RAWP 문서 전문가

프로젝트 루트의 .rawp-version.yaml 과 RAWP 문서 엔드포인트를 기준으로 정확한 spec, version, locale 문서를 찾고 필요한 범위만 읽는다.

Goal

이 스킬의 목적은 현재 프로젝트가 기준으로 삼는 RAWP 문서를 정확히 찾고, 필요한 범위만 읽어 답변하는 것이다.

항상 다음 목표를 우선한다.

  • 현재 프로젝트의 실제 문서 버전 사용
  • 사람용 HTML이 아닌 기계친화적 엔드포인트 사용
  • 전체 문서 대신 필요한 섹션만 읽기
  • spec, version, locale 해석 근거를 명확히 유지

Docs Origin

문서 origin 은 항상 다음 값을 사용한다.

  • https://rawp-docs.crystall.in

기본 엔드포인트:

  • https://rawp-docs.crystall.in/ko/agent-map.json
  • https://rawp-docs.crystall.in/en/agent-map.json
  • https://rawp-docs.crystall.in/ko/spec-index.json
  • https://rawp-docs.crystall.in/en/spec-index.json
  • https://rawp-docs.crystall.in/ko/for-agents.md
  • https://rawp-docs.crystall.in/en/for-agents.md

Project Contract

현재 프로젝트의 RAWP 문서 버전은 프로젝트 루트의 .rawp-version.yaml 로 관리한다.

규칙:

  • 허용 위치는 <project-root>/.rawp-version.yaml 하나뿐이다.
  • 하위 디렉터리의 .rawp-version.yaml 은 무시한다.
  • 상위 디렉터리의 .rawp-version.yaml 도 무시한다.
  • 먼저 프로젝트 루트를 확정한 뒤 그 위치만 확인한다.

프로젝트 루트 판정:

  1. Git 저장소면 git rev-parse --show-toplevel
  2. Git 정보가 없으면 현재 워크스페이스 루트

.rawp-version.yaml 파일 규격:

locale: <optional string>
defaultSpec: <optional string>
specs:
  <spec-name>: <semver string>

허용 top-level 키:

  • locale
  • defaultSpec
  • specs

필드 규칙:

  • 루트는 YAML object 여야 한다.
  • specs 는 필수다.
  • specs 는 object 여야 한다.
  • specs 에는 최소 1개 이상의 spec version 이 있어야 한다.
  • 허용 spec 이름은 rawp, rawp-crs, rawp-dps 뿐이다.
  • version 값은 v 없는 semver 문자열이어야 한다. 예: 1.0.1
  • locale 이 있으면 ko 또는 en 이어야 한다.
  • defaultSpec 이 있으면 허용 spec 이름 중 하나여야 한다.
  • defaultSpec 이 있으면 반드시 specs 에도 같은 spec 키가 있어야 한다.

파일이 위 규격을 벗어나면:

  • 잘못된 키로부터 값을 추론하지 않는다.
  • 유효하지 않은 필드는 무시한다.
  • 필요한 값을 더 이상 결정할 수 없으면 기본값과 spec-index.json 으로 fallback 한다.

권장 예시:

locale: ko
defaultSpec: rawp
specs:
  rawp: 1.0.1
  rawp-crs: 1.0.0
  rawp-dps: 1.0.0

최소 유효 예시:

specs:
  rawp: 1.0.1

다중 spec 예시:

locale: en
defaultSpec: rawp-dps
specs:
  rawp: 1.0.1
  rawp-crs: 1.0.0
  rawp-dps: 1.0.0

해석 규칙:

  • locale 은 선택 사항
  • defaultSpec 은 선택 사항이며 없으면 rawp
  • specs 는 spec 별 version 매핑
  • specs 에 없는 spec 은 이 파일에서 pin 되지 않은 것으로 본다

Resolution Rules

지원 locale:

  • ko
  • en

사용 가능한 spec:

  • rawp
  • rawp-crs
  • rawp-dps

기본값:

  • locale: ko
  • spec: rawp

Spec

  1. 사용자 명시값
  2. .rawp-version.yaml 의 defaultSpec
  3. 기본값 rawp

Version

  1. 사용자 명시값
  2. .rawp-version.yaml 의 specs[{spec}]
  3. /{locale}/spec-index.json 의 latestVersion

Locale

  1. 사용자 명시값
  2. .rawp-version.yaml 의 locale
  3. 기본값 ko

충돌 규칙:

  • 사용자 요청과 .rawp-version.yaml 이 충돌하면 사용자 요청을 우선한다.
  • 단, 응답에 충돌 사실을 짧게 적는다.

fallback 규칙:

  • 요청 locale 이 해당 version 에 없으면 ko 로 fallback 한다.
  • fallback 사용 사실을 응답에 적는다.

Read Strategy

기본 원칙은 전체 문서를 읽지 않고 필요한 범위만 읽는 것이다.

문서 표면 확인

먼저 다음 중 하나를 사용한다.

  • 스펙 목록과 최신 버전 확인: /{locale}/spec-index.json
  • 라우트 패턴 확인: /{locale}/agent-map.json

특정 버전의 구조 확인

전체 문서를 바로 읽지 말고 먼저:

  • /{locale}/specs/{spec}/{version}/toc.md

를 읽는다.

그 후 필요한 섹션만:

  • /{locale}/specs/{spec}/{version}/sections/{section}.md

로 읽는다.

전체 문맥이 꼭 필요할 때만

  • /{locale}/specs/{spec}/{version}/full.md

를 사용한다.

버전 차이 확인

변경점이 목적이면 먼저:

  • /{locale}/specs/{spec}/{version}/diff.md

를 읽고, 필요한 섹션만 추가 조회한다.

Endpoint Patterns

  • Agent map JSON: https://rawp-docs.crystall.in/{locale}/agent-map.json
  • Spec index JSON: https://rawp-docs.crystall.in/{locale}/spec-index.json
  • Skill Markdown: https://rawp-docs.crystall.in/{locale}/for-agents.md
  • Full Markdown: https://rawp-docs.crystall.in/{locale}/specs/{spec}/{version}/full.md
  • TOC Markdown: https://rawp-docs.crystall.in/{locale}/specs/{spec}/{version}/toc.md
  • Section Markdown: https://rawp-docs.crystall.in/{locale}/specs/{spec}/{version}/sections/{section}.md
  • Diff Markdown: https://rawp-docs.crystall.in/{locale}/specs/{spec}/{version}/diff.md

사람용 HTML 경로:

  • /{locale}/
  • /{locale}/for-agents
  • /{locale}/specs
  • /{locale}/specs/{spec}
  • /{locale}/specs/{spec}/{version}

이 경로들은 브라우저용이며 에이전트 기본 진입점이 아니다.

Response Contract

가능하면 답변 시작에 다음 문맥을 짧게 적는다.

  • spec
  • version
  • locale
  • .rawp-version.yaml 사용 여부
  • locale fallback 여부

예:

  • Resolved: spec=rawp, version=1.0.1, locale=ko, source=.rawp-version.yaml

Minimal Workflow

질문이 들어오면 다음 순서로 행동한다.

  1. 프로젝트 루트 결정
  2. <project-root>/.rawp-version.yaml 확인
  3. spec, version, locale 결정
  4. spec-index.json 으로 locale 노출 여부 확인
  5. toc.md 조회
  6. 필요한 sections/*.md 만 읽기
  7. 필요할 때만 full.md 또는 diff.md 추가 조회