副驾驶指令

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

创建或更新存储库文件 .github/copilot-instructions.md 创建或更新可重用知识 SKILL.md 创建或更新专门角色 .agent.md 按文件路径配置指令 (.instructions.md)

Copilot CLI 指令类型

类型 · 文件 · 全局范围 · ~/.copilot/instructions.md · 所有用户会话 存储库 · .github/copilot-instructions.md · 整个存储库 按路径 · .github/instructions/*.instructions.md,前面有 applyTo · 技能特定文件 · skills/<name>/SKILL.md · 由代理按需加载

格式:副驾驶指令.md

存储库全局指令文件。您必须定义:

格式:技能.md

可重用的程序知识。强制性最低前置内容:可选字段:type: skill、targets: [copilot-cli]。 SKILL.md 的正文必须包含: 何时使用 — 精确的触发器 检查表或工作流程 — 可执行的分步指南

格式:.agent.md

具有自己背景的孤立角色。强制前置事项:.agent.md 的关键规则:必须完整 — 人物角色 + 工作流程 + 永不做的事 + 升级协议 无提示 — 不要写“使用技能 X 了解细节”;将必需品纳入内联 最小工具 - 仅列出代理真正需要的工具

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Copilot Instructions

> ⚠️ EXPERIMENTAL — Ainda não validado em produção.

## Quando Usar

- Criar ou atualizar o arquivo `.github/copilot-instructions.md` do repositório
- Criar ou atualizar uma `SKILL.md` de conhecimento reutilizável
- Criar ou atualizar um `.agent.md` de persona especializada
- Configurar instruções por caminho de arquivo (`.instructions.md`)

## Tipos de Instrução Copilot CLI

| Tipo | Arquivo | Escopo |
|------|---------|--------|
| Global | `~/.copilot/instructions.md` | Todas as sessões do usuário |
| Repositório | `.github/copilot-instructions.md` | Todo o repositório |
| Por caminho | `.github/instructions/*.instructions.md` com `applyTo` no frontmatter | Arquivos específicos |
| Skill | `skills/<name>/SKILL.md` | Carregada sob demanda por agente |
| Agent | `agents/<name>.agent.md` | Contexto isolado do subagente |

## Formato: copilot-instructions.md

Arquivo de instruções globais do repositório. Deve definir:

```markdown
# [Nome do Projeto] — Copilot Instructions

## Contexto
[O que é o projeto, stack principal, idioma de resposta]

## Convenções
[Convenções de código, nomenclatura, padrões obrigatórios]

## Protocolo de Resposta
[Como o agente deve trabalhar — etapas, aprovação, registro]

## Roster de Agentes
[Tabela de agentes disponíveis e quando chamar cada um]

## Nunca Faça
[Anti-padrões explícitos para este repositório]
```

## Formato: SKILL.md

Conhecimento procedural reutilizável. Frontmatter mínimo obrigatório:

```yaml
---
name: skill-name
description: Quando usar esta skill em uma frase precisa.
license: MIT
---
```

Campos opcionais: `type: skill`, `targets: [copilot-cli]`.

Corpo do SKILL.md deve conter:
- **Quando Usar** — gatilhos precisos
- **Checklist ou Workflow** — passo-a-passo executável
- **Padrões** — código de referência, exemplos
- **Nunca Faça** — anti-padrões explícitos

## Formato: .agent.md

Persona isolada com contexto próprio. Frontmatter obrigatório:

```yaml
---
name: agent-name
description: [Persona]. Use quando [gatilho preciso].
tools: ["read", "search", "edit"]
---
```

Regras críticas para `.agent.md`:
- **Deve ser COMPLETO** — persona + workflow + nunca-faz + protocolo de escalamento
- **Sem ponteiros** — não escrever "use a skill X para detalhes"; incorporar o essencial inline
- **Ferramentas mínimas** — listar só as tools que o agente realmente precisa
- **Persona forte** — o agente deve ter uma voz e perspectiva clara

Corpo do `.agent.md` deve conter:
- Identidade e papel
- Perguntas de discovery (se aplicável)
- Workflow passo-a-passo
- Protocolo de escalamento
- O que nunca fazer

## Formato: Path-Specific Instructions

```yaml
---
applyTo: "**/*.test.ts"
---

# Instruções para arquivos de teste TypeScript

[Convenções específicas para este tipo de arquivo]
```

## Quando Usar Cada Tipo

| Cenário | Tipo de instrução |
|---------|------------------|
| Convenções globais do projeto | `copilot-instructions.md` |
| Regras para um tipo de arquivo específico | Path-specific `.instructions.md` |
| Conhecimento de domínio reutilizável | `SKILL.md` |
| Persona com workflow completo | `.agent.md` |

## Checklist de Qualidade

Para qualquer instrução criada:
- [ ] Frontmatter com `name` e `description` preenchidos
- [ ] Conteúdo em pt-BR (padrão deste repositório)
- [ ] Sem TODO ou placeholder vazio no conteúdo
- [ ] Instruções executáveis, não só conceituais
- [ ] Sem repetição de conteúdo já em outra instrução
- [ ] Tag `⚠️ EXPERIMENTAL` se ainda não validado em produção

## Passos

### 1. Identificar o escopo da instrução

Determinar onde a instrução deve atuar — usar `## Quando Usar Cada Tipo` como guia:
- Afeta todo repositório → `.github/copilot-instructions.md`
- Afeta diretório específico → `.instructions.md`
- Capacidade reutilizável → `SKILL.md`
- Persona com fluxo → `.agent.md`

### 2. Escrever o frontmatter YAML

Consultar o formato correspondente em `## Formato: SKILL.md` ou `## Formato: .agent.md`.
Campos mínimos obrigatórios: `name`, `description`.

### 3. Estruturar o conteúdo

Para **Skills**: seguir as seções obrigatórias de `## Formato: SKILL.md`:
1. Quando Usar
2. Passos/Procedimento
3. Exemplos ou Templates
4. Checklist de validação

Para **Agents**: seguir as seções obrigatórias:
1. Persona
2. Metodologia
3. Protocolo de Escalamento
4. Fluxo de Trabalho
5. Nunca Faça

### 4. Validar com checklist

Completar o `## Checklist de Qualidade` abaixo antes de commitar.

### 5. Registrar no repositório

```bash
# Posicionar o arquivo no local correto
# Para agents e skills neste repositório:
skills/.experimental/agents/nome.agent.md
skills/.experimental/skills/nome/SKILL.md
```

## Exemplos

### SKILL.md mínimo válido

```markdown
---
name: minha-skill
description: Use quando precisar [contexto de uso]. Fornece [o que entrega].
license: MIT
---

# Minha Skill

## Quando Usar

- Situação A que justifica uso
- Situação B que justifica uso

## Passos

### 1. Primeiro passo
Descrição acionável.

### 2. Segundo passo
Descrição acionável.

## Checklist de validação

- [ ] Critério 1
- [ ] Critério 2
```

### .agent.md mínimo válido

```markdown
---
name: meu-agente
description: Papel do agente. Use quando precisar [contexto].
tools: ["read", "search", "edit", "todo"]
user-invocable: true
type: agent
targets: [copilot-cli]
license: MIT
infer: true
---

# Meu Agente

## Persona

[1-3 linhas descrevendo a persona e princípio central]

## Metodologia

[Seções técnicas específicas do domínio]

## Protocolo de Escalamento

[Quando e como escalar]

## Fluxo de Trabalho

[Passos numerados]

## Nunca Faça

[Proibições explícitas]
```

---
> Source: [ATNexusLab/skills](https://github.com/ATNexusLab/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。