code · pull · Oct 16, 2025 · Oct 14, 2025 · Oct 14, 2025 · Oct 15, 2025
diff --git a/capabilities/README.md b/capabilities/README.md
@@ -0,0 +1,19 @@
+# Claude Capabilities
+
+Welcome to the Capabilities section of the Claude Cookbooks! This directory contains a collection of guides that showcase specific capabilities where Claude excels. Each guide provides an in-depth exploration of a particular capability, discussing potential use cases, prompt engineering techniques to optimize results, and approaches for evaluating Claude's performance.
+
+## Guides
+
+- **[Classification with Claude](./classification/guide.ipynb)**: Discover how Claude can revolutionize classification tasks, especially in scenarios with complex business rules and limited training data. This guide walks you through data preparation, prompt engineering with retrieval-augmented generation (RAG), testing, and evaluation.
+
+- **[Retrieval Augmented Generation with Claude](./retrieval_augmented_generation/guide.ipynb)**: Learn how to enhance Claude's capabilities with domain-specific knowledge using RAG. This guide demonstrates how to build a RAG system from scratch, optimize its performance, and create an evaluation suite. You'll learn how techniques like summary indexing and re-ranking can significantly improve precision, recall, and overall accuracy in question-answering tasks.
+
+- **[Retrieval Augmented Generation with Contextual Embeddings](./contextual-embeddings/guide.ipynb)**: Learn how to use a new technique to improve the performance of your RAG system. In traditional RAG, documents are typically split into smaller chunks for efficient retrieval. While this approach works well for many applications, it can lead to problems when individual chunks lack sufficient context. Contextual Embeddings solve this problem by adding relevant context to each chunk before embedding. You'll learn how to use contextual embeddings with semantic search, BM25 search, and reranking to improve performance.
+
+- **[Summarization with Claude](./summarization/guide.ipynb)**: Explore Claude's ability to summarize and synthesize information from multiple sources. This guide covers a variety of summarization techniques, including multi-shot, domain-based, and chunking methods, as well as strategies for handling long-form content and multiple documents. We also explore evaluating summaries, which can be a balance of art, subjectivity, and the right approach!
+
+- **[Text-to-SQL with Claude](./text_to_sql/guide.ipynb)**: This guide covers how to generate complex SQL queries from natural language using prompting techniques, self-improvement, and RAG. We'll also explore how to evaluate and improve the accuracy of generated SQL queries, with evals that test for syntax, data correctness, row count, and more.
+
+## Getting Started
+
+To get started with these guides, simply navigate to the desired guide's directory and follow the instructions provided in the `guide.ipynb` file. Each guide is self-contained and includes all the necessary code, data, and evaluation scripts to reproduce the examples and experiments.
diff --git a/skills/classification/README.md → capabilities/classification/README.md b/skills/classification/README.md → capabilities/classification/README.md
diff --git a/skills/classification/data/results.csv → capabilities/classification/data/results.csv b/skills/classification/data/results.csv → capabilities/classification/data/results.csv
diff --git a/skills/classification/data/test.tsv → capabilities/classification/data/test.tsv b/skills/classification/data/test.tsv → capabilities/classification/data/test.tsv
diff --git a/skills/classification/data/train.tsv → capabilities/classification/data/train.tsv b/skills/classification/data/train.tsv → capabilities/classification/data/train.tsv
diff --git a/skills/classification/data/vector_db.pkl → ...ilities/classification/data/vector_db.pkl b/skills/classification/data/vector_db.pkl → ...ilities/classification/data/vector_db.pkl
diff --git a/skills/classification/evaluation/README.md → ...ities/classification/evaluation/README.md b/skills/classification/evaluation/README.md → ...ities/classification/evaluation/README.md
diff --git a/skills/classification/evaluation/dataset.csv → ...ies/classification/evaluation/dataset.csv b/skills/classification/evaluation/dataset.csv → ...ies/classification/evaluation/dataset.csv
diff --git a/...ification/evaluation/promptfooconfig.yaml → ...ification/evaluation/promptfooconfig.yaml b/...ification/evaluation/promptfooconfig.yaml → ...ification/evaluation/promptfooconfig.yaml
diff --git a/skills/classification/evaluation/prompts.py → ...ties/classification/evaluation/prompts.py b/skills/classification/evaluation/prompts.py → ...ties/classification/evaluation/prompts.py
diff --git a/...ls/classification/evaluation/transform.py → ...es/classification/evaluation/transform.py b/...ls/classification/evaluation/transform.py → ...es/classification/evaluation/transform.py
diff --git a/skills/classification/evaluation/vectordb.py → ...ies/classification/evaluation/vectordb.py b/skills/classification/evaluation/vectordb.py → ...ies/classification/evaluation/vectordb.py
diff --git a/skills/classification/guide.ipynb → capabilities/classification/guide.ipynb b/skills/classification/guide.ipynb → capabilities/classification/guide.ipynb
diff --git a/skills/contextual-embeddings/README.md → capabilities/contextual-embeddings/README.md b/skills/contextual-embeddings/README.md → capabilities/contextual-embeddings/README.md
diff --git a/...-rag-lambda-function/inference_adapter.py → ...-rag-lambda-function/inference_adapter.py b/...-rag-lambda-function/inference_adapter.py → ...-rag-lambda-function/inference_adapter.py
diff --git a/...al-rag-lambda-function/lambda_function.py → ...al-rag-lambda-function/lambda_function.py b/...al-rag-lambda-function/lambda_function.py → ...al-rag-lambda-function/lambda_function.py
diff --git a/...textual-rag-lambda-function/s3_adapter.py → ...textual-rag-lambda-function/s3_adapter.py b/...textual-rag-lambda-function/s3_adapter.py → ...textual-rag-lambda-function/s3_adapter.py
diff --git a/...tual-embeddings/data/codebase_chunks.json → ...tual-embeddings/data/codebase_chunks.json b/...tual-embeddings/data/codebase_chunks.json → ...tual-embeddings/data/codebase_chunks.json
diff --git a/...tual-embeddings/data/evaluation_set.jsonl → ...tual-embeddings/data/evaluation_set.jsonl b/...tual-embeddings/data/evaluation_set.jsonl → ...tual-embeddings/data/evaluation_set.jsonl
diff --git a/skills/contextual-embeddings/guide.ipynb → ...ilities/contextual-embeddings/guide.ipynb b/skills/contextual-embeddings/guide.ipynb → ...ilities/contextual-embeddings/guide.ipynb
@@ -3,55 +3,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "# Enhancing RAG with Contextual Retrieval\n",
-    "\n",
-    "> Note: For more background information on Contextual Retrieval, including additional performance evaluations on various datasets, we recommend reading our accompanying  [blog post](https://www.anthropic.com/news/contextual-retrieval).\n",
-    "\n",
-    "Retrieval Augmented Generation (RAG) enables Claude to leverage your internal knowledge bases, codebases, or any other corpus of documents when providing a response. Enterprises are increasingly building RAG applications to improve workflows in customer support, Q&A over internal company documents, financial & legal analysis, code generation, and much more.\n",
-    "\n",
-    "In a [separate guide](https://github.com/anthropics/anthropic-cookbook/blob/main/skills/retrieval_augmented_generation/guide.ipynb), we walked through setting up a basic retrieval system, demonstrated how to evaluate its performance, and then outlined a few techniques to improve performance. In this guide, we present a technique for improving retrieval performance: Contextual Embeddings.\n",
-    "\n",
-    "In traditional RAG, documents are typically split into smaller chunks for efficient retrieval. While this approach works well for many applications, it can lead to problems when individual chunks lack sufficient context. Contextual Embeddings solve this problem by adding relevant context to each chunk before embedding. This method improves the quality of each embedded chunk, allowing for more accurate retrieval and thus better overall performance. Averaged across all data sources we tested, Contextual Embeddings reduced the top-20-chunk retrieval failure rate by 35%.\n",
-    "\n",
-    "The same chunk-specific context can also be used with BM25 search to further improve retrieval performance. We introduce this technique in the “Contextual BM25” section.\n",
-    "\n",
-    "In this guide, we'll demonstrate how to build and optimize a Contextual Retrieval system using a dataset of 9 codebases as our knowledge base. We'll walk through:\n",
-    "\n",
-    "1) Setting up a basic retrieval pipeline to establish a baseline for performance.\n",
-    "\n",
-    "2) Contextual Embeddings: what it is, why it works, and how prompt caching makes it practical for production use cases.\n",
-    "\n",
-    "3) Implementing Contextual Embeddings and demonstrating performance improvements.\n",
-    "\n",
-    "4) Contextual BM25: improving performance with *contextual* BM25 hybrid search.\n",
-    "\n",
-    "5) Improving performance with reranking,\n",
-    "\n",
-    "### Evaluation Metrics & Dataset:\n",
-    "\n",
-    "We use a pre-chunked dataset of 9 codebases - all of which have been chunked according to a basic character splitting mechanism. Our evaluation dataset contains 248 queries - each of which contains a 'golden chunk.' We'll use a metric called Pass@k to evaluate performance. Pass@k checks whether or not the 'golden document' was present in the first k documents retrieved for each query. Contextual Embeddings in this case helped us to improve Pass@10 performance from ~87% --> ~95%.\n",
-    "\n",
-    "You can find the code files and their chunks in `data/codebase_chunks.json` and the evaluation dataset in `data/evaluation_set.jsonl`\n",
-    "\n",
-    "#### Additional Notes:\n",
-    "\n",
-    "Prompt caching is helpful in managing costs when using this retrieval method. This feature is currently available on Anthropic's 1P API, and is coming soon to our 3P partner environments in AWS Bedrock and GCP Vertex. We know that many of our customers leverage AWS Knowledge Bases and GCP Vertex AI APIs when building RAG solutions, and this method can be used on either platform with a bit of customization. Consider reaching out to Anthropic or your AWS/GCP account team for guidance on this!\n",
-    "\n",
-    "To make it easier to use this method on Bedrock, the AWS team has provided us with code that you can use to implement a Lambda function that adds context to each document. If you deploy this Lambda function, you can select it as a custom chunking option when configuring a [Bedrock Knowledge Base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-create.html). You can find this code in `contextual-rag-lambda-function`. The main lambda function code is in `lambda_function.py`.\n",
-    "\n",
-    "## Table of Contents\n",
-    "\n",
-    "1) Setup\n",
-    "\n",
-    "2) Basic RAG\n",
-    "\n",
-    "3) Contextual Embeddings\n",
-    "\n",
-    "4) Contextual BM25\n",
-    "\n",
-    "5) Reranking"
-   ]
+   "source": "# Enhancing RAG with Contextual Retrieval\n\n> Note: For more background information on Contextual Retrieval, including additional performance evaluations on various datasets, we recommend reading our accompanying  [blog post](https://www.anthropic.com/news/contextual-retrieval).\n\nRetrieval Augmented Generation (RAG) enables Claude to leverage your internal knowledge bases, codebases, or any other corpus of documents when providing a response. Enterprises are increasingly building RAG applications to improve workflows in customer support, Q&A over internal company documents, financial & legal analysis, code generation, and much more.\n\nIn a [separate guide](https://github.com/anthropics/anthropic-cookbook/blob/main/capabilities/retrieval_augmented_generation/guide.ipynb), we walked through setting up a basic retrieval system, demonstrated how to evaluate its performance, and then outlined a few techniques to improve performance. In this guide, we present a technique for improving retrieval performance: Contextual Embeddings.\n\nIn traditional RAG, documents are typically split into smaller chunks for efficient retrieval. While this approach works well for many applications, it can lead to problems when individual chunks lack sufficient context. Contextual Embeddings solve this problem by adding relevant context to each chunk before embedding. This method improves the quality of each embedded chunk, allowing for more accurate retrieval and thus better overall performance. Averaged across all data sources we tested, Contextual Embeddings reduced the top-20-chunk retrieval failure rate by 35%.\n\nThe same chunk-specific context can also be used with BM25 search to further improve retrieval performance. We introduce this technique in the \"Contextual BM25\" section.\n\nIn this guide, we'll demonstrate how to build and optimize a Contextual Retrieval system using a dataset of 9 codebases as our knowledge base. We'll walk through:\n\n1) Setting up a basic retrieval pipeline to establish a baseline for performance.\n\n2) Contextual Embeddings: what it is, why it works, and how prompt caching makes it practical for production use cases.\n\n3) Implementing Contextual Embeddings and demonstrating performance improvements.\n\n4) Contextual BM25: improving performance with *contextual* BM25 hybrid search.\n\n5) Improving performance with reranking,\n\n### Evaluation Metrics & Dataset:\n\nWe use a pre-chunked dataset of 9 codebases - all of which have been chunked according to a basic character splitting mechanism. Our evaluation dataset contains 248 queries - each of which contains a 'golden chunk.' We'll use a metric called Pass@k to evaluate performance. Pass@k checks whether or not the 'golden document' was present in the first k documents retrieved for each query. Contextual Embeddings in this case helped us to improve Pass@10 performance from ~87% --> ~95%.\n\nYou can find the code files and their chunks in `data/codebase_chunks.json` and the evaluation dataset in `data/evaluation_set.jsonl`\n\n#### Additional Notes:\n\nPrompt caching is helpful in managing costs when using this retrieval method. This feature is currently available on Anthropic's 1P API, and is coming soon to our 3P partner environments in AWS Bedrock and GCP Vertex. We know that many of our customers leverage AWS Knowledge Bases and GCP Vertex AI APIs when building RAG solutions, and this method can be used on either platform with a bit of customization. Consider reaching out to Anthropic or your AWS/GCP account team for guidance on this!\n\nTo make it easier to use this method on Bedrock, the AWS team has provided us with code that you can use to implement a Lambda function that adds context to each document. If you deploy this Lambda function, you can select it as a custom chunking option when configuring a [Bedrock Knowledge Base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-create.html). You can find this code in `contextual-rag-lambda-function`. The main lambda function code is in `lambda_function.py`.\n\n## Table of Contents\n\n1) Setup\n\n2) Basic RAG\n\n3) Contextual Embeddings\n\n4) Contextual BM25\n\n5) Reranking"
   },
   {
    "cell_type": "markdown",

diff --git a/.../retrieval_augmented_generation/README.md → .../retrieval_augmented_generation/README.md b/.../retrieval_augmented_generation/README.md → .../retrieval_augmented_generation/README.md
diff --git a/...ented_generation/data/anthropic_docs.json → ...ented_generation/data/anthropic_docs.json b/...ented_generation/data/anthropic_docs.json → ...ented_generation/data/anthropic_docs.json
diff --git a/.../data/anthropic_summary_indexed_docs.json → .../data/anthropic_summary_indexed_docs.json b/.../data/anthropic_summary_indexed_docs.json → .../data/anthropic_summary_indexed_docs.json
diff --git a/...d_generation/data/end_to_end_results.json → ...d_generation/data/end_to_end_results.json b/...d_generation/data/end_to_end_results.json → ...d_generation/data/end_to_end_results.json
diff --git a/...ed_generation/data/retrieval_results.json → ...ed_generation/data/retrieval_results.json b/...ed_generation/data/retrieval_results.json → ...ed_generation/data/retrieval_results.json
diff --git a/...augmented_generation/evaluation/README.md → ...augmented_generation/evaluation/README.md b/...augmented_generation/evaluation/README.md → ...augmented_generation/evaluation/README.md
diff --git a/...tion/csvs/evaluation_results_detailed.csv → ...tion/csvs/evaluation_results_detailed.csv b/...tion/csvs/evaluation_results_detailed.csv → ...tion/csvs/evaluation_results_detailed.csv
diff --git a/...aluation_results_detailed_level_three.csv → ...aluation_results_detailed_level_three.csv b/...aluation_results_detailed_level_three.csv → ...aluation_results_detailed_level_three.csv
diff --git a/...evaluation_results_detailed_level_two.csv → ...evaluation_results_detailed_level_two.csv b/...evaluation_results_detailed_level_two.csv → ...evaluation_results_detailed_level_two.csv
diff --git a/.../csvs/evaluation_results_detailed_one.csv → .../csvs/evaluation_results_detailed_one.csv b/.../csvs/evaluation_results_detailed_one.csv → .../csvs/evaluation_results_detailed_one.csv
diff --git a/...n/evaluation/docs_evaluation_dataset.json → ...n/evaluation/docs_evaluation_dataset.json b/...n/evaluation/docs_evaluation_dataset.json → ...n/evaluation/docs_evaluation_dataset.json
diff --git a/..._generation/evaluation/eval_end_to_end.py → ..._generation/evaluation/eval_end_to_end.py b/..._generation/evaluation/eval_end_to_end.py → ..._generation/evaluation/eval_end_to_end.py
diff --git a/...d_generation/evaluation/eval_retrieval.py → ...d_generation/evaluation/eval_retrieval.py b/...d_generation/evaluation/eval_retrieval.py → ...d_generation/evaluation/eval_retrieval.py
diff --git a/...sults/evaluation_results_level_three.json → ...sults/evaluation_results_level_three.json b/...sults/evaluation_results_level_three.json → ...sults/evaluation_results_level_three.json
diff --git a/...results/evaluation_results_level_two.json → ...results/evaluation_results_level_two.json b/...results/evaluation_results_level_two.json → ...results/evaluation_results_level_two.json
diff --git a/.../json_results/evaluation_results_one.json → .../json_results/evaluation_results_one.json b/.../json_results/evaluation_results_one.json → .../json_results/evaluation_results_one.json
diff --git a/...promptfoo_datasets/end_to_end_dataset.csv → ...promptfoo_datasets/end_to_end_dataset.csv b/...promptfoo_datasets/end_to_end_dataset.csv → ...promptfoo_datasets/end_to_end_dataset.csv
diff --git a/.../promptfoo_datasets/retrieval_dataset.csv → .../promptfoo_datasets/retrieval_dataset.csv b/.../promptfoo_datasets/retrieval_dataset.csv → .../promptfoo_datasets/retrieval_dataset.csv
diff --git a/...valuation/promptfooconfig_end_to_end.yaml → ...valuation/promptfooconfig_end_to_end.yaml b/...valuation/promptfooconfig_end_to_end.yaml → ...valuation/promptfooconfig_end_to_end.yaml
diff --git a/...evaluation/promptfooconfig_retrieval.yaml → ...evaluation/promptfooconfig_retrieval.yaml b/...evaluation/promptfooconfig_retrieval.yaml → ...evaluation/promptfooconfig_retrieval.yaml
diff --git a/...ugmented_generation/evaluation/prompts.py → ...ugmented_generation/evaluation/prompts.py b/...ugmented_generation/evaluation/prompts.py → ...ugmented_generation/evaluation/prompts.py
diff --git a/...neration/evaluation/provider_retrieval.py → ...neration/evaluation/provider_retrieval.py b/...neration/evaluation/provider_retrieval.py → ...neration/evaluation/provider_retrieval.py
diff --git a/...gmented_generation/evaluation/vectordb.py → ...gmented_generation/evaluation/vectordb.py b/...gmented_generation/evaluation/vectordb.py → ...gmented_generation/evaluation/vectordb.py
diff --git a/...etrieval_augmented_generation/guide.ipynb → ...etrieval_augmented_generation/guide.ipynb b/...etrieval_augmented_generation/guide.ipynb → ...etrieval_augmented_generation/guide.ipynb
diff --git a/skills/summarization/README.md → capabilities/summarization/README.md b/skills/summarization/README.md → capabilities/summarization/README.md
diff --git a/...zation/data/Sample Sublease Agreement.pdf → ...zation/data/Sample Sublease Agreement.pdf b/...zation/data/Sample Sublease Agreement.pdf → ...zation/data/Sample Sublease Agreement.pdf
diff --git a/.../summarization/data/multiple_subleases.py → .../summarization/data/multiple_subleases.py b/.../summarization/data/multiple_subleases.py → .../summarization/data/multiple_subleases.py
diff --git a/skills/summarization/data/results.csv → capabilities/summarization/data/results.csv b/skills/summarization/data/results.csv → capabilities/summarization/data/results.csv
diff --git a/...marization/data/sample-lease1-summary.txt → ...marization/data/sample-lease1-summary.txt b/...marization/data/sample-lease1-summary.txt → ...marization/data/sample-lease1-summary.txt
diff --git a/skills/summarization/data/sample-lease1.txt → ...ties/summarization/data/sample-lease1.txt b/skills/summarization/data/sample-lease1.txt → ...ties/summarization/data/sample-lease1.txt
diff --git a/...marization/data/sample-lease2-summary.txt → ...marization/data/sample-lease2-summary.txt b/...marization/data/sample-lease2-summary.txt → ...marization/data/sample-lease2-summary.txt
diff --git a/skills/summarization/data/sample-lease2.txt → ...ties/summarization/data/sample-lease2.txt b/skills/summarization/data/sample-lease2.txt → ...ties/summarization/data/sample-lease2.txt
diff --git a/...marization/data/sample-lease3-summary.txt → ...marization/data/sample-lease3-summary.txt b/...marization/data/sample-lease3-summary.txt → ...marization/data/sample-lease3-summary.txt
diff --git a/skills/summarization/data/sample-lease3.txt → ...ties/summarization/data/sample-lease3.txt b/skills/summarization/data/sample-lease3.txt → ...ties/summarization/data/sample-lease3.txt
diff --git a/...marization/data/sample-lease4-summary.txt → ...marization/data/sample-lease4-summary.txt b/...marization/data/sample-lease4-summary.txt → ...marization/data/sample-lease4-summary.txt
diff --git a/skills/summarization/data/sample-lease4.txt → ...ties/summarization/data/sample-lease4.txt b/skills/summarization/data/sample-lease4.txt → ...ties/summarization/data/sample-lease4.txt
diff --git a/...marization/data/sample-lease5-summary.txt → ...marization/data/sample-lease5-summary.txt b/...marization/data/sample-lease5-summary.txt → ...marization/data/sample-lease5-summary.txt
diff --git a/skills/summarization/data/sample-lease5.txt → ...ties/summarization/data/sample-lease5.txt b/skills/summarization/data/sample-lease5.txt → ...ties/summarization/data/sample-lease5.txt
diff --git a/...marization/data/sample-lease6-summary.txt → ...marization/data/sample-lease6-summary.txt b/...marization/data/sample-lease6-summary.txt → ...marization/data/sample-lease6-summary.txt
diff --git a/skills/summarization/data/sample-lease6.txt → ...ties/summarization/data/sample-lease6.txt b/skills/summarization/data/sample-lease6.txt → ...ties/summarization/data/sample-lease6.txt
diff --git a/...marization/data/sample-lease7-summary.txt → ...marization/data/sample-lease7-summary.txt b/...marization/data/sample-lease7-summary.txt → ...marization/data/sample-lease7-summary.txt
diff --git a/skills/summarization/data/sample-lease7.txt → ...ties/summarization/data/sample-lease7.txt b/skills/summarization/data/sample-lease7.txt → ...ties/summarization/data/sample-lease7.txt
diff --git a/...marization/data/sample-lease8-summary.txt → ...marization/data/sample-lease8-summary.txt b/...marization/data/sample-lease8-summary.txt → ...marization/data/sample-lease8-summary.txt
diff --git a/skills/summarization/data/sample-lease8.txt → ...ties/summarization/data/sample-lease8.txt b/skills/summarization/data/sample-lease8.txt → ...ties/summarization/data/sample-lease8.txt
diff --git a/...marization/data/sample-lease9-summary.txt → ...marization/data/sample-lease9-summary.txt b/...marization/data/sample-lease9-summary.txt → ...marization/data/sample-lease9-summary.txt
diff --git a/skills/summarization/data/sample-lease9.txt → ...ties/summarization/data/sample-lease9.txt b/skills/summarization/data/sample-lease9.txt → ...ties/summarization/data/sample-lease9.txt
diff --git a/skills/summarization/evaluation/README.md → ...lities/summarization/evaluation/README.md b/skills/summarization/evaluation/README.md → ...lities/summarization/evaluation/README.md
diff --git a/...tion/evaluation/custom_evals/bleu_eval.py → ...tion/evaluation/custom_evals/bleu_eval.py b/...tion/evaluation/custom_evals/bleu_eval.py → ...tion/evaluation/custom_evals/bleu_eval.py
diff --git a/...ation/evaluation/custom_evals/llm_eval.py → ...ation/evaluation/custom_evals/llm_eval.py b/...ation/evaluation/custom_evals/llm_eval.py → ...ation/evaluation/custom_evals/llm_eval.py
diff --git a/...ion/evaluation/custom_evals/rouge_eval.py → ...ion/evaluation/custom_evals/rouge_eval.py b/...ion/evaluation/custom_evals/rouge_eval.py → ...ion/evaluation/custom_evals/rouge_eval.py
diff --git a/...arization/evaluation/promptfooconfig.yaml → ...arization/evaluation/promptfooconfig.yaml b/...arization/evaluation/promptfooconfig.yaml → ...arization/evaluation/promptfooconfig.yaml
diff --git a/skills/summarization/evaluation/prompts.py → ...ities/summarization/evaluation/prompts.py b/skills/summarization/evaluation/prompts.py → ...ities/summarization/evaluation/prompts.py
diff --git a/skills/summarization/evaluation/tests.yaml → ...ities/summarization/evaluation/tests.yaml b/skills/summarization/evaluation/tests.yaml → ...ities/summarization/evaluation/tests.yaml
diff --git a/skills/summarization/guide.ipynb → capabilities/summarization/guide.ipynb b/skills/summarization/guide.ipynb → capabilities/summarization/guide.ipynb
diff --git a/skills/text_to_sql/README.md → capabilities/text_to_sql/README.md b/skills/text_to_sql/README.md → capabilities/text_to_sql/README.md
diff --git a/skills/text_to_sql/data/data.db → capabilities/text_to_sql/data/data.db b/skills/text_to_sql/data/data.db → capabilities/text_to_sql/data/data.db
diff --git a/skills/text_to_sql/data/results.csv → capabilities/text_to_sql/data/results.csv b/skills/text_to_sql/data/results.csv → capabilities/text_to_sql/data/results.csv
diff --git a/skills/text_to_sql/data/vector_db.pkl → capabilities/text_to_sql/data/vector_db.pkl b/skills/text_to_sql/data/vector_db.pkl → capabilities/text_to_sql/data/vector_db.pkl
diff --git a/skills/text_to_sql/evaluation/README.md → ...bilities/text_to_sql/evaluation/README.md b/skills/text_to_sql/evaluation/README.md → ...bilities/text_to_sql/evaluation/README.md
diff --git a/...xt_to_sql/evaluation/promptfooconfig.yaml → ...xt_to_sql/evaluation/promptfooconfig.yaml b/...xt_to_sql/evaluation/promptfooconfig.yaml → ...xt_to_sql/evaluation/promptfooconfig.yaml
diff --git a/skills/text_to_sql/evaluation/prompts.py → ...ilities/text_to_sql/evaluation/prompts.py b/skills/text_to_sql/evaluation/prompts.py → ...ilities/text_to_sql/evaluation/prompts.py
diff --git a/...uation/tests/test_above_average_salary.py → ...uation/tests/test_above_average_salary.py b/...uation/tests/test_above_average_salary.py → ...uation/tests/test_above_average_salary.py
diff --git a/...l/evaluation/tests/test_average_salary.py → ...l/evaluation/tests/test_average_salary.py b/...l/evaluation/tests/test_average_salary.py → ...l/evaluation/tests/test_average_salary.py
diff --git a/...valuation/tests/test_budget_allocation.py → ...valuation/tests/test_budget_allocation.py b/...valuation/tests/test_budget_allocation.py → ...valuation/tests/test_budget_allocation.py
diff --git a/...l/evaluation/tests/test_employee_count.py → ...l/evaluation/tests/test_employee_count.py b/...l/evaluation/tests/test_employee_count.py → ...l/evaluation/tests/test_employee_count.py
diff --git a/...evaluation/tests/test_employee_details.py → ...evaluation/tests/test_employee_details.py b/...evaluation/tests/test_employee_details.py → ...evaluation/tests/test_employee_details.py
diff --git a/...aluation/tests/test_hierarchical_query.py → ...aluation/tests/test_hierarchical_query.py b/...aluation/tests/test_hierarchical_query.py → ...aluation/tests/test_hierarchical_query.py
diff --git a/...sql/evaluation/tests/test_simple_query.py → ...sql/evaluation/tests/test_simple_query.py b/...sql/evaluation/tests/test_simple_query.py → ...sql/evaluation/tests/test_simple_query.py
diff --git a/skills/text_to_sql/evaluation/tests/utils.py → ...ies/text_to_sql/evaluation/tests/utils.py b/skills/text_to_sql/evaluation/tests/utils.py → ...ies/text_to_sql/evaluation/tests/utils.py
diff --git a/skills/text_to_sql/evaluation/vectordb.py → ...lities/text_to_sql/evaluation/vectordb.py b/skills/text_to_sql/evaluation/vectordb.py → ...lities/text_to_sql/evaluation/vectordb.py
diff --git a/skills/text_to_sql/guide.ipynb → capabilities/text_to_sql/guide.ipynb b/skills/text_to_sql/guide.ipynb → capabilities/text_to_sql/guide.ipynb
diff --git a/skills/.claude/hooks/pre-bash.sh b/skills/.claude/hooks/pre-bash.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+# PreToolUse Hook - Bash Safety Check
+# Prevents dangerous commands and provides helpful reminders
+
+set -e
+
+TOOL_NAME="$1"
+COMMAND="$2"
+
+# Only run for Bash tool
+if [[ "$TOOL_NAME" != "Bash" ]]; then
+    exit 0
+fi
+
+# Check for potentially dangerous commands
+if [[ "$COMMAND" == *"rm -rf outputs"* ]] || [[ "$COMMAND" == *"rm -rf sample_data"* ]]; then
+    echo "⚠️  WARNING: Attempting to delete important directory!"
+    echo "Command: $COMMAND"
+    echo "These directories contain generated files and sample data."
+    # Allow but warn
+fi
+
+# Warn about pip install without using requirements.txt
+if [[ "$COMMAND" == *"pip install"* ]] && [[ "$COMMAND" != *"requirements.txt"* ]]; then
+    echo "ℹ️  Installing package directly. Consider updating requirements.txt"
+fi
+
+# Remind about kernel restart after SDK reinstall
+if [[ "$COMMAND" == *"pip install"* ]] && [[ "$COMMAND" == *"anthropic"* ]]; then
+    echo "ℹ️  Remember: Restart Jupyter kernel after SDK installation!"
+fi
+
+# Warn if trying to start jupyter/servers
+if [[ "$COMMAND" == *"jupyter notebook"* ]] || [[ "$COMMAND" == *"jupyter lab"* ]]; then
+    echo "ℹ️  Starting Jupyter. Make sure to select the venv kernel in notebooks."
+fi
+
+exit 0
diff --git a/skills/.claude/hooks/pre-write.sh b/skills/.claude/hooks/pre-write.sh
@@ -0,0 +1,39 @@
+#!/bin/bash
+# PreToolUse Hook - Write Safety Check
+# Prevents accidental overwrites of key files
+
+set -e
+
+TOOL_NAME="$1"
+FILE_PATH="$2"
+
+# Only run for Write tool
+if [[ "$TOOL_NAME" != "Write" ]]; then
+    exit 0
+fi
+
+# Protected files - should never be overwritten without explicit user request
+PROTECTED_FILES=(
+    ".env"
+    "requirements.txt"
+)
+
+for protected in "${PROTECTED_FILES[@]}"; do
+    if [[ "$FILE_PATH" == *"$protected"* ]]; then
+        echo "⚠️  WARNING: Attempting to write to protected file: $FILE_PATH"
+        echo "This file should rarely be modified. Proceeding with caution..."
+        # Allow but warn - don't block
+    fi
+done
+
+# Warn if writing to notebooks/ without .ipynb extension
+if [[ "$FILE_PATH" == *"notebooks/"* ]] && [[ "$FILE_PATH" != *".ipynb" ]]; then
+    echo "⚠️  Writing non-notebook file to notebooks/ directory: $FILE_PATH"
+fi
+
+# Warn if writing to sample_data/
+if [[ "$FILE_PATH" == *"sample_data/"* ]]; then
+    echo "ℹ️  Modifying sample data: $FILE_PATH"
+fi
+
+exit 0
diff --git a/skills/.claude/hooks/session-start.sh b/skills/.claude/hooks/session-start.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# SessionStart Hook - Skills Cookbook Environment Check
+# This hook runs at the start of each Claude Code session to verify environment setup
+
+set -e
+
+echo "🔍 Skills Cookbook - Environment Check"
+echo "======================================"
+
+# Check if we're in a virtual environment
+if [[ -z "$VIRTUAL_ENV" ]]; then
+    echo "⚠️  WARNING: No virtual environment detected!"
+    echo "   Run: source venv/bin/activate"
+    echo ""
+fi
+
+# Check if Anthropic SDK is installed and get version
+if python -c "import anthropic" 2>/dev/null; then
+    SDK_VERSION=$(python -c "import anthropic; print(anthropic.__version__)" 2>/dev/null || echo "unknown")
+    echo "✅ Anthropic SDK: $SDK_VERSION"
+    # Check for minimum version for Skills support
+    if [[ "$SDK_VERSION" < "0.71.0" ]]; then
+        echo "⚠️  SDK version $SDK_VERSION may be too old (minimum 0.71.0 for Skills support)"
+        echo "   Run: pip install anthropic>=0.71.0"
+        echo ""
+    fi
+else
+    echo "❌ Anthropic SDK not installed"
+    echo "   Run: pip install -r requirements.txt"
+    echo ""
+fi
+
+# Check for API key
+if [[ -f ".env" ]]; then
+    if grep -q "^ANTHROPIC_API_KEY=sk-" .env 2>/dev/null; then
+        echo "✅ API key configured in .env"
+    else
+        echo "⚠️  .env exists but API key may not be set"
+        echo "   Check ANTHROPIC_API_KEY in .env"
+        echo ""
+    fi
+else
+    echo "⚠️  .env file not found"
+    echo "   Run: cp .env.example .env"
+    echo "   Then add your ANTHROPIC_API_KEY"
+    echo ""
+fi
+
+# Check outputs directory
+if [[ -d "outputs" ]]; then
+    FILE_COUNT=$(find outputs -type f 2>/dev/null | wc -l | tr -d ' ')
+    echo "✅ outputs/ directory exists ($FILE_COUNT files)"
+else
+    echo "ℹ️  Creating outputs/ directory..."
+    mkdir -p outputs
+fi
+
+# Show current status from plan
+if [[ -f "docs/skills_cookbook_plan.md" ]]; then
+    echo ""
+    echo "📊 Current Status:"
+    PHASE_STATUS=$(grep -A1 "^**Phase:**" docs/skills_cookbook_plan.md 2>/dev/null | tail -1 || echo "Unknown")
+    echo "   $PHASE_STATUS"
+fi
+
+echo ""
+echo "======================================"
+echo "Ready to work on Skills Cookbook! 🚀"
+echo ""
+echo "Quick commands:"
+echo "  - jupyter notebook              # Launch notebooks"
+echo "  - ls outputs/                   # View generated files"
+echo "  - cat CLAUDE.md                 # View project guide"
diff --git a/skills/.claude/settings.json b/skills/.claude/settings.json
@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "SessionStart": {
+      "command": ".claude/hooks/session-start.sh",
+      "description": "Verify Skills cookbook environment setup (SDK version, API key, directories)"
+    },
+    "PreToolUse": [
+      {
+        "command": ".claude/hooks/pre-write.sh",
+        "description": "Warn before overwriting protected files (whl, plan, sample data)",
+        "toolFilter": ["Write"]
+      },
+      {
+        "command": ".claude/hooks/pre-bash.sh",
+        "description": "Safety checks for bash commands (rm, pip install, jupyter)",
+        "toolFilter": ["Bash"]
+      }
+    ]
+  },
+  "contextFiles": [
+    "CLAUDE.md",
+    "docs/skills_cookbook_plan.md"
+  ],
+  "projectInfo": {
+    "name": "Skills Cookbook",
+    "type": "jupyter-notebooks",
+    "language": "python",
+    "description": "Educational cookbook for Claude Skills API with progressive notebooks"
+  }
+}
diff --git a/skills/.env.example b/skills/.env.example
@@ -0,0 +1,14 @@
+# Claude Skills Cookbook Configuration
+# Copy this file to .env and add your actual API key
+
+# Required: Your Anthropic API key from https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Model selection (Skills require Claude 4.5 Sonnet or newer)
+ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
+
+# Optional: Custom skills storage directory (default: ./custom_skills)
+SKILLS_STORAGE_PATH=./custom_skills
+
+# Optional: Output directory for generated files (default: ./outputs)
+OUTPUT_PATH=./outputs
diff --git a/skills/.gitignore b/skills/.gitignore
@@ -0,0 +1,38 @@
+# Environment and secrets
+.env
+*.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Generated outputs
+outputs/
+*.xlsx
+*.pptx
+*.pdf
+*.docx
+
+# Documentation sources - internal only
+docs/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db