Dropstone Docs

에이전트 스킬

SKILL.md 정의를 통해 재사용 가능한 동작 정의

에이전트 스킬을 사용하면 Dropstone이 리포지토리나 홈 디렉토리에서 재사용 가능한 지침을 발견할 수 있습니다. 스킬은 내장 skill 도구를 통해 필요에 따라 로드됩니다. 에이전트는 사용 가능한 스킬을 확인하고 작업과 일치하는 스킬이 있으면 전체 콘텐츠를 로드할 수 있습니다.

파일 배치

스킬 이름별로 폴더를 만들고 그 안에 SKILL.md를 배치합니다. Dropstone은 다음 위치를 검색합니다:

  • 프로젝트 설정: .dropstone/skills/<name>/SKILL.md
  • 전역 설정: ~/.config/dropstone/skills/<name>/SKILL.md
  • 프로젝트 Claude 호환: .claude/skills/<name>/SKILL.md
  • 전역 Claude 호환: ~/.claude/skills/<name>/SKILL.md
  • 프로젝트 에이전트 호환: .agents/skills/<name>/SKILL.md
  • 전역 에이전트 호환: ~/.agents/skills/<name>/SKILL.md

발견 메커니즘 이해

프로젝트 로컬 경로의 경우, Dropstone은 현재 작업 디렉토리에서 git 워크트리에 도달할 때까지 상위 디렉토리로 이동합니다. 이동 경로에서 .dropstone/ 내의 일치하는 skills/*/SKILL.md 및 .claude/skills/*/SKILL.md 또는 .agents/skills/*/SKILL.md를 모두 로드합니다.

전역 정의는 ~/.config/dropstone/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md, ~/.agents/skills/*/SKILL.md에서도 로드됩니다.

프론트매터 작성

각 SKILL.md는 YAML 프론트매터로 시작해야 합니다. 다음 필드만 인식됩니다:

  • name (필수)
  • description (필수)
  • license (선택)
  • compatibility (선택)
  • metadata (선택, 문자열-문자열 맵)

알 수 없는 프론트매터 필드는 무시됩니다.

이름 검증

name은 다음을 충족해야 합니다:

  • 1–64자
  • 소문자 영숫자와 단일 하이픈 구분자
  • -로 시작하거나 끝나지 않음
  • 연속된 -- 포함 안 함
  • SKILL.md를 포함하는 디렉토리 이름과 일치

동등한 정규식:

^[a-z0-9]+(-[a-z0-9]+)*$

길이 규칙 따르기

description은 1-1024자여야 합니다. 에이전트가 올바르게 선택할 수 있도록 충분히 구체적으로 작성하세요.

예제 사용

다음과 같이 .dropstone/skills/git-release/SKILL.md를 만듭니다:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: dropstone
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

도구 설명 인식

Dropstone은 skill 도구 설명에서 사용 가능한 스킬을 나열합니다. 각 항목에는 스킬 이름과 설명이 포함됩니다:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

에이전트는 도구를 호출하여 스킬을 로드합니다:

skill({ name: "git-release" })

권한 구성

dropstone.json에서 패턴 기반 권한을 사용하여 에이전트가 액세스할 수 있는 스킬을 제어합니다:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
권한동작
allow스킬 즉시 로드
deny에이전트에서 스킬 숨김, 액세스 거부
ask로드 전 사용자 승인 요청

패턴은 와일드카드를 지원합니다: internal-*는 internal-docs, internal-tools 등과 일치합니다.

에이전트별 재정의

특정 에이전트에 전역 기본값과 다른 권한을 부여합니다.

커스텀 에이전트의 경우 (에이전트 프론트매터):

---
permission:
  skill:
    "documents-*": "allow"
---

내장 에이전트의 경우 (dropstone.json):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

스킬 도구 비활성화

스킬을 사용하지 않아야 하는 에이전트에 대해 완전히 비활성화합니다:

커스텀 에이전트의 경우:

---
tools:
  skill: false
---

내장 에이전트의 경우:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

비활성화되면 <available_skills> 섹션이 완전히 생략됩니다.

로드 문제 해결

스킬이 표시되지 않으면:

  1. SKILL.md가 모두 대문자로 철자되어 있는지 확인
  2. 프론트매터에 name과 description이 포함되어 있는지 확인
  3. 모든 위치에서 스킬 이름이 고유한지 확인
  4. 권한 확인: deny 권한이 있는 스킬은 에이전트에서 숨겨집니다
Ctrl+I