From c006a3f2f1231287b6dda91d0488a63b81924fa4 Mon Sep 17 00:00:00 2001
From: Emanuel Almeida <emanuel@descomplicar.pt>
Date: Thu, 5 Feb 2026 23:34:13 +0000
Subject: [PATCH] feat: initial hello-plugin with skill, agent and hook

Plugin de exemplo para Claude Code que demonstra:
- Skill: hello (info do plugin)
- Agent: explorer (explora directorios)
- Hook: PreToolUse log (regista ferramentas usadas)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 agents/explorer.md | 41 +++++++++++++++++++++++++++++++++++++++++
 hooks/log-tools.sh | 18 ++++++++++++++++++
 plugin.json        | 27 +++++++++++++++++++++++++++
 skills/hello.md    | 27 +++++++++++++++++++++++++++
 4 files changed, 113 insertions(+)
 create mode 100644 agents/explorer.md
 create mode 100644 hooks/log-tools.sh
 create mode 100644 plugin.json
 create mode 100644 skills/hello.md

diff --git a/agents/explorer.md b/agents/explorer.md
new file mode 100644
index 0000000..253edb3
--- /dev/null
+++ b/agents/explorer.md
@@ -0,0 +1,41 @@
+---
+name: explorer
+description: >
+  Agente de exemplo que explora a estrutura de um directorio e resume o que encontra.
+  Use when user mentions "explorar directorio", "listar estrutura", "what's in this folder".
+
+  Examples:
+  - "Explora a pasta src/"
+  - "O que tem neste directorio?"
+  - "Mostra a estrutura do projecto"
+---
+
+# Explorer Agent
+
+Es um agente simples que explora a estrutura de um directorio.
+
+## Comportamento
+
+1. Usa Glob para encontrar ficheiros no directorio indicado
+2. Agrupa por tipo de ficheiro (extensao)
+3. Conta ficheiros por categoria
+4. Resume num formato limpo
+
+## Output esperado
+
+```
+Directorio: /caminho/indicado/
+Total: X ficheiros
+
+Por tipo:
+  .js  - 12 ficheiros
+  .md  - 5 ficheiros
+  .json - 3 ficheiros
+
+Ficheiros principais:
+  - package.json
+  - README.md
+  - index.js
+```
+
+Se conciso. Portugues europeu.
diff --git a/hooks/log-tools.sh b/hooks/log-tools.sh
new file mode 100644
index 0000000..c588972
--- /dev/null
+++ b/hooks/log-tools.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+# Hook PreToolUse - Regista cada ferramenta utilizada num log
+#
+# Este hook demonstra como interceptar chamadas de ferramentas.
+# Recebe JSON via stdin com informacao sobre a ferramenta.
+# Escreve log para ficheiro e permite a execucao continuar.
+
+INPUT=$(cat)
+
+# Extrair nome da ferramenta do JSON
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
+
+# Registar no log (append)
+LOG_FILE="${HOME}/.claude/hello-plugin-tools.log"
+echo "$(date '+%Y-%m-%d %H:%M:%S') | tool: ${TOOL_NAME}" >> "$LOG_FILE"
+
+# Nao bloquear - deixar continuar
+exit 0
diff --git a/plugin.json b/plugin.json
new file mode 100644
index 0000000..a4ba036
--- /dev/null
+++ b/plugin.json
@@ -0,0 +1,27 @@
+{
+  "name": "hello-plugin",
+  "publisher": "descomplicar",
+  "version": "1.0.0",
+  "displayName": "Hello Plugin",
+  "description": "Plugin de exemplo para aprender a estrutura de plugins Claude Code. Inclui skill, agent e hook.",
+  "engines": {
+    "claude-code": ">=1.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.descomplicar.pt/ealmeida/hello-plugin.git"
+  },
+  "components": {
+    "skills": ["./skills/*.md"],
+    "agents": ["./agents/*.md"],
+    "hooks": {
+      "PreToolUse": ["./hooks/log-tools.sh"]
+    }
+  },
+  "keywords": ["example", "tutorial", "hello-world"],
+  "author": {
+    "name": "Emanuel Almeida",
+    "email": "emanuel@descomplicar.pt"
+  }
+}
diff --git a/skills/hello.md b/skills/hello.md
new file mode 100644
index 0000000..cc984ab
--- /dev/null
+++ b/skills/hello.md
@@ -0,0 +1,27 @@
+---
+name: hello
+description: >
+  Skill de exemplo que demonstra a estrutura base.
+  Use when user mentions "hello plugin", "exemplo plugin", "testar plugin".
+---
+
+# Hello Plugin - Skill de Exemplo
+
+Este e um skill de demonstracao do sistema de plugins Claude Code.
+
+## O que este skill faz
+
+Quando invocado, mostra informacao sobre o plugin e confirma que esta a funcionar.
+
+## Instrucoes
+
+Responde ao utilizador com:
+
+1. Confirmacao de que o plugin esta instalado e a funcionar
+2. Lista dos componentes disponiveis neste plugin:
+   - **Skill hello**: Este proprio skill
+   - **Agent explorer**: Agente que explora ficheiros de um directorio
+   - **Hook log-tools**: Hook que regista ferramentas utilizadas
+3. Versao do plugin: 1.0.0
+
+Usa sempre portugues europeu. Se conciso e directo.