Dropstone Docs

Habilidades do Agente

Defina comportamento reutilizável via definições SKILL.md

As habilidades do agente permitem que o Dropstone descubra instruções reutilizáveis do seu repositório ou diretório inicial. As habilidades são carregadas sob demanda através da ferramenta skill integrada: os agentes veem quais habilidades estão disponíveis e podem carregar o conteúdo completo quando uma corresponde à tarefa.

Coloque os arquivos

Crie uma pasta por nome de habilidade e coloque um SKILL.md dentro dela. O Dropstone procura nestes locais:

  • Configuração do projeto: .dropstone/skills/<name>/SKILL.md
  • Configuração global: ~/.config/dropstone/skills/<name>/SKILL.md
  • Compatível com Claude do projeto: .claude/skills/<name>/SKILL.md
  • Compatível com Claude global: ~/.claude/skills/<name>/SKILL.md
  • Compatível com agente do projeto: .agents/skills/<name>/SKILL.md
  • Compatível com agente global: ~/.agents/skills/<name>/SKILL.md

Entenda a descoberta

Para caminhos locais do projeto, o Dropstone sobe a partir do seu diretório de trabalho atual até atingir a árvore de trabalho do git. Ele carrega qualquer skills/*/SKILL.md correspondente em .dropstone/ e qualquer .claude/skills/*/SKILL.md ou .agents/skills/*/SKILL.md correspondente ao longo do caminho.

As definições globais também são carregadas de ~/.config/dropstone/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md e ~/.agents/skills/*/SKILL.md.

Escreva o frontmatter

Cada SKILL.md deve começar com frontmatter YAML. Apenas estes campos são reconhecidos:

  • name (obrigatório)
  • description (obrigatório)
  • license (opcional)
  • compatibility (opcional)
  • metadata (opcional, mapa de string para string)

Campos de frontmatter desconhecidos são ignorados.

Valide nomes

name deve:

  • Ter 1–64 caracteres
  • Ser alfanumérico em minúsculas com separadores de hífen único
  • Não começar ou terminar com -
  • Não conter -- consecutivos
  • Corresponder ao nome do diretório que contém SKILL.md

Regex equivalente:

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

Siga as regras de comprimento

description deve ter 1-1024 caracteres. Mantenha-a específica o suficiente para o agente escolher corretamente.

Use um exemplo

Crie .dropstone/skills/git-release/SKILL.md assim:

---
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.

Reconheça a descrição da ferramenta

O Dropstone lista as habilidades disponíveis na descrição da ferramenta skill. Cada entrada inclui o nome da habilidade e a descrição:

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

O agente carrega uma habilidade chamando a ferramenta:

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

Configure permissões

Controle quais habilidades os agentes podem acessar usando permissões baseadas em padrões em dropstone.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
PermissãoComportamento
allowHabilidade carregada imediatamente
denyHabilidade oculta do agente, acesso rejeitado
askUsuário solicitado para aprovação antes de carregar

Padrões suportam curingas: internal-* corresponde a internal-docs, internal-tools, etc.

Substitua por agente

Dê a agentes específicos permissões diferentes das configurações padrão globais.

Para agentes personalizados (no frontmatter do agente):

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

Para agentes integrados (em dropstone.json):

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

Desabilite a ferramenta de habilidade

Desabilite completamente as habilidades para agentes que não devem usá-las:

Para agentes personalizados:

---
tools:
  skill: false
---

Para agentes integrados:

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

Quando desabilitada, a seção <available_skills> é omitida inteiramente.

Solucione problemas de carregamento

Se uma habilidade não aparecer:

  1. Verifique se SKILL.md está escrito em maiúsculas
  2. Verifique se o frontmatter inclui name e description
  3. Certifique-se de que os nomes das habilidades são únicos em todos os locais
  4. Verifique as permissões: habilidades com deny estão ocultas dos agentes
Ctrl+I