docs: add Thariq skills lessons reference

- Extract key insights from Thariq's article on Anthropic's internal skill usage
- Document 9 skill categories taxonomy, gotchas pattern, on-demand hooks
- Audit existing 15 skills against taxonomy (gaps: Verification, Runbooks)

Author: nicolas-codemate

docs/skills-lessons-thariq.md

@@ -0,0 +1,126 @@
+# Lessons from Building Claude Code: How We Use Skills
+
+> Source: Thariq (@trq212), Anthropic — 2026-03-17
+> https://x.com/trq212/status/2033949937936085378
+> Extracted: 2026-03-17. Only insights NOT already in skills-guide-anthropic.md.
+
+## 1. Nine Skill Categories (Audit Checklist)
+
+Use this taxonomy to identify gaps in your skill library:
+
+| # | Category | Purpose | Examples |
+|---|----------|---------|----------|
+| 1 | **Library & API Reference** | How to correctly use a library/CLI/SDK | billing-lib, internal-cli, frontend-design |
+| 2 | **Product Verification** | Test/verify that code works (playwright, tmux) | signup-flow-driver, checkout-verifier |
+| 3 | **Data Fetching & Analysis** | Connect to data/monitoring stacks | funnel-query, cohort-compare, grafana |
+| 4 | **Business Process & Team Automation** | Automate repetitive workflows | standup-post, create-ticket, weekly-recap |
+| 5 | **Code Scaffolding & Templates** | Generate framework boilerplate | new-workflow, new-migration, create-app |
+| 6 | **Code Quality & Review** | Enforce code quality, review code | adversarial-review, code-style, testing-practices |
+| 7 | **CI/CD & Deployment** | Fetch, push, deploy code | babysit-pr, deploy-service, cherry-pick-prod |
+| 8 | **Runbooks** | Symptom -> investigation -> structured report | service-debugging, oncall-runner, log-correlator |
+| 9 | **Infrastructure Operations** | Routine maintenance with guardrails | orphan-cleanup, dependency-management, cost-investigation |
+
+**Key insight**: The best skills fit cleanly into ONE category. Confusing skills straddle several.
+
+## 2. Gotchas Section = Highest-Signal Content
+
+The most valuable part of any skill is a **Gotchas** section built from real failure points.
+
+- Start with common mistakes Claude makes using the skill
+- Update iteratively as new edge cases appear
+- This is more valuable than detailed instructions
+
+```markdown
+## Gotchas
+- Always use `--no-cache` flag when running migrations (stale cache causes silent failures)
+- The `user_id` column in `events` table is NOT the same as `users.id` — join via `canonical_user_id`
+- Never call `billing.charge()` without checking `subscription.active` first
+```
+
+## 3. Don't State the Obvious
+
+Focus on information that pushes Claude **out of its normal way of thinking**.
+Claude already knows a lot about coding — add value with org-specific knowledge,
+non-obvious patterns, and things that differ from standard approaches.
+
+Example: the `frontend-design` skill was built by iterating on improving Claude's
+design taste, avoiding generic patterns (Inter font, purple gradients).
+
+## 4. Setup Pattern with config.json
+
+For skills needing user-specific setup (e.g., which Slack channel to post to):
+
+1. Store setup info in a `config.json` in the skill directory
+2. On first run, if config is missing, ask the user for the information
+3. Save for future runs
+
+Use `AskUserQuestion` tool for structured, multiple-choice setup questions.
+
+## 5. Persistent Data with ${CLAUDE_PLUGIN_DATA}
+
+Skills can maintain memory by storing data within them:
+- Append-only text logs, JSON files, or even SQLite databases
+- Example: `standup-post` keeps a `standups.log` — next run, Claude reads its own history
+
+**Important**: Data in the skill directory may be deleted on upgrade.
+Use `${CLAUDE_PLUGIN_DATA}` for stable per-plugin storage.
+
+## 6. Store Scripts & Helper Libraries
+
+Give Claude pre-built scripts and libraries to **compose** rather than reconstruct:
+
+```
+skills/data-analysis/
+  SKILL.md
+  lib/
+    fetch_events.py      # helper to query event source
+    format_report.py     # standard report formatter
+  references/
+    schema.md            # table schemas and relationships
+```
+
+Claude spends its turns on **composition and decision-making** instead of
+reconstructing boilerplate. It generates scripts on the fly that import and
+compose these helpers.
+
+## 7. On-Demand Hooks (Skill-Scoped)
+
+Skills can register hooks that activate **only when the skill is called**
+and last for the session duration. Use for opinionated hooks that would be
+annoying if always active:
+
+- `/careful` — blocks `rm -rf`, `DROP TABLE`, force-push, `kubectl delete`
+  via PreToolUse matcher on Bash. Only when touching prod.
+- `/freeze` — blocks Edit/Write outside a specific directory.
+  Useful when debugging to prevent accidental "fixes" to unrelated code.
+
+## 8. Composing Skills
+
+Skills can reference other skills by name. If the referenced skill is installed,
+the model will invoke it automatically. No native dependency management yet —
+just mention the skill name in your instructions.
+
+## 9. Measuring Skill Usage
+
+Use a **PreToolUse hook** to log which skills are invoked:
+- Track popularity and identify under-triggering skills
+- Compare actual usage vs expectations
+- Helps curate and improve the skill library
+
+## 10. Avoid Railroading Claude
+
+Be careful of over-specifying instructions in reusable skills:
+- Give Claude the information it needs
+- But give it flexibility to adapt to the situation
+- Too-specific instructions break when context varies
+
+## 11. Distribution Strategy
+
+| Scale | Approach |
+|-------|----------|
+| Small team, few repos | Check skills into repo under `.claude/skills/` |
+| Growing org | Internal plugin marketplace |
+
+**Marketplace flow**: sandbox folder on GitHub -> share on Slack -> gains traction -> PR to marketplace.
+
+**Warning**: It's easy to create bad or redundant skills. Have a curation method before release.

settings.json

@@ -40,10 +40,6 @@
       "WebFetch(domain:shipyard.build)",
       "WebFetch(domain:awesomeclaude.ai)"
     ],
-    "ask": [
-      "Bash(git push *)",
-      "Bash(cd * && git push *)"
-    ],
     "deny": [
       "Bash(rm -rf *)",
       "Bash(rm -rf /)",
@@ -64,6 +60,10 @@
       "Bash(* /tmp/cloud-sql-proxy-sockets*)",
       "Bash(*/tmp/cloud-sql-proxy-sockets*)"
     ],
+    "ask": [
+      "Bash(git push *)",
+      "Bash(cd * && git push *)"
+    ],
     "defaultMode": "acceptEdits"
   },
   "hooks": {