Add Cursor agent skills for SoundCloud API integration#541
Conversation
Publish focused skills for auth, discovery, and core integration rules alongside Agents.md, aligned with developer portal AI documentation. Co-authored-by: Cursor <cursoragent@cursor.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces structured 'Cursor Agent Skills' to facilitate AI-driven integration with the SoundCloud API, covering authentication (OAuth 2.1 with PKCE), discovery endpoints, and core integration rules like the use of URNs and cursor-based pagination. Feedback focuses on improving documentation consistency by recommending Basic Auth for token refresh flows and reinforcing the preference for cursor-based pagination over manual offsets. Additionally, it was suggested to explicitly mention the 'collection' key in response schemas to ensure agents correctly parse paginated results.
| curl -X POST "https://secure.soundcloud.com/oauth/token" \ | ||
| -H "Content-Type: application/x-www-form-urlencoded" \ | ||
| --data-urlencode "grant_type=refresh_token" \ | ||
| --data-urlencode "refresh_token=REFRESH_TOKEN" \ | ||
| --data-urlencode "client_id=CLIENT_ID" \ | ||
| --data-urlencode "client_secret=CLIENT_SECRET" |
There was a problem hiding this comment.
For consistency with the Client Credentials example and the core rules in soundcloud-api-integration/SKILL.md, consider using the Authorization: Basic header for the refresh token flow instead of passing the client secret in the request body. This follows standard OAuth 2.1 practices for confidential clients.
| curl -X POST "https://secure.soundcloud.com/oauth/token" \ | |
| -H "Content-Type: application/x-www-form-urlencoded" \ | |
| --data-urlencode "grant_type=refresh_token" \ | |
| --data-urlencode "refresh_token=REFRESH_TOKEN" \ | |
| --data-urlencode "client_id=CLIENT_ID" \ | |
| --data-urlencode "client_secret=CLIENT_SECRET" | |
| curl -X POST "https://secure.soundcloud.com/oauth/token" \ | |
| -H "Content-Type: application/x-www-form-urlencoded" \ | |
| -H "Authorization: Basic BASE64_CLIENT_ID_SECRET" \ | |
| --data-urlencode "grant_type=refresh_token" \ | |
| --data-urlencode "refresh_token=REFRESH_TOKEN" |
| ### Cursor-Based Paging (Preferred) | ||
| **AI Agents should prioritize cursor-based pagination over static page numbers.** * **Why:** Cursors are more resilient to real-time data changes and offer better performance for deep-scrolling large datasets. | ||
| * **Implementation:** Look for the `next_href` or `cursor` field in the API response. Use this entire URL or token for the subsequent request rather than manually incrementing an `offset | ||
| * **Implementation:** Look for the `next_href` field in the API response. Use that URL for the next request, or pass `linked_partitioning=true` with `limit` / `offset` as documented per endpoint. |
There was a problem hiding this comment.
The addition of "or pass linked_partitioning=true with limit / offset" is slightly confusing because the section's primary recommendation is to avoid manual offsets in favor of cursor-based paging. It is clearer to instruct the agent to use linked_partitioning=true on the initial request to obtain the next_href, and then exclusively follow that link for subsequent pages.
|
|
||
| - `user_urn`: full URN, e.g. `soundcloud:users:948745750` | ||
| - Response: user collection; paginate via `next_href` | ||
| - Same pagination model as related tracks (`limit`, `offset`, `linked_partitioning`) |
There was a problem hiding this comment.
To reinforce the preference for cursor-based paging, consider removing the reference to offset here. The agent should be encouraged to use linked_partitioning=true and follow the next_href provided in the response.
| - Same pagination model as related tracks (`limit`, `offset`, `linked_partitioning`) | |
| - Same pagination model as related tracks (limit, linked_partitioning) |
|
|
||
| 1. Accept `access_token` and resource URN as parameters | ||
| 2. Use `httpx` or `requests` | ||
| 3. Return `(items, next_href)` tuple |
There was a problem hiding this comment.
When linked_partitioning=true is active, the API returns results within a collection key in the response object. Specifying this in the function requirements will help the agent generate code that correctly extracts the results.
| 3. Return `(items, next_href)` tuple | |
| 3. Return (collection, next_href) tuple |
1 participant
Publish focused skills for auth, discovery, and core integration rules alongside Agents.md, aligned with developer portal AI documentation.