From 52c64e6f3996fb4a6771c3193d3cd32530f35e07 Mon Sep 17 00:00:00 2001
From: zap <zap@local>
Date: Thu, 5 Mar 2026 20:55:23 +0000
Subject: [PATCH] feat(skills): add model-family hint files for agent:bootstrap
 injection (anthropic/openai/generic)

---
 .../hints/anthropic.md                        | 30 ++++++++++++++++
 .../llm-tool-best-practices/hints/generic.md  | 15 ++++++++
 .../llm-tool-best-practices/hints/openai.md   | 35 +++++++++++++++++++
 3 files changed, 80 insertions(+)
 create mode 100644 skills/llm-tool-best-practices/hints/anthropic.md
 create mode 100644 skills/llm-tool-best-practices/hints/generic.md
 create mode 100644 skills/llm-tool-best-practices/hints/openai.md

diff --git a/skills/llm-tool-best-practices/hints/anthropic.md b/skills/llm-tool-best-practices/hints/anthropic.md
new file mode 100644
index 0000000..4ea02d5
--- /dev/null
+++ b/skills/llm-tool-best-practices/hints/anthropic.md
@@ -0,0 +1,30 @@
+# MODEL_HINTS.md — Anthropic/Claude Tool Best Practices
+
+Active model family: **Anthropic (Claude)**
+
+When writing or evaluating skills/tools for this session, apply these rules:
+
+## Schema
+- Use `input_schema` (not `parameters`) for tool definitions.
+- Add `strict: true` for production tools — guarantees schema conformance via structured outputs.
+- Use `input_examples` array for tools with complex inputs, nested objects, or format-sensitive params.
+
+## Descriptions
+- Write **3–4+ sentences** per tool: what it does, when to use/not use it, what each param means, what it returns, caveats.
+- This is the highest-leverage factor in Claude's tool selection accuracy.
+
+## Model selection
+- Use **Claude Opus** for complex/multi-tool tasks or ambiguous queries.
+- Use **Claude Haiku** for simple well-defined tools only — it may infer missing params.
+
+## Tool design
+- Consolidate related operations into fewer tools (e.g. one `github_pr` tool with action param vs three separate tools).
+- Use `service_resource_verb` namespacing: `github_issues_search`, `slack_channel_send`.
+- Return only high-signal fields. Prefer semantic names/slugs over raw UUIDs.
+- Bound response size. Truncation messages should be actionable (tell Claude what to do next).
+- For errors: plain-language messages, not stack traces.
+
+## Safety
+- Least privilege on all tool permissions.
+- Guard destructive/irreversible actions with confirmation or human-in-the-loop.
+- Validate all tool inputs before acting.
diff --git a/skills/llm-tool-best-practices/hints/generic.md b/skills/llm-tool-best-practices/hints/generic.md
new file mode 100644
index 0000000..efc3c67
--- /dev/null
+++ b/skills/llm-tool-best-practices/hints/generic.md
@@ -0,0 +1,15 @@
+# MODEL_HINTS.md — General Tool Best Practices
+
+Active model family: **Unknown** (no specific hints available for this model)
+
+Applying universal best practices. For model-specific guidance, see:
+- `skills/llm-tool-best-practices/hints/anthropic.md` (Claude)
+- `skills/llm-tool-best-practices/hints/openai.md` (GPT)
+
+## Universal rules
+- Write detailed descriptions (3–4+ sentences per tool): purpose, when to use/not use, params, output, caveats.
+- Fewer, richer tools beat many narrow ones. Consolidate related operations.
+- Use `service_resource_verb` namespacing for clarity.
+- Return only high-signal data. Strip opaque IDs, raw stack traces, bloat.
+- Bound response sizes; make truncation messages actionable.
+- Least privilege. Validate all inputs. Guard destructive actions.
diff --git a/skills/llm-tool-best-practices/hints/openai.md b/skills/llm-tool-best-practices/hints/openai.md
new file mode 100644
index 0000000..0c18693
--- /dev/null
+++ b/skills/llm-tool-best-practices/hints/openai.md
@@ -0,0 +1,35 @@
+# MODEL_HINTS.md — OpenAI/GPT Tool Best Practices
+
+Active model family: **OpenAI (GPT)**
+
+When writing or evaluating skills/tools for this session, apply these rules:
+
+## Schema
+- Use `parameters` (not `input_schema`) for tool definitions.
+- Always set `"strict": true` — requires `additionalProperties: false` and all fields in `required`.
+- For optional fields: add `null` to the type union (e.g. `"type": ["string", "null"]`) and keep in `required`.
+
+## Descriptions
+- Write clear, detailed descriptions explaining purpose, each param, and output.
+- Use the system prompt to describe when (and when NOT) to use each function.
+- **Do not add examples in descriptions** for reasoning-capable GPT models — focus on clear prose.
+
+## Tool count & loading
+- Keep initially available tools **under ~20** for highest accuracy.
+- Use `defer_loading: true` + tool search for large tool libraries — defer rarely-used tools.
+- Use `namespace` type to group related tools by domain (e.g. `crm`, `billing`).
+
+## Tool design
+- Use `service_resource_verb` namespacing: `crm_customer_get`, `billing_invoice_list`.
+- Use enums and object structure to make invalid states unrepresentable.
+- Combine functions always called in sequence into one tool.
+- Don't ask the model to fill args you already know — pass them in code.
+
+## Parallel calls
+- Parallel tool calls are on by default. Disable with `parallel_tool_calls: false` if tools have ordering dependencies.
+
+## Safety
+- Use the **Moderation API** (free) to filter unsafe content.
+- Pass `safety_identifier` (hashed user ID) with requests for abuse detection.
+- Human-in-the-loop for high-stakes or irreversible tool actions.
+- Guard against prompt injection from tool outputs.