improve skill defaults: ranks over scores, optional filters, github t…

SKILL.md

@@ -5,16 +5,17 @@ description: Query builder reputation data via Talent Protocol API. Get Builder
 
 # Talent Powers
 
-Query professioanl data from [Talent Protocol](https://talent.app) - a platform that tracks onchain builders
+Query professioanl data from [Talent Protocol](https://talent.app) - a platform that tracks builders
 
 **Use this skill to:**
 - Find verified developers by location, skills, or identity (Twitter/GitHub/Farcaster/wallet)
-- Check builder reputation scores and rankings
-- Map Twitter accounts with Wallets
+- Check builder reputation (ranks by default, scores only when asked)
+- Map Twitter accounts with Wallet addresses
 - Verify human identity from a wallet
 - Search for builder's credentials (earnings, contributions, hackathons, contracts, etc)
-- Discover what projects are being built by profiles
+- Check the projects each builder is shipping
 
+First get your API Key:
 **API Key:** https://talent.app/~/settings/api  
 **Base URL:** `https://api.talentprotocol.com`
 
@@ -31,8 +32,8 @@ curl -H "X-API-KEY: $TALENT_API_KEY" "https://api.talentprotocol.com/..."
 | `/accounts` | Get connected wallets, GitHub, socials |
 | `/socials` | Get social profiles + bios |
 | `/credentials` | Get data points (earnings, followers, hackathons, etc.) |
-| `/human_checkmark` | Check if human-verified |
-| `/farcaster/scores` | Batch lookup Farcaster users |
+| `/human_checkmark` | Check if human-verified (optional, don't use by default) |
+| `/scores` | Get ranks (default) or scores (only when explicitly asked) |
 
 ## Key Parameters
 
@@ -41,11 +42,11 @@ curl -H "X-API-KEY: $TALENT_API_KEY" "https://api.talentprotocol.com/..."
 query[identity]={handle}&query[identity_type]={twitter|github|farcaster|ens|wallet}
 ```
 
-**Filters:**
+**Filters (all optional, only use when relevant to the query):**
 ```
-query[human_checkmark]=true
-query[verified_nationality]=true
-query[tags][]=developer
+query[tags][]=developer              # filter by tag (developer, designer, etc.)
+query[verified_nationality]=true     # only verified nationality
+query[human_checkmark]=true          # only human-verified (reduces results significantly)
 ```
 
 **Sorting:**
@@ -61,9 +62,15 @@ sort[score][order]=desc&sort[score][scorer]=Builder%20Score
 
 ## Response Fields
 
-- `builder_score.rank_position` - Primary metric
+**Default → Ranks (always use unless user asks for scores):**
+- `builder_score.rank_position` - Primary rank metric
+- `scores[].rank_position` where `slug = "builder_score"` - Latest rank
+
+**Only when user explicitly asks for scores:**
+- `builder_score.points` - Score value
+- `scores[].points` - Individual score values
+
 - `location` - User-entered location (returned in response)
-- `scores[]` - Use `builder_score_2025` for latest rank
 
 ## Location Filter
 
@@ -83,7 +90,6 @@ curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json"
         }
       }
     },
-    "humanCheckmark": true,
     "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
     "perPage": 50
   }'
@@ -113,7 +119,9 @@ GET https://api.github.com/users/{username}/events/public             # Commits
 GET https://api.github.com/search/issues?q=author:{username}+type:pr+state:open  # Open PRs
 ```
 
-GitHub token: https://github.com/settings/tokens (60 req/hr without, 5000 with)
+**GitHub Token (recommended):** Without a token, GitHub limits to 60 requests/hr. With a personal access token, you get 5,000/hr.
+- Create one at: https://github.com/settings/tokens → "Generate new token (classic)" → no scopes needed for public data
+- Use it: `-H "Authorization: token $GITHUB_TOKEN"`
 
 ## References
 

references/endpoints.md

@@ -23,8 +23,8 @@ curl -H "X-API-KEY: $TALENT_API_KEY" \
 |-----------|---------|
 | `query[identity]` | `jessepollak` |
 | `query[identity_type]` | `twitter`, `github`, `farcaster`, `ens`, `wallet` |
-| `query[human_checkmark]` | `true` |
 | `query[verified_nationality]` | `true` |
+| `query[human_checkmark]` | `true` (optional - reduces results, only use when user asks) |
 | `query[tags][]` | `developer` |
 | `sort[score][order]` | `desc` |
 | `sort[score][scorer]` | `Builder Score` |
@@ -49,12 +49,13 @@ curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json"
         }
       }
     },
-    "humanCheckmark": true,
     "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
     "perPage": 50
   }'
 ```
 
+> **Note:** `"humanCheckmark": true` is optional. Don't include it by default — it reduces results. Only add when user explicitly asks.
+
 See [use-cases.md](use-cases.md#by-location-country) for more location examples.
 
 ### Response
@@ -71,13 +72,15 @@ See [use-cases.md](use-cases.md#by-location-country) for more location examples.
     "tags": ["developer"],
     "builder_score": { "rank_position": 127, "points": 229 },
     "scores": [
-      { "slug": "builder_score_2025", "rank_position": 154 }
+      { "slug": "builder_score", "rank_position": 154 }
     ]
   }],
   "pagination": { "current_page": 1, "total": 100 }
 }
 ```
 
+**Default:** Use `rank_position` fields. Only include `points` when user explicitly asks for scores.
+
 ---
 
 ## /profile

references/use-cases.md

@@ -9,7 +9,8 @@
 ```bash
 # 1. Search by identity
 curl -H "X-API-KEY: $TALENT_API_KEY" \
-  "https://api.talentprotocol.com/search/advanced/profiles?query%5Bidentity%5D=jessepollak&query%5Bidentity_type%5D=twitter"
+  "https://api.talentprotocol.com/search/advanced/profiles?query%5Bidentity%5D={handle}&query%5Bidentity_type%5D={identity_type}"
+# Response: profiles[0].id → use as profile_id
 
 # 2. Get wallets from profile ID
 curl -H "X-API-KEY: $TALENT_API_KEY" \
@@ -21,28 +22,30 @@ curl -H "X-API-KEY: $TALENT_API_KEY" \
 
 ---
 
-## Get Rank
+## Get Rank (default behavior)
 
 Response from `/search/advanced/profiles` includes:
 
 ```json
 {
   "builder_score": { "rank_position": 127 },
   "scores": [
-    { "slug": "builder_score_2025", "rank_position": 154 }
+    { "slug": "builder_score", "rank_position": 154 }
   ]
 }
 ```
 
-Use `builder_score_2025.rank_position` for latest rank.
+**Default:** Always return `rank_position` values. Use `builder_score.rank_position` for latest rank.
+
+**Only when user explicitly asks for scores:** include `points` values from `builder_score.points` or `scores[].points`.
 
 ---
 
-## Top Builders
+## Get the Top Builders
 
 ```bash
 curl -H "X-API-KEY: $TALENT_API_KEY" \
-  "https://api.talentprotocol.com/search/advanced/profiles?query%5Bhuman_checkmark%5D=true&sort%5Bscore%5D%5Border%5D=desc&sort%5Bscore%5D%5Bscorer%5D=Builder%20Score&per_page=250"
+  "https://api.talentprotocol.com/search/advanced/profiles?sort%5Bscore%5D%5Border%5D=desc&sort%5Bscore%5D%5Bscorer%5D=Builder%20Score&per_page=250"
 ```
 
 ---
@@ -67,7 +70,6 @@ curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json"
         }
       }
     },
-    "humanCheckmark": true,
     "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
     "perPage": 50
   }'
@@ -87,7 +89,6 @@ curl -X POST -H "X-API-KEY: $TALENT_API_KEY" -H "Content-Type: application/json"
         }
       }
     },
-    "humanCheckmark": true,
     "sort": { "score": { "order": "desc", "scorer": "Builder Score" } },
     "perPage": 50
   }'
@@ -124,7 +125,14 @@ This matches locations ending with ", argentina" (e.g., "Buenos Aires, Argentina
 
 All from `/credentials?id={profile_id}`.
 
-**Example queries** (there are many more available):
+**Discover all available data points:** Use `/data_issuers_meta` to get the full list of data issuers and credential slugs available. [API docs](https://docs.talentprotocol.com/docs/talent-api/api-reference/get-data-issuers-and-credentials-available)
+
+```bash
+curl -H "X-API-KEY: $TALENT_API_KEY" \
+  "https://api.talentprotocol.com/data_issuers_meta"
+```
+
+**Common credential slugs:**
 
 | Data | Slug |
 |------|------|