메모리와 스킬

메모리와 스킬 (Memory and Skills)

에이전트를 쓰다 보면 "이전에 알려줬던 코딩 스타일을 계속 기억해줬으면 좋겠는데" 싶을 때가 있어요. 그리고 어떤 작업이 들어왔을 때만 해당하는 전문 지식을 불러오면 더 좋고요. Deep Agents Code는 이 두 가지를 **메모리(Memory)**와 **스킬(Skills)**이라는 서로 다른 방식으로 나눠서 다뤄요. 여기서는 둘이 어떻게 다르고, 각각 어떻게 만들고 쓰는지 살펴볼게요.

출처: 공식문서

메모리와 스킬의 차이

Deep Agents Code에서 에이전트를 커스터마이즈하는 방법은 크게 두 가지예요.

  • 메모리: AGENTS.md 파일과 자동 저장되는 메모리로, 세션을 넘나들며 유지돼요. 일반적인 코딩 스타일, 선호, 학습한 관례를 담을 때 써요.
  • 스킬: 재사용 가능하고 필요할 때만 발견·읽히는 능력이에요. 워크플로우, 모범 사례, 레퍼런스 문서처럼 작업별 맥락을 담을 때 써요.

실제로 스킬과 메모리는 연속선상에 있어요. 언제 무엇을 써야 하는지 더 자세히 보고 싶다면 Skills, memory, and tools 문서를 참고하면 돼요.

/remember 명령으로 지금 대화에서 얻은 내용을 명시적으로 메모리와 스킬에 반영하라고 요청할 수도 있어요.

SDK로 커스텀 에이전트를 만드는 중이라면 프로그래매틱 메모리 백엔드는 Memory 문서를 참고하세요.

메모리 (Memory)

자동 메모리 (Automatic memory)

에이전트를 쓰는 동안, 에이전트는 정보를 ~/.deepagents/<agent_name>/memories/ 폴더에 마크다운 파일로 자동 저장해요. 메모리 우선 프로토콜을 따르는 방식이에요:

  1. 조사(Research): 작업을 시작하기 전에 메모리에서 관련 맥락을 검색해요
  2. 응답(Response): 실행 중 헷갈릴 때 메모리를 확인해요
  3. 학습(Learning): 미래 세션을 위해 새 정보를 자동으로 저장해요

메모리는 계속 읽으면서 자동 저장만 멈추고 싶다면 Automatic memory 문서를 참고하세요.

에이전트는 메모리를 주제별로, 설명적인 파일 이름으로 정리해요:

~/.deepagents/backend-dev/memories/
├── api-conventions.md
├── database-schema.md
└── deployment-process.md

에이전트에게 관례를 가르치면:

dcode --agent backend-dev
> Our API uses snake_case and includes created_at/updated_at timestamps

다음 세션이 되면 이렇게 기억하고 있어요:

> Create a /users endpoint
# Applies conventions without prompting

AGENTS.md 파일

AGENTS.md 파일은 세션 시작 시 항상 로드되는 영구 맥락을 제공해요.

  • 전역(Global): ~/.deepagents/<agent_name>/AGENTS.md — 모든 세션에서 로드돼요.
  • 프로젝트(Project): git 프로젝트 루트의 .deepagents/AGENTS.md — 해당 프로젝트에서 Deep Agents Code를 실행할 때 로드돼요.

두 파일 모두 시작 시점에 시스템 프롬프트에 추가돼요.

저장소 위키를 생성하고 코딩 에이전트용 AGENTS.md·CLAUDE.md에 포인터를 연결하고 싶다면 OpenWiki 문서를 참고하세요.

메모리가 동작하는 방식

에이전트는 프로젝트별 질문에 답할 때나, 과거 작업·패턴을 언급할 때 메모리 파일을 읽을 수 있어요.

에이전트는 어떻게 행동해야 하는지, 작업에 대한 피드백, 기억할 지시사항 등을 제공받으면 AGENTS.md를 갱신해요. 상호작용에서 패턴이나 선호를 발견해도 메모리를 갱신해요.

더 구조화된 프로젝트 지식을 추가 메모리 파일에 담고 싶다면 .deepagents/ 폴더에 넣고, AGENTS.md 파일에서 그 파일들을 참조하면 돼요. 에이전트가 그 파일들을 알게 하려면 AGENTS.md에서 반드시 참조해야 해요. 추가 파일은 시작 시 읽히지 않지만, 필요할 때 에이전트가 참조하거나 갱신할 수 있어요.

전역 vs 프로젝트 AGENTS.md

전역 AGENTS.md(~/.deepagents/agent/AGENTS.md)는 다음 용도로 써요:

  • 나의 성격, 스타일, 보편적인 코딩 선호
  • 전반적인 톤과 커뮤니케이션 스타일
  • 보편적인 코딩 선호(포매팅, 타입 힌트 등)
  • 어디서나 적용되는 도구 사용 패턴
  • 프로젝트마다 바뀌지 않는 워크플로우와 방법론

프로젝트 AGENTS.md(프로젝트 루트의 .deepagents/AGENTS.md)는 다음 용도로 써요:

  • 프로젝트 특정 컨텍스트와 관례
  • 프로젝트 아키텍처와 설계 패턴
  • 이 코드베이스에 특화된 코딩 관례
  • 테스트 전략과 배포 프로세스
  • 팀 가이드라인과 프로젝트 구조

스킬 (Skills)

스킬은 워크플로우, 모범 사례, 스크립트, 레퍼런스 문서 같은 도메인 전문 지식을 재사용 가능한 디렉토리로 패키징한 거예요. 에이전트는 관련 있을 때만 그 스킬을 발견하고 읽어요. 딥 에이전트 스킬은 Agent Skills 사양을 따라요. 스킬이 동작하는 방식과 효과적으로 작성하는 방법은 Skills 문서를 참고하세요.

시작 시 Deep Agents Code는 각 SKILL.md 파일의 frontmatter에서 이름과 설명을 읽어요. 작업이 스킬 설명과 일치하면 에이전트가 스킬 파일을 읽고 그 지시사항을 따라요. 발견(discovery)은 /reload 때 다시 실행돼요.

스킬 추가하기

1. 스킬 만들기

# User skill (stored in ~/.deepagents/<agent_name>/skills/)
dcode skills create test-skill

# Project skill (stored in .deepagents/skills/)
dcode skills create test-skill --project

이렇게 하면 다음 구조가 생성돼요:

skills/
└── test-skill
    └── SKILL.md

2. SKILL.md 편집 — 생성된 SKILL.md를 열어 지시사항을 포함하도록 편집해요.

3. 선택적 리소스 추가 — test-skill 폴더에 추가 스크립트나 다른 리소스를 선택적으로 넣을 수 있어요. 자세한 내용은 Usage 문서를 참고하세요.

기존 스킬을 에이전트 폴더로 바로 복사할 수도 있어요:

mkdir -p ~/.deepagents/<agent_name>/skills
cp -r examples/skills/web-research ~/.deepagents/<agent_name>/skills/

커뮤니티 스킬 설치하기

Vercel의 Skills CLI 같은 도구로 커뮤니티 Agent Skills을 환경에 설치해 딥 에이전트에서 쓸 수 있어요:

# Install a skill globally
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a deepagents -g -y

# List installed skills
npx skills ls -a deepagents -g

전역 설치(-g)는 스킬을 ~/.deepagents/agent/skills/ — 기본 에이전트의 사용자 수준 스킬 디렉토리 — 에 심볼릭 링크해요. 프로젝트 수준 설치(-g 제외)는 현재 디렉토리 기준 .deepagents/skills/에 스킬을 배치해서, 에이전트 이름과 무관하게 해당 프로젝트에서 실행되는 모든 에이전트가 쓸 수 있게 해요.

전역 설치는 기본 agent 디렉토리만 대상으로 해요. 커스텀 이름의 에이전트를 쓴다면 프로젝트 수준 설치를 하거나 스킬을 ~/.deepagents/{your-agent}/skills/에 직접 심볼릭 링크하세요.

스킬 발견 (Skill discovery)

시작 시 다음 디렉토리에서 스킬을 로드해요:

~/.deepagents/<agent_name>/skills/
~/.agents/skills/
.deepagents/skills/
.agents/skills/
~/.claude/skills/          (experimental)
.claude/skills/            (experimental)

스킬 이름이 중복되면 나중 우선순위 디렉토리가 앞선 디렉토리를 덮어써요 (App data 참고).

프로젝트별 스킬(.deepagents/skills/ 또는 .agents/skills/ 아래)의 경우, 프로젝트 루트는 .git 폴더를 포함하는지로 식별해요.

세션 중 스킬 호출하기

대화형 세션 안에서 /skill:<name> 슬래시 명령으로 스킬을 직접 실행할 수 있어요:

/skill:code-review
/skill:code-review review the auth module

스킬의 SKILL.md 지시사항이 전달한 인자와 함께 프롬프트에 주입돼요.

스킬과 함께 시작하기

--skill 플래그는 시작 즉시 스킬을 호출해요. 대화형(TUI)이든 비대화형(headless)이든 상관없어요:

# Open the TUI and immediately run a skill
dcode --skill code-review

# Pass a request to the skill with -m
dcode --skill code-review -m 'review the auth module'

# Pipe content into a skill
cat diff.txt | dcode --skill code-review

# Pipe content and add a request
cat diff.txt | dcode --skill code-review -m 'focus on security'

# Run a skill headlessly
dcode --skill code-review -n 'review this patch'

# Quiet mode (only agent output on stdout)
dcode --skill code-review -n 'review this patch' -q

--skill을 --quiet나 --no-stream과 함께 쓰려면 -n(비대화형 모드)이 필요해요.

스킬 목록 보기

# List all user skills
dcode skills list

# List project skills
dcode skills list --project

# Get detailed info about a specific skill
dcode skills info test-skill
dcode skills info test-skill --project

더 알아보기 (Learn more)

  • Skills — 스킬이 동작하는 원리와 효과적인 스킬 작성법.
  • Memory — SDK에서 프로그래매틱 메모리 백엔드 사용하기.
  • Configuration — 자동 메모리와 스킬 발견 설정을 더 자세히 다루는 문서.
  • Skills CLI — 커뮤니티 에이전트 스킬을 설치하는 도구.
  • Agent Skills 사양 — 스킬의 표준 사양과 레지스트리.