Suporte a Links Simbólicos

O Que Você Vai Aprender

Entender o valor central e os cenários de aplicação de links simbólicos
Dominar o comando ln -s para criar links simbólicos
Compreender como o OpenSkills processa automaticamente links simbólicos
Implementar atualização automática de skills baseada em git
Desenvolver skills localmente de forma eficiente
Lidar com links simbólicos corrompidos

Pré-requisitos

Este tutorial assume que você já conhece Detalhes das Fontes de Instalação e Instalando Sua Primeira Skill, entendendo o fluxo básico de instalação de skills.

Seu Problema Atual

Você pode já ter aprendido a instalar e atualizar skills, mas enfrenta os seguintes problemas ao usar links simbólicos:

Atualização complicada no desenvolvimento local: Após modificar uma skill, é necessário reinstalar ou copiar arquivos manualmente
Dificuldade em compartilhar skills entre projetos: A mesma skill usada em vários projetos requer sincronização manual a cada atualização
Gerenciamento de versão confuso: Arquivos de skills dispersos em diferentes projetos, difíceis de gerenciar uniformemente com git
Fluxo de atualização trabalhoso: Atualizar skills de um repositório git requer reinstalar todo o repositório

Na verdade, o OpenSkills suporta links simbólicos, permitindo que você use symlinks para atualização automática de skills baseada em git e um fluxo de trabalho eficiente de desenvolvimento local.

Quando Usar Esta Técnica

Cenários de Aplicação para Links Simbólicos:

Cenário	Precisa de Link Simbólico?	Exemplo
Desenvolvimento local de skills	✅ Sim	Desenvolver skills personalizadas com modificações e testes frequentes
Compartilhamento de skills entre projetos	✅ Sim	Repositório de skills compartilhado pela equipe, usado em múltiplos projetos
Atualização automática baseada em git	✅ Sim	Após atualização do repositório de skills, todos os projetos recebem a versão mais recente automaticamente
Instalar uma vez, usar para sempre	❌ Não	Apenas instalar sem modificar, use `install` diretamente
Testar skills de terceiros	❌ Não	Testar skills temporariamente, não precisa de link simbólico

Práticas Recomendadas

Use links simbólicos para desenvolvimento local: Ao desenvolver suas próprias skills, use symlinks para evitar cópias repetidas
Use git + symlink para compartilhamento em equipe: Repositório de skills da equipe no git, compartilhado via symlink em cada projeto
Use instalação normal para produção: Em implantações estáveis, use install normal para evitar dependência de diretórios externos

Conceito Central: Link em Vez de Cópia

Método de Instalação Tradicional:

┌─────────────────┐
│ Repositório Git │
│ ~/dev/skills/   │
│ └── my-skill/   │
└────────┬────────┘
         │ cópia
         ▼
┌─────────────────┐
│ .claude/skills/ │
│ └── my-skill/   │
│     └── cópia   │
│       completa  │
└─────────────────┘

Problema: Após atualização do repositório Git, a skill em .claude/skills/ não é atualizada automaticamente.

Método de Link Simbólico:

┌─────────────────┐
│ Repositório Git │
│ ~/dev/skills/   │
│ └── my-skill/   │ ← arquivos reais aqui
└────────┬────────┘
         │ link simbólico (ln -s)
         ▼
┌─────────────────┐
│ .claude/skills/ │
│ └── my-skill/   │ → aponta para ~/dev/skills/my-skill
└─────────────────┘

Vantagem: Após atualização do repositório Git, o conteúdo apontado pelo link simbólico é atualizado automaticamente, sem necessidade de reinstalação.

Conceito Importante

Link Simbólico (Symlink): Um tipo especial de arquivo que aponta para outro arquivo ou diretório. O OpenSkills reconhece automaticamente links simbólicos ao buscar skills e segue para o conteúdo real. Links simbólicos corrompidos (apontando para destinos inexistentes) são ignorados automaticamente, não causando falhas.

Implementação do Código Fonte (src/utils/skills.ts:10-25):

typescript

function isDirectoryOrSymlinkToDirectory(entry: Dirent, parentDir: string): boolean {
  if (entry.isDirectory()) {
    return true;
  }
  if (entry.isSymbolicLink()) {
    try {
      const fullPath = join(parentDir, entry.name);
      const stats = statSync(fullPath); // statSync segue symlinks
      return stats.isDirectory();
    } catch {
      // Link simbólico corrompido ou erro de permissão
      return false;
    }
  }
  return false;
}

Pontos-chave:

entry.isSymbolicLink() detecta links simbólicos
statSync() segue automaticamente links simbólicos até o destino
try/catch captura links simbólicos corrompidos, retornando false para ignorar

Siga os Passos

Passo 1: Criar Repositório de Skills

Por quê Crie primeiro um repositório git para armazenar skills, simulando um cenário de compartilhamento em equipe.

Abra o terminal e execute:

bash

# Criar diretório do repositório de skills
mkdir -p ~/dev/my-skills
cd ~/dev/my-skills

# Inicializar repositório git
git init

# Criar uma skill de exemplo
mkdir -p my-first-skill
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Uma skill de exemplo para demonstrar suporte a symlinks
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
EOF

# Commit no git
git add .
git commit -m "Initial commit: Add my-first-skill"

Você deve ver: Repositório git criado com sucesso e skill commitada.

Explicação:

Skills armazenadas no diretório ~/dev/my-skills/
Gerenciamento de versão com git, facilitando colaboração em equipe
Este diretório é a "localização real" das skills

Passo 2: Criar Link Simbólico

Por quê Aprenda a usar o comando ln -s para criar links simbólicos.

Continue executando no diretório do projeto:

bash

# Voltar para o diretório raiz do projeto
cd ~/my-project

# Criar diretório de skills
mkdir -p .claude/skills

# Criar link simbólico
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Visualizar link simbólico
ls -la .claude/skills/

Você deve ver:

.claude/skills/
└── my-first-skill -> /Users/yourname/dev/my-skills/my-first-skill

Explicação:

ln -s cria um link simbólico
-> mostra o caminho real apontado
O link simbólico em si é apenas um "ponteiro", não ocupa espaço real

Passo 3: Verificar Funcionamento do Link Simbólico

Por quê Confirme que o OpenSkills consegue reconhecer e ler corretamente skills via link simbólico.

Execute:

bash

# Listar skills
npx openskills list

# Ler conteúdo da skill
npx openskills read my-first-skill

Você deve ver:

my-first-skill (project)
Uma skill de exemplo para demonstrar suporte a symlinks

Summary: 1 project, 0 global (1 total)

Saída da leitura da skill:

markdown

---
name: my-first-skill
description: Uma skill de exemplo para demonstrar suporte a symlinks
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"

Explicação:

O OpenSkills reconhece automaticamente links simbólicos
Skills via link simbólico exibem a tag (project)
O conteúdo lido vem do arquivo original apontado pelo link simbólico

Passo 4: Atualização Automática Baseada em Git

Por quê Experimente a maior vantagem dos links simbólicos: sincronização automática após atualização do repositório git.

Modifique a skill no repositório de skills:

bash

# Entrar no repositório de skills
cd ~/dev/my-skills

# Modificar conteúdo da skill
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Versão atualizada com novos recursos
---

# My First Skill (Updated)

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
3. NEW: This feature was updated via git!
EOF

# Commit da atualização
git add .
git commit -m "Update skill: Add new feature"

Agora verifique a atualização no diretório do projeto:

bash

# Voltar para o diretório do projeto
cd ~/my-project

# Ler skill (sem necessidade de reinstalação)
npx openskills read my-first-skill

Você deve ver: O conteúdo da skill foi atualizado automaticamente, incluindo a descrição do novo recurso.

Explicação:

Após atualização dos arquivos apontados pelo link simbólico, o OpenSkills lê automaticamente o conteúdo mais recente
Não é necessário executar openskills install novamente
Implementa "atualize uma vez, efetive em todos os lugares"

Passo 5: Compartilhamento de Skills Entre Múltiplos Projetos

Por quê Experimente a vantagem dos links simbólicos em cenários de múltiplos projetos, evitando instalação repetida de skills.

Crie um segundo projeto:

bash

# Criar segundo projeto
mkdir ~/my-second-project
cd ~/my-second-project

# Criar diretório de skills e link simbólico
mkdir -p .claude/skills
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Verificar se a skill está disponível
npx openskills list

Você deve ver:

my-first-skill (project)
Versão atualizada com novos recursos

Summary: 1 project, 0 global (1 total)

Explicação:

Múltiplos projetos podem criar links simbólicos apontando para a mesma skill
Após atualização do repositório de skills, todos os projetos recebem a versão mais recente automaticamente
Evita instalação e atualização repetida de skills

Passo 6: Lidar com Links Simbólicos Corrompidos

Por quê Entenda como o OpenSkills lida elegantemente com links simbólicos corrompidos.

Simule um link simbólico corrompido:

bash

# Remover repositório de skills
rm -rf ~/dev/my-skills

# Tentar listar skills
npx openskills list

Você deve ver: Links simbólicos corrompidos são ignorados automaticamente, sem gerar erro.

Summary: 0 project, 0 global (0 total)

Explicação:

O try/catch no código fonte captura links simbólicos corrompidos
O OpenSkills ignora links corrompidos e continua buscando outras skills
Não causa falha no comando openskills

Checkpoint ✅

Complete as seguintes verificações para confirmar que você dominou o conteúdo desta lição:

[ ] Entender o valor central dos links simbólicos
[ ] Dominar o uso do comando ln -s
[ ] Entender a diferença entre links simbólicos e cópia de arquivos
[ ] Ser capaz de criar repositórios de skills baseados em git
[ ] Implementar atualização automática de skills
[ ] Saber como compartilhar skills entre múltiplos projetos
[ ] Entender o mecanismo de tratamento de links simbólicos corrompidos

Alertas de Problemas Comuns

Erro Comum 1: Caminho do Link Simbólico Incorreto

Cenário de Erro: Usar caminho relativo para criar link simbólico, link falha após mover o projeto.

bash

# ❌ Errado: usando caminho relativo
cd ~/my-project
ln -s ../dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Mover projeto após criação do link
mv ~/my-project ~/new-location/project
npx openskills list # ❌ skill não encontrada

Problema:

Caminhos relativos dependem do diretório de trabalho atual
Após mover o projeto, caminhos relativos falham
Link simbólico aponta para local incorreto

Prática Correta:

bash

# ✅ Correto: usar caminho absoluto
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Continua funcionando após mover o projeto
mv ~/my-project ~/new-location/project
npx openskills list # ✅ skill ainda encontrada

Erro Comum 2: Confundir Hard Link com Link Simbólico

Cenário de Erro: Usar hard link em vez de link simbólico.

bash

# ❌ Errado: usando hard link (sem parâmetro -s)
ln ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Hard link é outra entrada do arquivo, não um ponteiro
# Não consegue "atualizar um lugar, efetivar em todos"

Problema:

Hard link é outro nome de entrada para o arquivo
Modificar qualquer hard link atualiza todos os outros hard links
Mas após remover o arquivo fonte, o hard link ainda existe, causando confusão
Não pode ser usado entre sistemas de arquivos diferentes

Prática Correta:

bash

# ✅ Correto: usar link simbólico (com parâmetro -s)
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# Link simbólico é um ponteiro
# Após remover o arquivo fonte, o link simbólico falha (OpenSkills ignora)

Erro Comum 3: Link Simbólico Apontando para Local Errado

Cenário de Erro: Link simbólico aponta para o diretório pai da skill, não para o diretório da skill em si.

bash

# ❌ Errado: apontando para diretório pai
ln -s ~/dev/my-skills .claude/skills/my-skills-link

# OpenSkills procura SKILL.md em .claude/skills/my-skills-link/
# Mas SKILL.md real está em ~/dev/my-skills/my-first-skill/SKILL.md

Problema:

O OpenSkills procura <link>/SKILL.md
Mas a skill real está em <link>/my-first-skill/SKILL.md
Resulta em arquivo de skill não encontrado

Prática Correta:

bash

# ✅ Correto: apontar diretamente para o diretório da skill
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# OpenSkills procura .claude/skills/my-first-skill/SKILL.md
# Link simbólico aponta para diretório que contém SKILL.md

Erro Comum 4: Esquecer de Sincronizar AGENTS.md

Cenário de Erro: Criar link simbólico mas esquecer de sincronizar AGENTS.md.

bash

# Criar link simbólico
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ❌ Errado: esquecer de sincronizar AGENTS.md
# Agente AI não sabe que há nova skill disponível

Problema:

Link simbólico criado, mas AGENTS.md não atualizado
Agente AI não sabe da nova skill
Não consegue invocar a nova skill

Prática Correta:

bash

# Criar link simbólico
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ✅ Correto: sincronizar AGENTS.md
npx openskills sync

# Agora o agente AI pode ver a nova skill

Resumo da Lição

Pontos-chave:

Link simbólico é um ponteiro: Criado com ln -s, aponta para arquivo ou diretório real
Seguimento automático de links: O OpenSkills usa statSync() para seguir links simbólicos automaticamente
Links corrompidos ignorados automaticamente: try/catch captura exceções, evitando falhas
Atualização automática baseada em git: Após atualização do repositório Git, skills sincronizam automaticamente
Compartilhamento entre múltiplos projetos: Múltiplos projetos podem criar links simbólicos apontando para a mesma skill

Fluxo de Decisão:

[Precisa usar skill] → [Precisa modificar frequentemente?]
                             ↓ Sim
              [Usar link simbólico (desenvolvimento local)]
                             ↓ Não
              [Vários projetos compartilham?]
                             ↓ Sim
              [Usar git + link simbólico]
                             ↓ Não
              [Usar install normal]

Mnemônico:

Desenvolvimento local use symlink: Modificações frequentes, evita cópias repetidas
Compartilhamento em equipe use git + link: Atualize uma vez, efetive em todos os lugares
Caminho absoluto garante estabilidade: Evite falhas de caminhos relativos
Links corrompidos ignorados automaticamente: OpenSkills processa automaticamente

Próxima Lição

Na próxima lição aprenderemos Criando Skills Personalizadas.
Você vai aprender:
Como criar suas próprias skills do zero
Entender o formato SKILL.md e YAML frontmatter
Como organizar a estrutura de diretórios de skills (references/, scripts/, assets/)
Como escrever descrições de skills de alta qualidade

Apêndice: Referência do Código Fonte

Clique para expandir e ver localização do código fonte

Última atualização: 2026-01-24

Funcionalidade	Caminho do Arquivo	Linhas
Detecção de link simbólico	`src/utils/skills.ts`	10-25
Busca de skills	`src/utils/skills.ts`	30-64
Busca de skill individual	`src/utils/skills.ts`	69-84

Funções-chave:

isDirectoryOrSymlinkToDirectory(entry, parentDir): Determina se a entrada é um diretório real ou um link simbólico apontando para um diretório
Usa entry.isSymbolicLink() para detectar links simbólicos
Usa statSync() para seguir automaticamente links simbólicos até o destino
try/catch captura links simbólicos corrompidos, retornando false
findAllSkills(): Busca todas as skills instaladas
Percorre 4 diretórios de busca
Chama isDirectoryOrSymlinkToDirectory para identificar links simbólicos
Ignora automaticamente links simbólicos corrompidos

Regras de Negócio:

Links simbólicos são reconhecidos automaticamente como diretórios de skills
Links simbólicos corrompidos são ignorados elegantemente, não causando falhas
Links simbólicos e diretórios reais têm a mesma prioridade de busca

Suporte a Links Simbólicos ​

O Que Você Vai Aprender ​

Seu Problema Atual ​

Quando Usar Esta Técnica ​

Conceito Central: Link em Vez de Cópia ​

Siga os Passos ​

Passo 1: Criar Repositório de Skills ​

Passo 2: Criar Link Simbólico ​

Passo 3: Verificar Funcionamento do Link Simbólico ​

Passo 4: Atualização Automática Baseada em Git ​

Passo 5: Compartilhamento de Skills Entre Múltiplos Projetos ​

Passo 6: Lidar com Links Simbólicos Corrompidos ​

Checkpoint ✅ ​

Alertas de Problemas Comuns ​

Erro Comum 1: Caminho do Link Simbólico Incorreto ​

Erro Comum 2: Confundir Hard Link com Link Simbólico ​

Erro Comum 3: Link Simbólico Apontando para Local Errado ​

Erro Comum 4: Esquecer de Sincronizar AGENTS.md ​

Resumo da Lição ​

Próxima Lição ​

Apêndice: Referência do Código Fonte ​

Suporte a Links Simbólicos

O Que Você Vai Aprender

Seu Problema Atual

Quando Usar Esta Técnica

Conceito Central: Link em Vez de Cópia

Siga os Passos

Passo 1: Criar Repositório de Skills

Passo 2: Criar Link Simbólico

Passo 3: Verificar Funcionamento do Link Simbólico

Passo 4: Atualização Automática Baseada em Git

Passo 5: Compartilhamento de Skills Entre Múltiplos Projetos

Passo 6: Lidar com Links Simbólicos Corrompidos

Checkpoint ✅

Alertas de Problemas Comuns

Erro Comum 1: Caminho do Link Simbólico Incorreto

Erro Comum 2: Confundir Hard Link com Link Simbólico

Erro Comum 3: Link Simbólico Apontando para Local Errado

Erro Comum 4: Esquecer de Sincronizar AGENTS.md

Resumo da Lição

Próxima Lição

Apêndice: Referência do Código Fonte