feat: improve skill scores across 5 skills

sources/anthropic/check_bounding_boxes/SKILL.md

@@ -1,10 +1,40 @@
 ---
-description: Imported skill check_bounding_boxes from anthropic
-name: check_bounding_boxes
+description: "Use when validating that PDF form-field bounding boxes in a fields.json file do not overlap and that entry boxes are tall enough for their font size."
+name: check-bounding-boxes
 signature: eb2a5f79c8aa10c57b5867e1f0fc75b52a68b1218442ef9d838dfb4b9eedc6f4
 source: /a0/tmp/skills_research/anthropic/skills/pdf/scripts/check_bounding_boxes.py
 ---
 
+# Check Bounding Boxes
+
+Validation script that checks a `fields.json` file (produced by Claude's PDF form analysis) for overlapping label/entry bounding boxes and entries that are too short for their font size.
+
+## When to Use
+
+- After generating `fields.json` from a PDF form analysis workflow
+- Validating bounding-box geometry before filling PDF form fields
+- Debugging "FAILURE" messages from the PDF annotation pipeline
+- As a CI gate to catch bounding-box regressions
+
+## Usage
+
+```bash
+python check_bounding_boxes.py fields.json
+```
+
+**Output**: Prints per-field validation messages. Exits with `SUCCESS` if all boxes are valid, or lists up to 20 failures before aborting.
+
+## Checks Performed
+
+| Check | Condition |
+|-------|-----------|
+| Overlap detection | No two label/entry boxes on the same page may intersect |
+| Height validation | Entry box height must be ≥ font size of contained text |
+| Early abort | Stops after 20 failures to keep output manageable |
+
+## Implementation
+
+```python
 from dataclasses import dataclass
 import json
 import sys

sources/anthropic/mcp_best_practices/SKILL.md

@@ -1,12 +1,22 @@
 ---
-description: Imported skill mcp_best_practices from anthropic
-name: mcp_best_practices
+description: "Use when building, reviewing, or debugging an MCP server to follow standard conventions for naming, tool design, transport selection, security, pagination, and error handling."
+name: mcp-best-practices
 signature: 80fb4369a349447cf18ecdd7494fe7938b6065377e9f08c077cec411093a3007
 source: /a0/tmp/skills_research/anthropic/skills/mcp-builder/reference/mcp_best_practices.md
 ---
 
 # MCP Server Best Practices
 
+Comprehensive reference for building production-quality MCP (Model Context Protocol) servers. Covers naming conventions, tool design, transport selection, security hardening, pagination, error handling, and testing requirements.
+
+## When to Use
+
+- Scaffolding a new MCP server (Python or Node/TypeScript)
+- Designing tool schemas with proper naming and annotations
+- Choosing between stdio and streamable HTTP transport
+- Implementing pagination, error handling, or authentication
+- Reviewing an MCP server for security and design compliance
+
 ## Quick Reference
 
 ### Server Naming

sources/langchain/chat_input/SKILL.md

@@ -1,10 +1,40 @@
 ---
-description: Imported skill chat_input from langchain
-name: chat_input
+description: "Use when building or customizing a Textual-based chat input widget with autocomplete, slash-command support, and persistent command history for deepagents-cli."
+name: chat-input
 signature: 6e0e51d27a6f70ccb7bfcbc1333f0d62cfa825ed5b96ade9bd5bd1349393cf0e
 source: /a0/tmp/skills_research/langchain/libs/deepagents-cli/deepagents_cli/widgets/chat_input.py
 ---
 
+# Chat Input Widget
+
+Reference implementation of a Textual chat input widget for deepagents-cli with autocomplete, slash commands, file completion, and persistent history.
+
+## When to Use
+
+- Building a terminal chat UI that needs multi-line input with Enter-to-submit
+- Adding autocomplete for slash commands (`/`) and file paths (`@`)
+- Integrating persistent command history with up/down arrow navigation
+- Customizing input modes (normal, bash `!`, command `/`)
+
+## Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| `ChatInput` | Main widget — composes text area + completion popup |
+| `ChatTextArea` | TextArea subclass with submit-on-Enter and history navigation |
+| `CompletionPopup` | Renders autocomplete suggestions as a rich overlay |
+
+## Input Behavior
+
+- **Enter**: Submit input
+- **Shift+Enter / Ctrl+J**: Insert newline
+- **Up/Down** (first/last line): Navigate command history
+- **Tab**: Accept completion suggestion
+- Mode detection: `!` prefix → bash mode, `/` prefix → command mode
+
+## Implementation
+
+```python
 """Chat input widget for deepagents-cli with autocomplete and history support."""
 
 from __future__ import annotations

sources/openai/advanced_search/SKILL.md

@@ -1,12 +1,21 @@
 ---
-description: Imported skill advanced_search from openai
-name: advanced_search
+description: "Use when performing targeted Notion workspace searches with date, creator, teamspace, and page-scoped filters to retrieve precise research results."
+name: advanced-search
 signature: f9c70a3b731ce76f35aee7caa53888cc8b22dadc17dd0f54cce95933a0cbbe91
 source: /a0/tmp/skills_research/openai/skills/.curated/notion-research-documentation/reference/advanced-search.md
 ---
 
 # Advanced Search Techniques
 
+Structured guide for performing filtered, scoped, and multi-query searches against a Notion workspace. Covers filter composition, search strategies, result prioritization, and connected-source attribution.
+
+## When to Use
+
+- Narrowing broad Notion search results using date, creator, or scope filters
+- Building multi-query research workflows across teamspaces
+- Processing and prioritizing large result sets efficiently
+- Searching connected sources (Slack, Google Drive, GitHub, Jira)
+
 ## Search Filtering
 
 ### By Date Range

sources/openai/comparison_template/SKILL.md

@@ -1,13 +1,30 @@
 ---
-description: Imported skill comparison_template from openai
-name: comparison_template
+description: "Use when structuring a side-by-side comparison of multiple options, tools, or approaches with a matrix, per-option analysis, and a final recommendation."
+name: comparison-template
 signature: 4c3af7b72a704beb22ab8741e97d26830421dbb5f489fdc53509fdcbe4000f2f
 source: /a0/tmp/skills_research/openai/skills/.curated/notion-research-documentation/reference/comparison-template.md
 ---
 
 # Comparison Template
 
-Use when researching multiple options or alternatives. See [comparison-format.md](comparison-format.md) for when to use this format.
+Reusable template for researching and documenting side-by-side comparisons of multiple options or alternatives. Produces a structured deliverable with a comparison matrix, per-option analysis, and a justified recommendation.
+
+## When to Use
+
+- Evaluating competing tools, libraries, or services
+- Documenting technology selection decisions
+- Comparing approaches to a design or architecture problem
+- Creating structured research deliverables for stakeholders
+
+## Workflow
+
+1. **Define criteria** — identify the dimensions that matter (cost, performance, ease of use, etc.)
+2. **Research each option** — gather data from Notion pages, docs, or external sources
+3. **Fill the matrix** — populate the comparison table with ratings or details
+4. **Analyze trade-offs** — list pros, cons, and ideal use case per option
+5. **Recommend** — state the selected option and the rationale
+
+## Template
 
 ```markdown
 # [Topic] Comparison
@@ -49,3 +66,14 @@ Use when researching multiple options or alternatives. See [comparison-format.md
 [List all consulted pages]
 ```
 
+## Example
+
+A filled comparison for choosing a database:
+
+| Criteria | PostgreSQL | DynamoDB | SQLite |
+|----------|-----------|----------|--------|
+| Scalability | Vertical + read replicas | Horizontal, auto-scaling | Single-node |
+| Cost | Server hosting | Pay-per-request | Free / embedded |
+| Query flexibility | Full SQL | Key-value + GSI | Full SQL |
+| Best for | General-purpose web apps | High-throughput serverless | Local / embedded apps |
+