DeepSeek Harness에 skill 설치하는 법: dsh가 영상을 보게 만드는 실전 튜토리얼

DeepSeek Harness에 skill을 설치하는 가장 빠른 방법은 딱 한 단계입니다. <기술 이름>/SKILL.md 디렉터리를 ~/.agents/skills에 넣고 dsh를 재시작하면 명령 팔레트에 바로 나타납니다. dsh의 기술 계약이 Anthropic이 만든 SKILL.md 포맷을 그대로 쓰기 때문입니다——Claude Code용으로 작성해둔 기술이 있다면 손대지 않고 그대로 옮겨 쓸 수 있습니다. 이 글에서 가장 값진 한 줄을 먼저 드립니다.

프레임워크를 설치한 뒤 정작 발목을 잡는 건 「이게 대체 뭘 할 수 있는가」입니다. 이번 주 중국어권에는 dsh의 아키텍처 해설과 설치 튜토리얼이 이미 넘쳐나지만, 그다음 질문에 답하는 사람은 거의 없습니다. 프레임워크가 돌아가기 시작했다면, 원래 없던 능력을 어떻게 더해줄까요?

이 글은 「dsh가 무엇인가」를 101번째로 설명하지 않습니다. 검증 가능한 구체적인 과제 하나로 글 전체를 관통시킵니다——dsh가 영상을 볼 수 있게 만드는 것, 즉 B站(빌리빌리)·YouTube·팟캐스트를 요약할 수 있는 skill을 붙여주는 일입니다. 끝까지 따라 하면 손에는 진짜 일할 줄 아는 dsh가 남고, 덤으로 어떤 skill이든 설치할 수 있는 범용적인 방법도 익히게 됩니다.

목차

• dsh 설치 후, 능력 공백은 어디에 있을까
• dsh의 skill 포맷은 무엇일까
• 이미 가진 skill을 dsh에서 바로 쓰는 방법
• skill을 dsh 플러그인으로 만드는 방법
• 복사와 플러그인, 두 가지 방법 중 무엇을 선택할까
• 시작하기 전에 알아야 할 두 가지 함정
• 설치 후, dsh가 영상을 실제로 이해하게 만드는 방법
• 자주 묻는 질문: dsh와 skill 설치

dsh 설치 후, 능력 공백은 어디에 있을까

DeepSeek Harness(명령줄에서는 dsh라고 부릅니다)는 DeepSeek이 2026년 8월 13일에 오픈소스로 공개한 Agent 프레임워크입니다. Cordis를 기반으로 하며, 슬로건은 「모든 것이 플러그인」, 라이선스는 MIT입니다. 공개 당일부터 화제성이 대단했습니다——2026년 8월 14일 기준 GitHub 저장소는 이미 7만 5천 개가 넘는 star를 모았습니다. 배경 설명은 여기까지면 충분하니, 나머지 지면은 전부 실전에 씁니다.

「모든 것이 플러그인」의 또 다른 면은, 기본 상태에서는 전문 능력이 하나도 없다는 것입니다. dsh를 설치하고 「이 B站 영상 좀 요약해줘」라고 물어봐도, 그 링크를 열고 자막을 가져와 내용을 읽어낼 도구가 없습니다. 이건 dsh의 결함이 아니라 설계입니다——빈 토대 위에 당신이 직접 조립하는 구조입니다.

그리고 오디오·영상이야말로 이런 토대의 가장 전형적인 사각지대입니다. 이 세대의 Agent 워크벤치는 기본적으로 텍스트만 소화합니다——웹페이지도 읽고, PDF도 읽고, 코드도 읽지만, 한 시간짜리 강의 녹화, 팟캐스트 한 편, B站 합본 영상 하나는 넣어줄 방법이 없습니다. 회의, 온라인 강의, 팟캐스트라는 고빈도 시나리오 세 가지가 이렇게 문턱에서 막혀 있습니다. 더 큰 컨텍스트 윈도우도 이 문턱을 옮겨주지는 않습니다. DeepSeek V4가 1M 토큰 컨텍스트 윈도우를 들고 나왔을 때도, 한 시간짜리 오디오는 그 용량이 의미를 갖기 전에 먼저 텍스트가 되어야 했습니다.

실전 규칙: Agent의 다음 목적지는 더 똑똑한 agent가 아니라, 오디오·영상을 넣어줄 수 있는 입력 계층입니다.

이 입력 계층을 채워야, agent가 비로소 「한 마디로 영상을 다루는」 단계에 이를 수 있습니다. 아래 그림은 같은 일이 성숙한 형태로 구현된 모습입니다——자연어로 의도를 말하면 도구가 자동으로 호출됩니다.

스크린샷: BibiGPT · AI 대화 Agent 모드

그러므로 「dsh에 skill 설치하기」에서 가장 먼저 설치할 가치가 있는 건 바로 영상을 보는 능력입니다. 아래 인터랙티브 데모는 dsh가 갖추게 될 최종 결과물입니다——영상 하나를 고르면 타임스탬프가 붙은 구조화된 요약을 바로 받을 수 있습니다.

어떤 영상이든 몇 초 만에 요약

샘플을 선택하면 AI 요약이 나타납니다——한 줄 결론, 핵심 정리, 바로 이동하는 타임스탬프.

샘플 체험:밑바닥부터 GPT 만들기 —— Andrej Karpathy1:56:20미루기 달인의 머릿속 —— Tim Urban (TED)14:04

한 줄 요약: Karpathy가 GPT 형태의 언어 모델을 코드로 밑바닥부터 구축하며, 작은 문자 단위 모델부터 완전한 Transformer까지 모든 조각을 설명합니다.

핵심

• bigram 모델로 시작해 self-attention을 더해 토큰끼리 "대화"하게 만든다
• Transformer 블록 = 멀티헤드 어텐션 + 피드포워드 + 잔차 연결 + 층 정규화
• 학습은 그저 "다음 토큰 예측"; 나머지는 규모와 데이터가 한다
• nanoGPT의 구조를 키운 것이 곧 ChatGPT

바로가기

• 00:07 왜 밑바닥부터 만드나
• 08:23 직관으로 보는 self-attention
• 1:00:00 Transformer 블록 조립
• 1:35:00 nanoGPT에서 ChatGPT로

YouTube내 영상으로 해보기 →

dsh의 skill 포맷은 무엇일까

dsh의 skill은 YAML frontmatter가 붙은 Markdown 파일입니다. 디렉터리 이름은 kebab-case를 쓰고, frontmatter에는 최소한 name과 description 두 필드가 있어야 합니다. 이는 Anthropic이 Claude Code를 위해 정의한 Agent Skills 규격과 동일한 계약입니다——즉 기술을 agent 간에 재사용할 수 있고, dsh용으로 다시 쓸 필요가 없다는 뜻입니다.

유효한 구성 방식은 두 가지입니다:

skills/
  bibi/
    SKILL.md          ← 디렉터리 패키지: 메인 파일 + references/, scripts/ 동반 가능
  quick-note.md       ← 플랫 파일: 단일 파일 기술

공식 skills 서브시스템 문서에 따르면 재귀 탐색은 지원하지 않습니다——dsh는 탐색 루트 바로 아래의 하위 디렉터리와 플랫 파일만 인식하며, 기술을 2단계 하위 디렉터리에 숨기면 찾지 못합니다. 이는 놓치기 쉬운 첫 번째 디테일입니다.

정말로 「어디에 설치할지」를 결정하는 것은 dsh의 6단계 탐색 경로이며, 숫자가 작을수록 우선순위가 높습니다. 이 글에서 다루는 작업——이미 가지고 있는 기술을 설치하는 것——에는 이 6단계 중 딱 2단계만 관련이 있습니다:

우선순위	경로	이럴 때 선택
200	<project>/.agents/skills	기술이 특정 저장소 소속이라 그 저장소와 함께 이동해야 할 때
500	~/.agents/skills	기술을 어디서든 내 것으로 쓰고 싶을 때——Claude Code도 같은 경로를 읽습니다

나머지 4단계는 일상적인 설치보다는 dsh 전용 재정의와 패키징을 다루는 영역입니다.

여기서 말하는 「프로젝트」는 가장 가까운 .git을 포함한 상위 디렉터리를 뜻합니다. 찾지 못하면 현재 작업 디렉터리로 돌아갑니다. 그래서 같은 이름의 기술이 프로젝트 안에서 전역 설정을 덮어쓰는 건 직관과 맞아떨어집니다.

아래 그림은 저희 그 기술이 GitHub 저장소에서 어떤 모습인지 보여줍니다. 디렉터리 패키지가 어떻게 생겼는지 대조해서 볼 수 있습니다.

스크린샷: BibiGPT · Agent 기술 오픈소스 저장소의 설치 페이지

실전 규칙: Claude Code용으로 작성한 skill이 있다면, 먼저 그대로 dsh에 넣어 시도해보고 나서 수정을 고민하세요——대부분은 고칠 필요조차 없을 겁니다.

이미 가진 skill을 dsh에서 바로 쓰는 방법

가장 빠른 방법은 500단계 탐색 루트를 이용하는 것입니다. 기술 디렉터리를 ~/.agents/skills/에 넣으면 dsh가 시작할 때 자동으로 스캔하며, 별도 설정이 필요 없습니다. 이 디렉터리는 dsh가 만든 게 아니라 Claude Code 같은 agent들이 이미 쓰고 있던 것입니다——그래서 한 번만 설치하면 두 agent 모두 볼 수 있습니다.

저희가 오픈소스로 공개한 오디오·영상 기술을 예로 들면, 오늘 당장 실행 가능한 방법은 저장소를 클론한 뒤 기술 디렉터리를 복사해 넣는 것입니다:

git clone https://github.com/JimmyLv/bibigpt-skill.git
mkdir -p ~/.agents/skills
cp -r bibigpt-skill/skills/bibi ~/.agents/skills/

그다음 dsh를 재시작하고 명령 팔레트에 /를 입력하면, 기술이 Skills 그룹에 나타납니다. 아래는 실제 테스트 스크린샷입니다——bibi가 이미 목록에 있고, 설명도 온전히 렌더링되어 있습니다:

스크린샷: dsh 0.1.0-rc.6 웹 인터페이스. 화면에 보이는 API key is invalid 문구는 저희가 자리표시용 키로 격리 검증을 했을 때 예상된 결과이며, 설치 실패가 아닙니다——기술 인식과 모델 호출은 별개의 문제입니다.

같은 세션 안에서 Context injection · skill-catalog 흔적도 확인할 수 있는데, 이는 기술 디렉터리가 실제로 모델 컨텍스트에 주입되었다는 뜻이지, UI에 이름만 나열된 게 아니라는 걸 보여줍니다. 「제대로 설치됐는지」를 판단하는 가장 확실한 신호입니다.

특정 프로젝트에서만 적용하고 싶다면? 같은 디렉터리를 해당 프로젝트의 .agents/skills/(200단계) 아래에 두면 우선순위가 더 높고, 전역 설정을 오염시키지도 않습니다.

skill을 dsh 플러그인으로 만드는 방법

디렉터리를 복사하면 작동은 하지만 업데이트가 골치 아픕니다——기술이 업그레이드될 때마다 다시 복사했다는 걸 기억해야 합니다. 플러그인은 설치와 업데이트를 명령어 하나로 압축해줍니다. 이것이 플러그인이 존재하는 유일한 이유입니다.

dsh 플러그인의 핵심은 package.json에 patch 파일을 선언하는 것입니다:

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

cordis.patch.yml이 profile에 설정 한 줄을 기여하면, 사용자 쪽 설치는 명령 하나로 압축됩니다. 저희 오디오·영상 skill을 예로 들면, 아래 명령은 오늘 바로 실행됩니다:

dsh plugin --profile web add "github:JimmyLv/bibigpt-skill#path:/dsh-plugin"

따옴표를 빼지 마세요——shell에서 #는 주석의 시작으로 해석되어, 따옴표가 없으면 인자의 뒷부분이 통째로 사라집니다.

이 명령에는 따로 기억해둘 만한 지식이 하나 숨어 있습니다: dsh plugin은 인자를 pnpm에 넘겨줄 뿐이고, pnpm 자체가 git 저장소의 하위 디렉터리에서 곧바로 패키지를 설치하는 것을 지원합니다. 즉 dsh 플러그인을 만드는 데 npm 패키지 배포가 전혀 필요 없습니다——소스를 GitHub에 올리면 누구나 명령 하나로 설치할 수 있고, 저장소 업데이트도 그대로 따라옵니다.

플러그인은 런타임에 ctx.skills.register()를 통해 기술을 등록하며, 파일 시스템 기술 제공자의 customSkillDirs를 건드리지 않습니다. 이유는 실용적입니다——dsh의 patch 라인은 config를 통째로 교체할 뿐 깊은 병합을 하지 않기 때문에, 남의 그 한 줄을 고치려면 모든 키를 다시 써야 하고, 같은 줄을 고치려는 다른 패키지와도 충돌하게 됩니다.

SkillRegistration에는 선택 필드 resourceBase가 있으며, directory / url / opaque 세 가지 형태를 지원합니다. 여러분의 기술이 단일 파일이 아니라 references/와 scripts/를 동반한 디렉터리 패키지라면 반드시 이를 선언해야 하며, 그렇지 않으면 기술 본문의 상대 경로 참조가 전부 깨집니다. 이미 배포된 PicGo 공식 dsh 플러그인은 단일 SKILL.md라 이 문제가 없습니다——그대로 베끼면 함정에 빠집니다.

나머지 계약 내용 — 전체 SkillRegistration 필드 목록, 정확한 우선순위까지 매겨진 6개 탐색 루트 전체, 그리고 공식 skills 호환 도구 쇼케이스에 dsh가 여전히 이름을 올리지 못한 이유 — 은 공식 skills 서브시스템 문서를 보면 됩니다.

플러그인 생태계는 빠르게 성장하고 있습니다——GitHub에서 dsh-plugin 태그가 붙은 저장소는 2026년 8월 14일 기준 이미 1,200개를 넘어섰고 지금도 빠르게 늘고 있으며, GitHub의 dsh-plugin 토픽 페이지에서 바로 살펴볼 수 있습니다.

먼저 프레임워크 자체의 플러그인 철학을 훑어보고 시작하고 싶다면, 아래 영상이 「모든 것이 플러그인」을 비교적 명확하게 설명해줍니다:

영상 출처: YouTube · DevsKingdom · Deepseek Harness: Everything is a plugin(12분)

여기까지 오면 두 갈래 길 모두 오늘 실제로 돌아갑니다: 위의 플러그인 명령(명령 하나로 끝나고 업데이트도 따라옴), 또는 앞 절의 디렉터리 복사(의존성 제로에 Claude Code와 dsh가 같은 한 부를 공유). 다음 절에서 선택을 도와드리겠습니다.

복사와 플러그인, 두 가지 방법 중 무엇을 선택할까

한마디로: 혼자 쓸 거면 디렉터리를 복사하고, 남에게 배포할 거면 플러그인을 만드세요. 비교 가능한 네 가지 기준으로 풀어보면:

기준	~/.agents/skills에 복사	dsh 플러그인으로 제작
적합한 대상	나 자신/이 기기에서만 사용	배포용, 남이 한 번에 설치할 수 있어야 함
설치 비용	cp 한 줄	package.json + patch 파일 작성 필요
업데이트 방식	수동으로 다시 복사	패키지 매니저로 일괄 업그레이드
agent 간 재사용	가능, Claude Code도 동시에 인식	불가능, dsh 전용

세 번째 줄이 진짜 분수령입니다. 기술은 제품 능력이 발전함에 따라 계속 바뀌는데, 한 달에 세 번씩 고치는 기술을 수동 복사로 유지하기는 오래가지 못합니다. 반대로 변하지 않는 안정적인 개인용 기술이라면, 플러그인으로 만드는 건 오히려 과잉 엔지니어링입니다.

네 번째 줄도 따로 짚을 가치가 있습니다——~/.agents/skills는 agent 간 공용 디렉터리인 반면, 플러그인 등록은 dsh에만 적용됩니다. 두 agent를 동시에 쓰고 있다면 디렉터리 방식의 가성비가 훨씬 좋습니다.

판단 기준: 나만 쓴다 → 디렉터리 복사; 남에게 줄 것이고 계속 업데이트될 것이다 → 플러그인 제작.

시작하기 전에 알아야 할 두 가지 함정

이 두 함정은 0.1.0-rc.6에서 실제 테스트하면서 둘 다 부딪혔고, 둘 다 「설치 실패」로 오판하게 만들 수 있습니다.

함정 1: DEEPSEEK_API_KEY가 없으면 아예 들어갈 수 없습니다. dsh는 시작할 때 이 환경 변수를 강제로 요구하며, 없으면 MISSING_CREDENTIAL로 종료되어 화면조차 열리지 않습니다——기술이 설치됐는지 볼 기회조차 없는 것입니다. 이 검사는 존재 여부만 확인하므로, 격리 검증을 할 때는 자리표시용 값으로도 시작 검사를 통과시킬 수 있습니다——모델 호출은 실패하지만 세션과 워크스페이스 기록은 정상적으로 생성되고 명령 팔레트도 사용 가능하니, 기술이 인식됐는지 검증하기에는 충분합니다.

함정 2: 웹 인터페이스의 워크스페이스 선택기가 클릭이 안 될 수 있습니다. 이는 rc 버전에서 알려진 미완성 부분입니다. 우회법은 목표 디렉터리에서 먼저 헤드리스 모드로 한 번 실행해 세션 기록을 만들어두는 것입니다:

dsh --profile headless "현재 디렉터리에 어떤 파일이 있는지 알려줘"

실행이 끝난 뒤 웹 인터페이스로 돌아가면 사이드바에 이 워크스페이스가 나타납니다. 그때 자리표시용 키 때문에 인증 실패가 떴더라도 상관없습니다——기록은 이미 저장되어 있습니다.

덧붙이자면, dsh의 로그는 표준 출력으로 플러그인 로그를 내보내지 않습니다. ctx.logger.info는 보이지 않으니 로그로 등록 성공 여부를 확인하려 하지 마세요. 검증하려면 명령 팔레트의 Skills 그룹과 세션 안의 Context injection · skill-catalog를 확인하면 됩니다.

버전도 짚고 넘어가면, 이 글의 모든 실측은 0.1.0-rc.6에서 진행했으며 2026년 8월 14일 기준 여전히 개발자 프리뷰 단계입니다. dsh 커맨드라인 패키지 소스 디렉터리는 릴리스에 따라 바뀌므로, 시작하기 전에 현재 번호를 한 번 확인하세요. 위에서 다룬 API들(특히 resourceBase 같은 비교적 신규 필드)은 정식 버전에서 바뀔 수 있으니, 플러그인을 만든다면 버전을 고정해두길 권합니다.

아래 그림은 기술 뒤편에 있는 명령줄 도구의 도움말 화면입니다. 어떤 파라미터를 받는지 먼저 살펴볼 수 있습니다:

스크린샷: BibiGPT · 명령줄 도구의 help 출력

실전 규칙: rc 버전은 먼저 격리된 DSH_HOME으로 시도하고, 홈 디렉터리를 실험장으로 쓰지 마세요——홈 디렉터리가 더럽혀지지 않아야 검증 결론도 성립합니다.

설치 후, dsh가 영상을 실제로 이해하게 만드는 방법

기술이 패널에 나타나는 건 첫걸음일 뿐, 진짜 검수 기준은 링크 하나를 던져 넣고 쓸 만한 구조화된 노트를 돌려받는 것입니다. 완전한 흐름은 다섯 단계입니다:

1. BibiGPT 데스크톱 앱을 설치합니다. 기술이 의존하는 명령줄 도구가 함께 딸려 옵니다.
2. 앞서 소개한 방법 중 하나로 기술을 dsh에 설치합니다.
3. dsh를 재시작하고, 명령 팔레트의 Skills 그룹에서 보이는지 확인합니다.
4. 그냥 편하게 말합니다: 「이 영상 좀 요약해줘」라고 하면서 링크를 첨부합니다.
5. 타임스탬프가 붙은 구간별 요약을 받고, 타임스탬프를 클릭해 원본 영상으로 되돌아가 대조합니다.

이 기술은 Claude Code, OpenClaw 등 여러 agent에서 동시에 쓸 수 있고 기술 본문도 완전히 동일합니다——이것이 저희가 SKILL.md 표준 포맷을 고수하는 이유이기도 합니다. 다른 agent에서의 전체 사용법을 보고 싶다면 AI Agent에 오디오·영상 요약 능력을 붙이는 완전 가이드를 읽어보세요. 「오디오·영상을 agent에 넣어준다」는 것의 전체적인 사고방식을 이해하고 싶다면 오디오·영상을 AI Agent에 넣는 워크플로우가 더 체계적으로 다룹니다. AI 영상 요약 자체가 아직 낯설다면 AI 영상 요약 완전 가이드가 더 좋은 출발점입니다.

스크린샷: BibiGPT · Agent 기술이 있는 기술 마켓 페이지

프레임워크의 가치는 프레임워크 자체가 아니라 그 안에 무엇을 채워 넣느냐에 있습니다. dsh는 「무엇을 채울 것인가」의 문턱을 Markdown 파일 하나로 낮췄습니다——진짜 희소한 것은, agent가 읽을 수 없는 것을 읽을 수 있는 것으로 바꿔주는 기술입니다.

여러분의 dsh에 오디오·영상 능력을 채우세요 — 설치 없이 브라우저에서 바로 써 볼 수도 있습니다:

• ▶️ 브라우저에서 요약 (dsh 불필요): Bilibili 또는 YouTube 링크 붙여넣기
• 🌐 데스크톱 앱 다운로드: https://bibigpt.co/ko/desktop
• 🧩 기술 소스 코드: https://github.com/JimmyLv/bibigpt-skill
• 🎬 효과 확인하기: B站 영상 AI 요약

자주 묻는 질문: dsh와 skill 설치

Q1: Claude Code용으로 작성한 skill을 dsh에서 정말 바로 쓸 수 있나요?

A: 됩니다. 양쪽 모두 <기술 이름>/SKILL.md + YAML frontmatter라는 동일한 계약을 씁니다. frontmatter에는 최소 name과 description이 필요합니다. 기술 디렉터리를 ~/.agents/skills/에 넣으면 두 agent가 같은 파일을 읽습니다. 한쪽 전용 능력(예: 특정 도구 호출 규약)을 쓴 극소수 기술만 수정이 필요합니다.

Q2: skill은 어느 디렉터리에 설치해야 하나요?

A: 나만 쓸 거면 ~/.agents/skills/(500단계)에 두면 agent 간 공용으로 쓸 수 있습니다. 특정 프로젝트에서만 적용하고 싶다면 그 프로젝트의 .agents/skills/(200단계)에 두면 우선순위가 더 높습니다. 「프로젝트」는 가장 가까운 .git을 포함한 상위 디렉터리이지, 그냥 cd로 들어간 아무 폴더가 아니라는 점에 유의하세요.

Q3: dsh가 실행이 안 되고 MISSING_CREDENTIAL 오류가 뜨는데 왜 그런가요?

A: dsh는 시작할 때 DEEPSEEK_API_KEY 환경 변수를 강제로 요구하며, 없으면 바로 종료되어 화면조차 들어갈 수 없습니다. 실제 키를 설정하면 정상적으로 쓸 수 있습니다. 기술이 인식됐는지만 확인하고 싶다면 자리표시용 값으로도 시작 검사는 통과하며, 모델 호출은 실패하지만 명령 팔레트는 사용할 수 있습니다.

Q4: 웹 인터페이스에서 워크스페이스를 선택할 수 없으면 어떻게 하나요?

A: 이는 0.1.0-rc.6의 알려진 미완성 부분입니다. 먼저 목표 디렉터리에서 헤드리스 모드(dsh --profile headless, 아무 작업이나 하나 주면 됩니다)로 한 번 실행해 세션 기록을 만든 뒤 웹 인터페이스로 돌아가면, 사이드바에 이 워크스페이스가 나타납니다.

Q5: 언제 디렉터리 복사 대신 플러그인으로 만들어야 하나요?

A: 판단 기준은 「계속 업데이트되는가」와 「남에게 쓰게 할 것인가」입니다. 기술이 지속적으로 개선되거나 남이 명령어 하나로 설치하게 하고 싶다면 플러그인으로 만드세요. 자신의 기기에서만 쓰는 안정적인 기술이라면 디렉터리 복사가 더 간편하고, 덤으로 Claude Code도 함께 볼 수 있습니다.

BibiGPT 팀