feat: improve api-setup skill score from 39% to 93%

api-setup/SKILL.md

@@ -1,55 +1,78 @@
 ---
 name: api-setup
-description: Set up API integration with configuration and helper scripts
+description: "Scaffold a new REST API integration by generating a config file, setting up authentication, and verifying the connection. Use when the user asks to connect to an external API, configure API keys, set up API endpoints, or create a new API client integration."
 author: goose
 version: "1.0"
 tags:
   - api
   - integration
   - setup
+  - rest
+  - configuration
 ---
 
 # API Setup
 
-This skill helps you set up a new API integration with our standard configuration.
+Scaffold and configure a new API integration using the project's standard directory structure and config template.
+
+## Preconditions
+
+- The target API provider's documentation is accessible
+- An API key or credentials have been obtained from the provider's dashboard
 
 ## Steps
 
-1. Run `setup.sh <api-name>` to create the integration directory
-2. Copy `templates/config.template.json` to your integration directory
-3. Update the config with your API credentials
-4. Test the connection
+1. **Create the integration directory**
 
-## Configuration
+   ```bash
+   ./setup.sh <api-name>
+   ```
 
-The config template includes:
+   This creates `integrations/<api-name>/` and copies `templates/config.template.json` into it as `config.json`.
 
-- `api_key`: Your API key (get from the provider's dashboard)
-- `endpoint`: API endpoint URL
-- `timeout`: Request timeout in seconds (default: 30)
+2. **Configure the integration**
 
-## Verification
+   Edit `integrations/<api-name>/config.json` with the provider's details:
+
+   ```json
+   {
+     "api_key": "sk-live-abc123...",
+     "endpoint": "https://api.example.com/v1",
+     "timeout": 30,
+     "retry_attempts": 3
+   }
+   ```
 
-After setup, verify:
+   - `api_key`: The provider's API key — never commit real keys to version control
+   - `endpoint`: Base URL for the API (check the provider's docs for the correct version path)
+   - `timeout`: Request timeout in seconds — increase for slow or high-latency APIs
+   - `retry_attempts`: Automatic retries on transient failures (5xx, timeouts)
 
-- [ ] Config file is valid JSON
-- [ ] API key is set and not a placeholder
-- [ ] Test connection succeeds
+3. **Validate the config**
 
-## Troubleshooting
+   ```bash
+   python3 -m json.tool integrations/<api-name>/config.json
+   ```
 
-### Connection Timeout
+   Fix any JSON syntax errors before proceeding.
 
-If you experience connection timeouts:
+4. **Test the connection**
 
-1. Check your network connection
-2. Verify the endpoint URL is correct
-3. Increase the timeout value in config
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" \
+     -H "Authorization: Bearer $(jq -r .api_key integrations/<api-name>/config.json)" \
+     "$(jq -r .endpoint integrations/<api-name>/config.json)/health"
+   ```
+
+   A `200` response confirms the integration is working. A `401`/`403` means the API key is invalid or lacks required permissions.
+
+## Verification
 
-### Authentication Errors
+- [ ] `python3 -m json.tool integrations/<api-name>/config.json` exits cleanly
+- [ ] `api_key` is a real key, not the `YOUR_API_KEY_HERE` placeholder
+- [ ] Test connection returns HTTP 200
 
-If you get 401/403 errors:
+## Bundle Files
 
-1. Verify your API key is correct
-2. Check if the key has the required permissions
-3. Ensure the key hasn't expired
+- [`setup.sh`](setup.sh) — Creates the integration directory and copies the config template
+- [`templates/config.template.json`](templates/config.template.json) — Default config structure with placeholders