voc-claude-skills: Instructions file for Claude Code

Working in this repo

Conventions for anyone — human or agent — editing these skills.

Structure

• Skills live in .claude/skills/<name>/SKILL.md. Uppercase SKILL.md, always. Lowercase works on macOS and fails on Linux.
• The directory name must equal the name: in frontmatter. npm run check enforces this.
• Each skill is self-contained. A skill may not reference a path outside its own directory, except config/, context/ and scripts/ at the repo root.

Frontmatter

---
name: exactly-the-directory-name
description: What it does, then the trigger phrases. This is how the model decides
  whether to invoke the skill, so write it for retrieval, not for a human reader.
allowed-tools: Read, Write, Bash, mcp__server__tool
---

Always declare allowed-tools. A skill without it inherits every tool the installing user has connected, including write-capable CRM and messaging servers. That is someone else's blast radius, not yours.

Never declare an MCP tool name you have not seen in /mcp output. allowed-tools is an allowlist: a wrong name means the declared tool does not exist and the real one is not permitted, and the skill reports a clean run over an empty result set. No error appears.

For chat and notes servers, where namespaces vary, declare only the universal tools and instruct the user to add theirs. Two source skills here do exactly that.

Numbers

Thresholds live in config/thresholds.json. Never hardcode one in a SKILL.md — that is how the confirmation rule drifted into four contradictory versions. npm run check warns about this.

Company-specific values live in context/product-context.md, which is gitignored.

Every skill ends with "What this gets wrong"

Not a disclaimer. A specific list of how this particular skill produces wrong answers: sampling bias, what it cannot see, what a number does and does not mean. If you cannot write three honest failure modes for a skill, you do not understand it well enough to ship it.