docs: correct the install instructions and the repository layout

The Quick start told Hermes users to copy the workflows as loose .md files
into ~/.hermes/skills/software-development/. Hermes indexes skills by
walking for SKILL.md, so those files were never listed and never loaded.
Reproduced with the real loader (agent.skill_utils.iter_skill_index_files)
against a scratch HERMES_HOME: the documented command indexed 0 of 5
workflows, the loop now documented indexes 5 of 5.

- README.md / README.pt-BR.md: one loop for both agents, with SKILLS_DIR
  swapped for Claude Code; install verification hint (hermes skills list).
- README layout tree: five workflows (wf-readme.md was missing), the whole
  vendored skills/ tree, and the actual qa/ contents.
- The snapshot provenance claim listed base-364/v2/v3/v4 as if they lived
  in qa/snapshots/, but only baseline-final.json is committed; corrected,
  and it is now named as the file the gates read.
- Documented that api-security-review is two unrelated skills sharing one
  name (OWASP vendored vs apisec-inc external).
- docs/SKILLS.md: the Claude Code block did mkdir -p "~/.claude/..." with
  the tilde inside quotes, which creates a literal "~" directory instead of
  expanding; replaced with $HOME. Also corrected the claim that only Claude
  Code needs a per-skill directory.

Verified: installing from both documented blocks into a scratch HOME yields
15/15 skills indexed and carries the support files along.
This commit is contained in:
Evandro Fonseca Junior committed 2026-09-14 07:40:27 -03:00
1 parent bb3fe21766
commit 936ceda102
3 files changed
+77 -37

No files matched your search

+10 -8
View File
@@ -1,9 +1,10 @@
# Skills usadas e de onde vieram
Este é o inventário do que os workflows carregam. Cada skill é um diretório
com um `SKILL.md`; para o Hermes Agent, vão em `~/.hermes/skills/`; para
Claude Code, em `~/.claude/skills/<nome>/SKILL.md` (subdiretório por skill —
Claude Code não carrega arquivo `.md` solto, precisa do diretório).
com um `SKILL.md` dentro, e esse diretório é obrigatório nos dois agentes
(a skill é `<nome>/SKILL.md`, nunca um `.md` solto, que não é indexado):
no Hermes Agent, em `~/.hermes/skills/<nome>/SKILL.md`; no Claude Code, em
`~/.claude/skills/<nome>/SKILL.md`.
## Workflows orquestradores (em `workflows/`)
@@ -91,15 +92,16 @@ clone externo. Copie direto:
cp -r skills/* ~/.hermes/skills/
# Claude Code (cada skill no seu próprio diretório):
mkdir -p ~/.claude/skills
mkdir -p "$HOME/.claude/skills"
for d in skills/*/; do
nome=$(basename "$d")
[ "$nome" = "NOTICE.md" ] && continue
mkdir -p "~/.claude/skills/$nome"
cp -r "$d." "~/.claude/skills/$nome/"
cp -r "$d" "$HOME/.claude/skills/"
done
```
Os arquivos de apoio que cada skill referencia (`plays/`, `templates/`,
`schemas/`, `docs/`) ficam dentro do diretório da própria skill, então o
`cp -r` os leva junto. Origem e licença de cada um: `skills/NOTICE.md`.
**Frontend/backend/arquitetura** (ainda não vendorizadas, instalam de fora):
a maioria via `npx skills` (formato agentskills.io):