Claude Code Skills, explicadas de forma simples

Autoria: Agentic Lab · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: Claude Code Skills, Explained Simply. · Canal: Agentic Lab · 15:21 · Assistir no YouTube

Tópicos: Agentes de IA, Automação de tarefas e workflows, Claude Code, Engenharia de prompts e contexto, Engenharia de software com IA

Resumo

O vídeo explica que uma skill é uma pasta de arquivos que fornece instruções e recursos ao Claude Code, por meio de invocação do usuário ou do modelo. O apresentador mostra como combinar arquivos Markdown, scripts e hooks para tornar as skills mais úteis, consistentes e determinísticas. Também apresenta opções de configuração, como limitar ferramentas, usar argumentos e executar skills em contextos separados. Por fim, demonstra uma skill de auditoria que verifica problemas mecânicos com scripts e pede ao modelo que avalie aspectos que exigem julgamento.

Pontos-chave

Skills podem ser ativadas por um comando do usuário ou escolhidas pelo modelo com base em uma descrição carregada no contexto.
Na divulgação progressiva, a descrição fica disponível ao modelo, enquanto o conteúdo da skill só é carregado quando necessário.
O valor de uma skill está principalmente no conhecimento específico do usuário ou da equipe, não no mecanismo de ativação.
Uma skill pode ser uma pasta com arquivos Markdown e scripts, compartilhada com a equipe pelo repo.
Scripts devem executar as partes que podem ser determinísticas; o agent pode coordenar os scripts e decidir os próximos passos.
Hooks configurados por uma skill continuam ativos até o fim da sessão.
Skills podem restringir ferramentas, executar comandos durante o carregamento, incluir arquivos e aceitar argumentos.
A execução em contexto separado pode economizar contexto principal quando só é necessário o resultado da skill.
Skills longas, com muitas regras ou instruções contraditórias, podem consumir contexto e ser difíceis de seguir.
O apresentador recomenda desativar a invocação pelo modelo por padrão, a menos que seja desejável que ele escolha a skill por conta própria.

Capítulos

Início	Capítulo	Resumo
00:00	O que é uma skill e como ela é ativada	O vídeo define skills como arquivos de instrução carregados no contexto e diferencia a invocação pelo usuário da invocação pelo modelo.
02:37	Conhecimento próprio, pastas e determinismo	O apresentador explica por que skills específicas de uma equipe são valiosas e como combinar scripts com instruções para reduzir comportamentos probabilísticos.
04:13	Hooks, ferramentas, comandos e argumentos	São apresentados recursos de configuração, como hooks, restrições de ferramentas, execução de comandos no carregamento, inclusão de arquivos e argumentos.
06:51	Exemplo de uma skill de auditoria	O apresentador demonstra configurações para desativar a invocação pelo modelo, separar o contexto, escolher um modelo e limitar ferramentas.
09:01	Verificações determinísticas da auditoria	A skill usa scripts para localizar a skill-alvo e verificar metadados, tamanho, caminhos de arquivos e outras condições.
12:42	Análise do modelo e recomendações finais	O modelo avalia clareza, redundâncias e instruções que poderiam ser scripts ou hooks, e o apresentador recomenda auditar as skills existentes.

Citações

Uma skill é um arquivo Markdown que é inserido no contexto. — 00:00

Qualquer coisa que possa ser roteirizada será um script. — 04:13

O que a skill faz, em uma frase? — 12:42

Isso poderia ser um script? Isso poderia ser um hook? — 15:21

Conceitos e entidades

Claude Code (ferramenta): Ferramenta de programação da Anthropic cuja arquitetura de skills é explicada no vídeo.
skill (conceito): Conjunto de instruções e recursos, geralmente em uma pasta, que pode ser carregado no contexto do agent.
progressive disclosure (conceito): Padrão em que uma descrição da skill fica disponível e seu conteúdo completo só é carregado quando necessário.
hook (conceito): Ação que pode ser executada em resposta a um evento, como o envio de um prompt, e que pode ser registrada por uma skill.
script (conceito): Programa usado para executar de forma determinística tarefas que não precisam de julgamento de um modelo.
context fork (conceito): Execução de uma skill em um contexto separado, cujo resultado pode ser devolvido ao agent principal.
skill audit (conceito): Processo de verificar uma skill em busca de problemas mecânicos e de clareza, tamanho ou desenho.
Roman (pessoa): Apresentador do vídeo, que descreve sua abordagem para criar e auditar skills.
Matt Pocock (pessoa): Criador da skill “grill me” mencionada como exemplo no vídeo.
Anthropic (empresa): Empresa cujas recomendações e comportamento do Claude Code são mencionados na demonstração.
Opus (modelo): Modelo que o apresentador seleciona como exemplo de configuração para uma skill.
NeurIPS (conceito): Conferência de IA mencionada pelo apresentador ao se apresentar.

Tradução completa (pt-BR)

00:00 Desde que surgiram, as skills são o recurso favorito de todo mundo no Claude Code, e todo mundo fala delas como se fossem algum tipo de truque mágico. Mas uma skill é, sem dúvida, a parte mais simples do Claude Code. É um arquivo Markdown que é inserido no contexto, e é exatamente por isso que quase todo mundo as subutiliza. As pessoas param na primeira coisa que uma skill pode fazer, que é armazenar um prompt, e nunca mexem nos controles que a tornam algo mais versátil. Neste vídeo, vou definir exatamente o que é uma skill partindo dos primeiros princípios, mostrar a arquitetura por trás dela e como criar skills eficazes. Ao final,

00:33 você vai conseguir entender e criar skills mais baratas, rápidas e consistentes, que realizem qualquer tipo de trabalho de conhecimento que você escolher. Eu sou Roman. Publiquei um artigo entre os 3% melhores na NeurIPS, a maior conferência de IA do mundo. Agora, estou em uma missão para levar os agentes de programação ao limite absoluto. Então, vamos começar reiterando o que é uma skill. Uma skill é um arquivo Markdown que o usuário ou o agent pode inserir no contexto do agent. As skills são acionadas de duas formas: pelo modelo ou pelo usuário.

01:03 A maneira mais simples de usar skills é acioná-las pelo usuário. Imagine que você queira salvar um prompt e inseri-lo em um LLM sempre que digitar um comando específico, como {barra} analyze. Assim que você digita isso, o prompt armazenado é inserido diretamente na context window do Claude Code, junto com qualquer complemento que você tenha escrito depois do comando {barra}. Certo, é bem simples. Depois, temos o acionamento pelo modelo, que é o segundo tipo. Imagine que queremos que o modelo decida quando ele

01:34 deve carregar uma skill no próprio contexto. Bem, o modelo precisa saber que pode fazer isso, que isso é uma possibilidade. Então, logo no início de cada sessão, inserimos uma pequena descrição da skill e de quando ela deve ser acionada para ser carregada. Dizemos isso ao LLM para que ele possa decidir se deve fazê-lo. Essa descrição fica sempre carregada no contexto, e o corpo só é carregado quando o modelo realmente precisa dele. É isso que chamamos de divulgação progressiva. Mas isso é uma faca de dois gumes, porque

02:05 quanto mais skills que podem ser acionadas pelo modelo você acumula na sua configuração, mais essas descrições sempre ativas se tornam uma distração. Por isso, na maioria das minhas skills, desativo o acionamento pelo modelo, para que a descrição nem sequer seja carregada no contexto. E pronto. Skills são literalmente tão simples quanto isso. Você armazena um prompt em um arquivo Markdown e, ou o insere com um comando de barra, ou indica que ele existe e deixa o modelo decidir quando inseri-lo no próprio contexto. E, se é tão simples assim, então o mecanismo não é onde está o valor. O valor está no que você coloca na própria skill.

02:37 As skills se destacam quando contêm conhecimento que só existe na sua cabeça ou na sua equipe. Como sua base de código faz o deploy, do que seu cliente precisa, o jeito como você gosta de trabalhar. E nenhuma skill genérica do GitHub serve para todo mundo e contém essas informações. Então, o segredo é saber criar suas próprias skills para você e sua equipe. Uma observação sobre o que uma skill realmente é: ela não precisa ser apenas um arquivo. É uma pasta, e essa pasta é a unidade inteira que você compartilha. Então, você pode colocar scripts junto do Markdown e referenciá-los na skill por meio de uma

03:09 variável, e o Claude Code a substitui pelo caminho real da pasta antes que o modelo leia a linha. Isso nos permite transportar e referenciar scripts independentemente de em qual máquina a skill está sendo executada. É isso que torna essas skills tão poderosas para equipes internas. Sem isso, compartilhar uma skill significaria compartilhar uma pasta junto com um parágrafo de instruções de configuração, e cada chamada de script abriria uma janela pop-up. Com isso, você faz commit da pasta em .cloud/skills do repo, e cada colega tem o workflow completo ao clonar o repo. Agora, rapidinho, quero falar sobre determinismo. No fundo, as skills são probabilísticas,

03:43 ou seja, não há garantia de que funcionem, já que dependem de um agent para executar os comportamentos certos. Isso é problemático porque elas são mais caras, menos confiáveis e demoram mais. Por outro lado, scripts são totalmente determinísticos. A solução para o caráter probabilístico das skills é torná-las o mais determinísticas possível, incorporando scripts em todos os lugares em que isso for possível ou fizer sentido dentro de uma skill. Então, uma regra a considerar ao criar ou avaliar skills

04:13 é perguntar: há alguma funcionalidade nesta skill que possa ser executada de forma totalmente determinística em um script, ou não? E é assim que eu uso uma skill. Tudo o que puder ser transformado em script será um script, e o Markdown ensinará o agent a executá-los e decidir o que vem a seguir. O agent funciona como uma cola entre os scripts. Essa é a essência das skills. Além disso, há alguns controles no front matter que a maioria das pessoas realmente nunca usa, e alguns são muito bons. Para começar, você pode colocar hooks dentro de uma skill, e eles só são registrados nas sessões em que aquela skill foi executada. Por exemplo, uma skill chamada {barra}

04:47 grill me record: você pegaria a skill grill me original do Matt Pocock, em que o modelo faz perguntas sobre suas especificações até ficar satisfeito, e instalaria um hook de envio de prompt do usuário. Assim, toda vez que você envia um prompt ao agent, um script é executado. Então, antes que qualquer execução de código aconteça, esse hook usaria uma expressão regular para registrar cada pergunta feita pelo modelo e cada resposta dada pelo usuário, adicionando-as de maneira determinística e instantânea à documentação da base de código chamada grill responses.md.

05:18 Isso resolveria o problema de muitas pessoas terem perguntas e respostas perdidas na sessão de um agent, e dá para resolver isso com esse padrão simples de colocar um hook dentro de uma skill. Agora, um detalhe: quando uma skill registra um hook, ele continua ativo pelo resto da sessão, não apenas durante a tarefa daquela skill. Você também pode permitir ou proibir ferramentas na primeira rodada do agent quando uma skill está ativa. Isso funciona como uma medida de segurança quando você quer impor um comportamento. Por exemplo, você pode proibir edit write dentro de uma

05:49 skill em que a única tarefa do agent é fazer uma análise somente leitura. Assim, você garante que o agent se comporte adequadamente. Em seguida, no Claude Code, o símbolo de exclamação transforma o comando em uma execução de bash. E isso também funciona em skills. Ou seja, você pode executar scripts ao carregar uma skill. O modelo nunca recebe o comando que você digitou. Em vez disso, recebe a saída desse comando inserida de forma determinística. Isso permite criar uma lógica muito mais dinâmica dentro das skills por um custo muito menor. E também impõe determinismo

06:20 dentro das suas skills. Outra dica: o símbolo de arroba insere na sua skill qualquer arquivo que você escolher. Isso é poderoso porque permite mudar o que é enviado ao modelo sem alterar a skill toda vez que algo muda. Por exemplo, se você executar uma skill {barra} analyze codebase, poderá inserir a história do usuário da sua base de código adicionando at doc {barra} user story.md. E, conforme essa história do usuário muda, você não precisa alterar a skill. A terceira coisa é que você pode adicionar argumentos às skills que

06:51 permitem que o usuário insira variáveis em determinados scripts ou contexto no modelo. Outra dica profissional: ao usar uma skill, você também pode escrever um prompt adicional, que será inserido no agent depois da skill. Certo, então como é uma skill na prática? Vamos começar com uma skill de auditoria de skills que criei. É um exemplo metalinguístico de uma skill que segue todas as boas convenções e pode ensinar uma ou duas coisas. Você também pode baixá-la para ajudar a desenvolver melhor suas skills.

07:25 processo. Você pode auditar suas skills. Então, a primeira coisa que quero destacar é que disable-model-invocation está ativado. Isso significa, mais uma vez, que o front matter dessa skill, que é essa descrição, não será incluído no contexto do modelo em nenhum momento. Se você definir como false, será. A próxima dica é que configurei o contexto para ser bifurcado aqui. Assim que você executar essa skill, ela vai bifurcar o contexto exato do seu agent, colocar a skill nele e executá-la em um subagent bifurcado; depois, vai mesclar tudo de volta no agent principal. Esse pode ser um padrão muito poderoso para

07:58 a eficiência de contexto, quando você não precisa que a skill seja executada no contexto principal do seu agent. Você só precisa da saída da skill. Neste caso, vamos deixá-la em primeiro plano, o que significa apenas que não teremos nossa sessão normal enquanto a skill estiver em execução. Se você quisesse definir background como true, isso faria o agent bifurcado rodar em segundo plano enquanto você continua sua sessão. Neste caso, não nos importamos em esperar. Você também pode atribuir um modelo às suas skills. Assim, no momento em que eu executar essa skill, ela vai bifurcar o contexto, mudar o modelo para Opus, mudar o nível de esforço para

08:30 médio e mantê-la em primeiro plano. Agora, você também pode ver que proibi o máximo possível de ferramentas para torná-la totalmente determinística, porque esta é uma skill somente de leitura. Não queremos que ela altere a skill, então garantimos isso por meio dessa restrição. Agora, vamos à própria skill. A primeira coisa a observar é que usamos o padrão do ponto de exclamação para executar scripts bash dentro da própria skill antes mesmo de ela chegar ao agent. Então, a primeira coisa que a skill vai fazer é executar o script bash skill enter

09:01 na skill que você escolher. Aliás, a skill escolhida é definida pelo usuário em target, então ele pode adicioná-la como argumento. Em seguida, o script será executado nessa skill. E, bem rápido, o que é skill enter? Bem, skill enter é um conjunto de lógicas que primeiro localiza a skill por um caminho ou pelo nome passado em um argumento. Depois, verifica se nenhum argumento foi fornecido; nesse caso, as instruções de uso serão impressas no contexto. Em seguida, verifica se a skill especificada literalmente pelo usuário é

09:32 realmente uma skill em .claude/skills ou em plugins, e precisa encontrar exatamente uma. Assim que o script a encontra, todas as verificações abaixo são feitas nessa pasta. Vamos passar pelas verificações determinísticas. Primeiro, ele vai ler o front matter e verificar cada chave. Se não houver front matter, isso significa que a skill será carregada sem descrição. Isso porque, no front matter, a primeira parte de uma skill precisa ter três traços. Basicamente, essa é uma forma de garantir que a skill esteja escrita corretamente. Você pode ver aqui em cima

10:02 que a minha descrição, na primeira linha, começa com esses três traços. Isso pode mudar se a Anthropic decidir mudar o que está fazendo. Se houver uma chave que o Claude Code não reconheça, ela será ignorada silenciosamente. Então, vamos registrar isso para o nosso agent na observação do linter. Se não houver descrição, vamos sinalizar isso para o modelo e avisá-lo também. Outra coisa a considerar é que, se a descrição e a seção “quando usar” tiverem mais de 1.536 caracteres, o texto será truncado quando for enviado ao modelo, o que pode ser

10:34 confuso. Então, ao auditar skills, queremos garantir de forma determinística que o texto tenha menos de 1.536 caracteres, para que ele não seja truncado sem que a gente saiba. Agora, esta é outra verificação muito importante. No caso das minhas skills, gosto de definir disable-model-invocation como true por padrão. Isso serve para proteger a atenção dos nossos modelos. Portanto, se disable-model-invocation estiver como false, queremos que isso seja sinalizado ao nosso agent durante a auditoria da skill, para podermos decidir. A próxima verificação seria para os casos em que recebemos argumentos, mas não damos ao usuário

11:08 nenhuma dica sobre esses argumentos. Certo, e outras coisas importantes para você e seu modelo saberem: os hooks de uma skill permanecem armados durante toda a sessão. Então, às vezes, isso pode ser perigoso. Além disso, se trocarmos de modelo, o cache de prompt será invalidado naquele turno, causando um carregamento extra e caro da skill. E, na verdade, o mesmo vale para o nível de esforço. A próxima verificação do linter é o tamanho de uma skill. Em alguns casos, skills com mais de 500 linhas podem ser muito perigosas. O motivo é que você está injetando muito

11:39 contexto nos seus agents. Você pode definir esse limite como mil. A recomendação oficial da Anthropic é ficar abaixo de 500. Outra coisa a observar: se a skill tiver mais de 5.000 tokens no total, os primeiros 5.000 tokens vão sobreviver à compactação automática, mas o restante será descartado silenciosamente. É muito importante pelo menos saber disso. Agora, outras verificações: vamos verificar de forma determinística todos os caminhos de scripts e arquivos incluídos. Se um arquivo for referenciado apenas pelo nome, isso pode não funcionar em outra máquina. É muito importante verificar isso. O mesmo vale

12:11 para um caminho relativo de script: ele pode não funcionar em outra máquina. Ou os arquivos incluídos podem simplesmente não existir. Outra coisa a sinalizar é que, se o modelo estiver executando scripts em uma skill, mas não houver nada aprovando-os previamente, vão aparecer solicitações de permissão toda vez, tornando a skill praticamente inutilizável. Uma coisa que gosto de sinalizar é o excesso de regras absolutas em uma skill. Se houver mais de 15, por exemplo, talvez seja bom sinalizar isso ao nosso agent. Acumular regras é muito, muito perigoso ao trabalhar com agents

12:42 porque eles não conseguem seguir todas as regras muito bem. Em seguida, o script simplesmente imprime tudo isso para o nosso agent. De volta ao agent, primeiro ele recebe essa impressão. E agora recebe este prompt. Basicamente, o prompt analisa tudo o que o linter fez, examina a própria skill e rastreia certos comportamentos que não puderam ser detectados de forma determinística. Então, a skill vai perguntar: “Para que serve a skill, em uma frase?” Depois, vamos pedir ao agent que procure coisas que deveriam ser scripts. E vale notar que tudo o que estou prestes a mencionar são

13:13 coisas que só um LLM conseguiria detectar e que não poderíamos colocar em um script. Outra coisa são proibições que deveriam ser impostas. Por exemplo, algo em que poderíamos instalar um hook em vez de incluir uma regra do tipo “não faça”. Outra é pedir a um agent que crie um script em vez de preencher um template. Isso pode ser muito ineficiente em custo e tempo. Também podemos pedir que reduza o excesso. A skill deveria ser executada com o contexto bifurcado ou deixar de bifurcá-lo, caso isso esteja incorreto? As skills também podem ter contradições ou instruções pouco claras, então vamos pedir ao nosso

13:43 agent que investigue isso. E o excesso. Muitas vezes, quando os agents escrevem skills, eles as deixam inchadas, com uma tonelada de regras, uma tonelada de instruções e linhas muito densas. Então, queremos ver se conseguimos deixá-las um pouco menos inchadas. Depois, ele dá um veredito com base em tudo isso. Mais abaixo, vai injetar o template da resposta do modelo para que ele possa visualizá-la corretamente. Acredito que você também poderia usar o símbolo de arroba aqui. Na verdade, não faz muita diferença. Este é o pequeno template, caso tenha interesse. Este é o formato que toda skill deveria ter no final. Por fim, temos o template que

14:17 o modelo vai preencher, e vamos injetá-lo ali. O template é assim, caso tenha interesse. Vamos passar por isso bem rápido. E pronto. Essa é a minha skill para auditar skills. Espero que você tenha aprendido a criar skills boas e eficazes ao examinar essa skill. Ela também estará disponível na minha comunidade gratuita, cujo link está abaixo, onde você poderá auditar suas próprias skills usando essa ferramenta e também ver como criei esta skill. Agora, se você olhar o que eu realmente passei para ela, porque esta é a skill completa, eu disse o que deveria sinalizar,

14:48 quais dessas verificações são mecânicas e deveriam ficar em um script. Essa divisão é, na verdade, o ponto mais importante das skills: é onde você pode tornar as coisas o mais determinísticas e garantidas possível. Por exemplo, contar linhas e pesquisar um caminho com grep não é um trabalho para um LLM. Você deveria simplesmente colocar isso em um script e fazer com que ele execute na hora. E, mais uma vez, meus dois padrões, meus princípios inegociáveis, são deixar a invocação do modelo desativada, a menos que eu realmente queira que Claude recorra a ela por conta própria, e manter os arquivos curtos. Então, eis o que fazer hoje. Acesse minha comunidade gratuita da escola, cujo link está abaixo, e

15:21 baixe a skill de auditoria de skills e execute-a em todas as skills que você tem. Além disso, você pode ler cada linha e fazer duas perguntas: isto poderia ser um script? Isto poderia ser um hook? Então, encontre a skill indicada no link abaixo. É uma comunidade incrível, e também há muito conteúdo valioso disponível gratuitamente.

Transcrição original

[00:00] Since their inception, skills have been everyone’s favorite feature in Claude Code, and everybody talks about them like some kind of magic trick. But a skill is the simplest part of Claude Code, bar none. It’s a markdown file that gets pasted into context, and that’s exactly why almost everyone under uses them. They stop at the first thing a skill can do, which is store a prompt, and they never touch the levers that turn it into something more versatile. In this video, I’ll define exactly what a skill is from first principles, show you the architecture underneath, and how to build effective skills. By the end,

[00:33] you’ll be able to understand and create cheaper, faster, and more consistent skills that do any knowledge work of your choosing. I’m Roman. I published a top 3% paper at NeurIPS, the largest AI conference in the world. Now, I’m on a mission to push coding agents to their absolute limits. So, let’s start by reiterating what a skill is. A skill is a markdown file that the user or agent can paste into the agent’s context. Skills are triggered in two fashions: model invocation and user invocation.

[01:03] The simplest way to use skills is with user invocation. So, imagine that you wanted to save a prompt and inject it into an LLM whenever you type a certain command, such as {slash} analyze. And as soon as you type that, it pastes the stored prompt directly into your Claude Code’s context window, alongside any prompt additions you made after the {slash} command. Okay, so very simple. So, then we have model invocation, which is the second type. So, imagine that we want the model to decide whenever it

[01:34] should load a skill into its own context. Well, the model has to know that it can even do that, that that’s even a possibility. So, at the very start of every session, we paste a little headline about what the skill is and when to actually call upon it to get injected. We tell that to the LLM so it can then choose to do it. So, this headline is always loaded into context, and the body only loads when the model actually reaches for it. This is what we call progressive disclosure. But this is a double-edged sword because

[02:05] the more model invocable skills that you stack in your setup, the more distracting these always-on headlines become. That’s why in most of my skills, I disable model invocation so that it doesn’t load the headline into context at all. And there it is. Skills are quite literally as simple as that. You store a prompt in a markdown file, and either you inject it by a slash command, or you hint at its existence and let the model decide when to inject it into itself. And if it’s that simple, then the mechanism isn’t where the value is. The value is what you put in the skill

[02:37] itself. Skills shine when they carry knowledge that only exists in your head or on your team. How your codebase deploys, what your client needs, the way you personally like to work. And nobody’s one-size-fits-all skill off GitHub has that. So the whole game is knowing how to build your own skills for yourself and your team. A little bit of nuance about what a skill actually is. A skill isn’t actually necessarily just one file. It’s a folder, and that folder is the whole unit you share. So you can drop scripts next to the markdown, reference them with the skill through a

[03:09] variable, and Claude code swaps it for the folder’s real location before the model reads the line. And this allows us to port and reference scripts regardless of whose machine the skill is running on. That’s what makes these so powerful for internal teams. Because without that, sharing a skill would mean sharing a folder plus a paragraph of setup instructions, and every script call would be a pop-up. With it, you commit the folder to the repo’s .cloud/skills, and every teammate has the whole workflow on clone. Now, really quick, I want to talk about determinism. At their core, skills are probabilistic,

[03:43] meaning there is no guarantee that they work since they’re based on relying on an agent to do the right behaviors. This is problematic because they are more expensive, less reliable, and they take longer. On the other hand, scripts are fully deterministic. The solution to skills being probabilistic is that we can make them as deterministic as possible by incorporating scripts any place that they can be, or any place that they fit within a skill. So, one rule to consider when making or looking at skills,

[04:13] is there functionality in this skill that can be done fully deterministically in a script, or is there not? And here’s how I actually use a skill. Anything that can be scripted will be a script, and the markdown will teach the agent to run them and decide what comes next. The agent is treated like glue in between scripts. Now, that’s the core of skills. Past that, there are a couple of front matter levers most people genuinely never touch, and some are actually quite great. First up, you can put hooks inside of a skill, and they only register in sessions where that skill ran. For example, a skill called {slash}

[04:47] grill me record, you would take Matt Pocock’s original grill me skill, where the model asks you questions about your specifications until it’s satisfied, and you install a user prompt submit hook. So, every time you prompt the agent, a script fires. Then, before any code execution occurs, that hook would use a regex to record every question the model asked, and every response the user gave, adding it deterministically and instantly to documentation in the code base called grill responses.md.

[05:18] So, this would solve the pain point of a lot of people having their questions and the answers lost in the session of an agent, and it can be solved with this simple pattern of putting a hook inside of a skill. Now, one thing to note, once a skill registers a hook, it stays on for the rest of the session, not just that skill’s task. Now, you can also allow or disallow tools for the agent’s first turn when a skill is active. This serves as a safety precaution when you want to enforce behavior. For example, you can disallow edit write inside of a

[05:49] skill where the agent’s only job is to do read-only analysis. So, this guarantees that the agent will be well-behaved. Next up, in Claude code, the exclamation mark symbol turns the command into bash execution. And this works in skills, too. Meaning that you can run scripts at load time in a skill. The model never receives the command you typed. It instead receives the output of that command deterministically injected. This allows you to make a lot more dynamic logic inside of skills for a lot cheaper. And it enforces determinism

[06:20] inside of your skills. And another tip is that the at symbol injects any file of your choosing into your skill. This is powerful because it allows you to change what gets put into the model without changing the skill every time something changes. For example, if you run a {slash} analyze codebase skill, you can inject your codebase user story by adding at doc {slash} user story.md. And as that user story changes, you don’t have to change the skill. Number three is that you can add in arguments to skills that

[06:51] allow a user to inject variables into certain scripts or context into the model. Another pro tip is when using a skill, you can actually also prompt on top of it and it will just inject your prompt into the agent after the skill. Okay, so what does a skill actually look like in terms of the skill itself? So, let’s start with a skill audit skill that I created that’s kind of a meta example here of a skill that I created that follows all of the good conventions of skills and can teach you a thing or two. And then you can download it as well and have it better serve your skill building

[07:25] process. You can audit your skills. So, the first thing I’d like to highlight is that disable model invocation is on. This once again means that the front matter of this skill, which is this description, will not go into the model’s context at all times. If you have have set to false, then it will. Next little tip is that I made the context forked here. So, as soon as you run this skill, it will actually fork the exact context of your agent, put the skill in there, and have it run in a forked sub-agent, and then merge back into the main agent. This can be a very powerful pattern for

[07:58] context efficiency where you don’t actually need the skill running in the main context of your agent. You just need the output of the skill. In this case, we’re leaving it in the foreground, which just means that we won’t have our normal session while the skill is running. If you wanted to set background to true, this would mean that the forked agent would run in the background while you continue your session. In this case, we’re fine waiting. You can also assign a model to your skills. So, the second I run this skill, it will fork context, change the model to Opus, change the effort to

[08:30] medium, and keep it in the foreground. Now, you can also see I’ve disallowed as many tools as possible so that we make it fully deterministic because this is a read-only skill. We don’t want it actually changing our skill, so we enforce that guaranteed. Now, let’s move on to the skill itself. So, the first thing to note here is that we have the exclamation point pattern for running bash scripts within the skill itself before it even goes to the agent. So, the first thing the skill is going to do is it’s going to run the skill enter

[09:01] bash script on the skill of your choosing, which by the way, the skill of your choosing is chosen by the user under target, so they can add it as an argument. Then it will run this on that skill. And real quick, what is skill enter? Well, skill enter is a bunch of logic that first finds the skill from a path or a name in an argument. Then it’s going to see if no argument was given, usage will be printed instead into the context. Then it’s going to see if the verbatim skill that the user provided is

[09:32] actually a skill in your .cloud/skills or plugins, and it has to pick exactly one. So, once the script finds it, every check below runs against this folder. So, let’s go through the deterministic checks. First, it’s going to read the front matter and check each key. If there’s no front matter, that means that the skill will load with no description. Cuz in front matter, we have to have three dashes as the first part of a skill. Basically, this is a way to guarantee that the skill is actually written correctly. You can see up here

[10:02] that my description, the first line, is those three dashes. And this may be up for changes if Anthropic decides to change what they’re doing. So, if there’s a key Cloud Code does not know, it’s going to be silently ignored. So, we’re going to note that to our agent in the linter note. If there’s no description, we’re going to flag that to the model and let it know as well. And another thing to consider here is that if the description and the when to use is over 1,536 characters, then it will get truncated when given to the model, which can be

[10:34] confusing. So, in our auditing of skills, we want to deterministically make sure that it’s under 1,536 so that it isn’t truncating without our knowledge. Now, this is another very important one. For me and my skills, I like to by default have disable model invocation true. This is to protect the attention of our models. So, if disable model invocation is false, we want it flagged to our agent during the skill audit so we can make the decision. So, up next would be cases where we take arguments in, but we don’t give the user

[11:08] any hints on these arguments. All right, and other things that are important for you and your model to know about are that hooks from a skill stay armed for the whole session. So, sometimes that can cause danger. Also, if we switch model, it will break the prompt cache for that turn, causing an extra expensive skill load. And actually, same for effort. Up next in the linter is the size of a skill. So, in some cases, skills that are over 500 lines can be very dangerous. The reason is that you’re injecting a lot of

[11:39] context into your agents. You can make this flag a thousand. Under 500 is what Anthropic officially recommends. Another thing to note is that if it’s over 5,000 tokens total for the skill, the first 5,000 tokens will survive auto compaction, but the rest will silently drop. These are very important to at least know about. Now, other things, we’re going to deterministically check every script path and bundled file. So, if it’s referenced by a bare name, it may break on another machine. So, that’s very important to look into. Same thing

[12:11] with a relative script path, it’s going to break on another machine. Or if the bundled files do not actually exist. Uh another thing to flag is that if the model is running scripts in a skill, but nothing is pre-approving them, then permission pop-ups are going to occur every time, making the skill borderline unusable. One thing I like to flag is too many absolute rules within a skill. So, if it’s greater than 15, for example, we may want to flag this to our agent. Rule stacking is very, very dangerous when working with agents

[12:42] because they cannot adhere to every rule very well. And then next in the script, it’s just going to print this out to our agent. So, back into the agent, first it’s going to get that printout. And now it gets this prompt. So, the prompt is basically looking at everything the linter did, looking at the skill itself, and tracing certain behaviors that couldn’t deterministically be detected. So, the skill’s going to ask, “What is the skill for in one sentence?” Then we’re going to ask the agent to look for pros that should be a script. And note that all of these things I’m about to mention are

[13:13] things that only an LLM could detect that we couldn’t put in a script. So, another is do nots that should be enforced. So, somewhere where we could install a hook instead of a do not rule. Another is asking an agent to create a script instead of fill in a template. This can be very cost and time inefficient. We also may want to ask to reduce bloat. Should this be run under context forked or stop forking if that’s incorrect? There can also be contradictions or unclear instructions within skills, so we’re going to ask our

[13:43] agent to look into that. And bloat. So a lot of times when agents write skills, they bloat it with a ton of rules, a ton of instructions, a very dense line. So we just want to see if we can make it a little less bloated. And then so it gives a verdict based on all of this. Then down here it’s going to inject the template for the model’s response so that it can see it properly. I believe you could also use the at symbol here. It actually doesn’t really matter. And so this is the little template in case of you’re interested. This is the shape that every skill should end up. Then finally, we have the template that

[14:17] the model’s going to fill in and we’re going to inject it into there. So the template looks like this if you’re interested. We’re just going to move very fast through this. And there you have it. There’s my skill for auditing skills. So hopefully you learn how to build good effective skills by looking into the skill. It will also be available in my free school community linked down below where you can audit your own skills using this and you can also look into how I built this skill. Now, if you look into what I actually gave it there cuz this is actually the whole skill. I told it what to flag,

[14:48] which of those checks are mechanical and belong in a script, and this split is actually the biggest thing in skills is where you can make things as deterministic and guaranteed as possible. For example, counting lines and grepping a path is actually not a job for a language model. You should just install that into a script and have it run instantly. And once again, my two defaults, my non-negotiables are model invocation off unless I genuinely want Claude to reach for it on its own, and keep the files short. So here’s what to do today. Go into my free school community linked below and

[15:21] get the skill auditing skill and run it on every skill you have. Also, what you can do is read every line and ask two questions. Could this instead be a script? Could this be a hook? So, go find the skill linked below. It’s an amazing community, and there’s tons of value in there for free as well.