# 에이전트의 스킬·MCP·문서 점검 활용

기능을 설치하면 사용할 수 있게 되지만, 맞는 작업마다 에이전트가 반드시 선택한다는 뜻은 아닙니다. 사용 가능 여부, 실제 선택, 실행 성공을 구분해서 확인합니다.

## 서로 다른 세 가지 방식

| 구성 | 사용할 수 있게 하는 방법 | 사용 방식 |
| --- | --- | --- |
| 스킬 | 프로필을 설치하고 앱에서 목록 다시 불러오기 | 설명이 맞으면 에이전트가 선택하거나 사용자가 명시적으로 호출 |
| MCP | 서버를 등록·활성화하고 연결 다시 불러오기. Codex에서는 공통 항목 하나로 사용 가능 | 요청에 맞는 연결된 도구를 에이전트가 선택해 호출 |
| 문서·UI CLI | npm 패키지와 허용된 셸·Node 실행 도구 준비 | 도움이 될 때 에이전트나 사용자가 참고용 명령 실행 |

[공식 스킬 안내](https://learn.chatgpt.com/docs/build-skills)는 명시적 호출과 설명을 통한 자동 선택을 모두 설명합니다. 실제 앱의 동작과 목록은 현재 세션에서 확인해야 합니다. 디스크 파일, 스킬 목록, SKILL.md 읽기, 유용한 결과는 서로 다른 관측입니다.

## 도구 이름보다 작업을 요청하기

- 작업 재개: “현재 프로젝트 상태를 읽고 근거와 다음 할 일을 알려줘.”
- 문서 편집: “이 한국어 안내를 따라 하기 쉽게 고쳐줘. 명령·수치·URL·존댓말은 유지해 줘.”
- UI 검토: “브랜드와 정보 밀도는 유지하면서 실제 화면의 키보드 이동을 확인해 줘.”

이런 요청은 `project-memory`, `natural-writing-humanization`, `ui-polish`와 연결될 수 있습니다. 에이전트가 놓치면 원하는 스킬을 명시적으로 호출하세요. 한 번 선택하지 않았다고 모든 스킬을 매 작업의 필수 절차로 만들지는 않습니다.

## MCP 연결과 검증

코드 구조 검색이 필요하면 `--with-ast`로 `aapb_ast_search`를 추가할 수 있습니다. [AST 검색](ast-search.ko.md)에서 설명합니다. 문서 점검 CLI는 어느 MCP 모드에도 포함되지 않습니다.

기본 MCP는 `aapb_status`, `aapb_search`, `aapb_read`, `aapb_validate`를 제공합니다. 먼저 연결되어야 에이전트가 호출할 수 있습니다. 비활성 공통 서버가 npm 설치, 스킬 선택, SDK 테스트 성공만으로 켜지지는 않습니다.

Codex에서는 프로젝트별 경로 설정 없이 공통 서버가 각 작업의 폴더를 사용할 수 있습니다. 원하는 프로젝트에서 작업을 여세요. 기본 동작과 선택적인 경로 고정은 [MCP 설정](mcp-permission-model.ko.md)에서 설명합니다. 도구 이름을 확인하고 상태·읽기·검색·검증을 호출한 뒤 결과와 파일 무변경을 대조하세요. 이 검사는 서버 동작을 확인합니다. 자동 선택을 보려면 별도로 도구 이름을 말하지 않은 일반 요청을 주고 실제 선택을 확인해야 합니다. 파일을 직접 읽는 것도 적절한 선택일 수 있습니다.

## 작업 공간과 오래 유지할 기록

CURRENT.md와 관련 지식·일지부터 읽습니다. 경로, 저장소, 월과 종류 필터로 범위를 좁히고 근거가 부족할 때 넓힙니다. 전역 참고 자료가 있다고 해서 전체 이력을 읽거나 매 응답마다 기록할 필요는 없습니다. 의미 있는 진척을 기록하고 정확한 근거는 [오래 유지할 기록](durable-records.ko.md)에 보존합니다.

공통 기록은 명시적으로 등록된 구성원에만 연결됩니다. 코드나 Git 작업 전에 선택한 저장소와 지침, 루트, 브랜치, 미반영 변경과 필수 검사를 확인합니다. 작업 공간 루트에서 AST·Forge는 `--repo <id>`가 필요합니다. 기록 도구의 `recordSource`는 공통·기존 로컬 기록을 선택하고 검색의 `repo`는 구성원에 해당하는 기록을 필터링합니다. [작업 공간](workspaces.ko.md)을 참고하세요.

Astra와 Sol 모두 메인 작업을 맡을 수 있습니다. Sol `xhigh`·`max`를 포함해 사용자의 모델과 추론 강도 선택을 보존합니다. 기록은 보통 메인에서 작성하며 길고 독립적인 초안은 범위를 정한 근거와 짧은 관련 이력으로 선택적으로 위임할 수 있습니다. 메인은 원본 경로, 수치, 명령, URL, 결정과 미확인 사항을 검토한 뒤 반영합니다. 정확한 spawn 인자와 권한은 호스트 기능에 따라 달라지며 역할 프롬프트는 보안 샌드박스가 아닙니다. [Codex 모델 사용](../adapters/codex/model-use.ko.md)은 25분 설정을 강제하거나 예약기를 추가하지 않고 지원되는 v1/v2 대기를 설명합니다.

명시적 승인 조건을 지키며 허용된 조사, 구현, 검증과 검토를 완료합니다. 관련 입력과 조건이 같고 필수 검사 규칙이 허용할 때만 통과한 검증을 재사용합니다. 실행 예제나 설정 계약을 바꾸었다면 그에 맞는 검증이 여전히 필요합니다.

## 한국어 작성 도구

문서 스킬은 의미와 문체를 보존하고 필요한 예시를 제공합니다. 일반 편집마다 검사기를 실행할 필요는 없습니다. 수정 전후의 중요한 정보를 비교할 때 선택형 CLI를 사용할 수 있습니다.

```sh
ai-agent-playbook writing fidelity-check --before docs/before.md --after docs/after.md --lang ko --json
ai-agent-playbook writing naturalness-check --path docs/after.md --lang ko --engine js --json
```

대상 프로젝트에서 실행하거나 경로를 지정하세요. 이 명령들은 어느 MCP 모드에도 포함되지 않습니다. `--with-ast`는 소스 검색 도구만 추가합니다. 문서 CLI는 앱의 일반 실행 기능으로 호출하며, 결과도 참고 신호이지 좋은 한국어를 보장하는 판정은 아닙니다.

## 어디를 확인해야 하나요?

| 관측 | 확인한 것 | 다음 확인 |
| --- | --- | --- |
| `skills check` 성공 | 선택한 설치 파일이 패키지와 일치 | 앱에서 목록을 다시 불러와 확인 |
| 스킬이 목록에 보임 | 설명을 사용할 수 있음 | 관련 작업에서 실제 선택과 SKILL.md 읽기 확인 |
| MCP 프로세스 시작 | 실행 파일이 시작됨 | 도구 목록과 실제 호출 확인 |
| SDK 호출 성공 | 서버·통신 동작 | 사용하는 앱에서 별도로 시험 |
| 자연어 요청에서 도구 사용 | 선택 사례 한 번 성공 | 결과 품질과 대표 작업을 더 확인한 뒤 일반화 |

호출 한 번으로 전반적인 자율 활용이 안정적이라고 주장하지 않습니다. 요청 범위에 설정 변경이 없다면 비활성 연동과 사용자가 고른 설정을 보존합니다.