Refactor chicago-data-portal skill for better usability (v1.2.0)

.claude-plugin/marketplace.json

@@ -13,9 +13,9 @@
       "name": "chicago-data-portal",
       "source": "./skills/chicago-data-portal",
       "description": "Query Chicago's open data using Socrata/SODA API",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "license": "MIT",
-      "keywords": ["chicago", "open-data", "socrata", "soda"]
+      "keywords": ["chicago", "open-data", "socrata", "soda", "crime", "311", "permits"]
     },
     {
       "name": "cook-county-data-portal",

CHANGELOG.md

@@ -7,8 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **chicago-data-portal** skill (v1.2.0): Major refactor for better usability and progressive disclosure
+  - **SKILL.md**: Streamlined from ~200 lines to ~110 lines focused on quick-start workflow
+    - New quick reference table for common endpoints
+    - Simplified auth check section
+    - Essential SoQL examples inline, detailed reference moved to `references/`
+    - Cleaner output template
+  - **references/popular-datasets.md**: Expanded with decision tree lookup table ("If user asks about X, use Y dataset")
+    - Added more datasets: Employee Salaries, Divvy Stations, Lobbyist Data
+    - Richer column documentation and common values
+    - Better categorization (Public Safety, City Services, Business & Permits, Transportation, Government)
+  - **references/soql-quick-ref.md**: Enhanced with more practical examples
+    - Added common query patterns section (pagination, time series, aggregations)
+    - Better date function examples with `date_trunc_ym` for grouping
+    - Added `contains()` text function
+  - **references/geospatial.md**: New reference file for location-based queries
+    - Coordinate ordering warning (lat/lon vs lon/lat gotcha)
+    - Common Chicago landmark coordinates
+    - Examples combining spatial + other filters
+  - **examples/typescript-query.ts**: New TypeScript/JavaScript example
+    - Async/await with fetch API
+    - Typed interfaces for query params and metadata
+    - AsyncGenerator for pagination
+  - **examples/python-query.py**: Expanded with more practical examples
+    - Added `get_all_results()` helper for pagination
+    - Time series example (monthly counts)
+    - Food inspections analysis example
+  - **examples/curl-examples.sh**: More organized with clear sections
+    - Added filtering, aggregation, and geospatial sections
+    - Dataset-specific examples for permits, licenses, crashes
+
 ### Added
 
+- **Test Infrastructure**: Integration tests for skill API examples
+  - `tests/` directory with pytest-based test suite
+  - `test_chicago_data_portal.py`: 17 tests covering basic queries, metadata, filtering, aggregation, geospatial, pagination, and error handling
+  - Tests marked with `@pytest.mark.live` for easy skip when offline
+  - Shared fixtures in `conftest.py` for app tokens across skills
+  - Documentation in `tests/README.md`
+
 - **Plugin Marketplace Support**: Repository can now be added as a Claude Code plugin marketplace
   - `.claude-plugin/marketplace.json` manifest with all plugins listed
   - Individual `plugin.json` files for each skill

skills/chicago-data-portal/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "chicago-data-portal",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Query Chicago's open data using Socrata/SODA API",
   "license": "MIT",
   "skills": "./"

skills/chicago-data-portal/README.md

@@ -1,6 +1,6 @@
 # Chicago Data Portal
 
-Query and download datasets from the City of Chicago Data Portal using the Socrata Open Data API (SODA) and SoQL.
+Query and download datasets from the City of Chicago Open Data Portal using the Socrata SODA API and SoQL.
 
 ## Triggers
 
@@ -12,7 +12,7 @@ This skill activates when you ask Claude to:
 - "write a SODA query for Chicago"
 - "search data.cityofchicago.org"
 
-Or when you mention Chicago city data (311 requests, permits, licenses, inspections, crimes, etc.).
+Or when you mention Chicago city data (311 requests, permits, licenses, inspections, crimes, traffic crashes, etc.).
 
 ## Installation
 
@@ -22,7 +22,12 @@ Copy this skill folder to your project's `.claude/plugins/` directory:
 cp -r skills/chicago-data-portal /path/to/your/project/.claude/plugins/
 ```
 
-Or clone the entire repo and reference it in your Claude Code settings for global access.
+Or install from the plugin marketplace:
+
+```
+/plugin marketplace add MisterClean/claude-plugins
+/plugin install chicago-data-portal@misterclean-plugins
+```
 
 ## Usage
 
@@ -34,20 +39,46 @@ Once installed, just ask Claude naturally:
 
 > "Get 311 service requests for potholes by ward"
 
-Claude will automatically use this skill to discover datasets, build SoQL queries, and retrieve the data.
+> "Show me food inspections that failed near Wrigley Field"
+
+Claude will automatically discover datasets, build SoQL queries, and retrieve data.
 
 ## Contents
 
 | File | Description |
 |------|-------------|
 | [SKILL.md](./SKILL.md) | Core instructions and workflow |
-| [references/popular-datasets.md](./references/popular-datasets.md) | Commonly requested datasets with IDs |
-| [references/soql-quick-ref.md](./references/soql-quick-ref.md) | SoQL syntax reference |
-| [examples/curl-examples.sh](./examples/curl-examples.sh) | Sample curl commands |
-| [examples/python-query.py](./examples/python-query.py) | Python query example |
+| [references/popular-datasets.md](./references/popular-datasets.md) | Dataset lookup table with IDs and columns |
+| [references/soql-quick-ref.md](./references/soql-quick-ref.md) | Complete SoQL syntax reference |
+| [references/geospatial.md](./references/geospatial.md) | Location queries and coordinate systems |
+| [examples/curl-examples.sh](./examples/curl-examples.sh) | Ready-to-run curl commands |
+| [examples/python-query.py](./examples/python-query.py) | Python with requests + pandas |
+| [examples/typescript-query.ts](./examples/typescript-query.ts) | TypeScript/JavaScript fetch examples |
+
+## Popular Datasets
+
+| Dataset | ID | Use Case |
+|---------|-----|----------|
+| Crimes | `ijzp-q8t2` | Crime analysis, safety research |
+| 311 Service Requests | `v6vf-nfxy` | City services, complaints |
+| Building Permits | `ydr8-5enu` | Construction, development |
+| Food Inspections | `4ijn-s7e5` | Restaurant health scores |
+| Traffic Crashes | `85ca-t3if` | Accident analysis |
+| Business Licenses | `r5kz-chrr` | Business activity |
+
+See [references/popular-datasets.md](./references/popular-datasets.md) for the full list.
+
+## Authentication
+
+Queries work without authentication but are rate-limited. For production use, get a free app token:
+
+1. Sign up at https://data.cityofchicago.org/signup
+2. Go to Developer Settings and create an app token
+3. Add to your `.env` file: `CHICAGO_DATA_PORTAL_TOKEN=your_token_here`
 
 ## Resources
 
 - [Chicago Data Portal](https://data.cityofchicago.org)
 - [SODA API Documentation](https://dev.socrata.com/)
+- [SoQL Reference](https://dev.socrata.com/docs/queries/)
 - [Main Repository](../../README.md)