From 6e372126cab737290bd3e754fe4fc3a07865787b Mon Sep 17 00:00:00 2001 From: Yogesh Rao Date: Tue, 12 May 2026 12:04:09 +0530 Subject: [PATCH] =?UTF-8?q?feat:=20improve=20aiconfig-projects=20skill=20s?= =?UTF-8?q?core=20(47%=20=E2=86=92=2090%)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @nieblara ๐Ÿ‘‹ I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | aiconfig-projects | 47% | 90% | **+43%** | ## Summary - Rewrote `aiconfig-projects` skill description with concrete actions, third-person voice, and an explicit "Use when..." clause (description score: 33% โ†’ 100%) - Removed generic padding sections (Core Principles, What Are Projects?, Common Organization Patterns, What NOT to Do) that explained concepts the agent already knows - Added executable MCP tool call and REST API examples for project creation directly in the skill body - Added error recovery paths in the verification step (SDK init errors, 401/403, missing environments) - Collapsed the five-step workflow into a tighter four-step flow (Explore โ†’ Create โ†’ Implement โ†’ Verify)
Detailed changes **Description (frontmatter)** - Replaced vague description with specific actions: "Create and configure LaunchDarkly projects, extract SDK keys per environment, and verify SDK connectivity" - Added "Use when..." clause covering project creation, feature flag setup, SDK key extraction, and multi-team/region organization - Switched from second-person ("Helps you") to third-person voice **Content restructuring** - Removed ~110 lines of generic content: "What Are Projects?" explainer, "Core Principles" section, "Common Organization Patterns" examples, and "What NOT to Do" checklist - Merged Steps 1 and 2 into a single "Explore and Assess" step with inline scenario-routing table - Added concrete `create-project` MCP JSON payload and equivalent `curl` command in new Step 2 - Added explicit 409 Conflict handling guidance inline at the point of creation - Added three failure-recovery paths in verification: SDK key mismatch, permission errors, missing environments - Consolidated references section into a compact grouped format
I also stress-tested your `launchdarkly-flag-cleanup` skill against a few real-world task evals and it held up really well on safely removing launched flags while preserving production variation behavior. Kudos for that. Honest disclosure โ€” I work at @tesslio where we build tooling around skills like these. Not a pitch โ€” just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me โ€” [@yogesh-tessl](https://github.com/yogesh-tessl) โ€” if you hit any snags. ## Testing - [x] Manual (describe below) Ran `tessl skill review` before and after optimization. Score improved from 47% to 90%. All validation checks pass (valid frontmatter, name, description, compatibility, metadata). No changes to reference files or other skills. ## Notes - Only `aiconfig-projects/SKILL.md` is modified โ€” no other skills touched - All 9 reference files in `references/` are unchanged and still correctly linked - The skill's existing cross-references from `aiconfig-create` and `aiconfig-migrate` remain valid Thanks in advance ๐Ÿ™ --- skills/ai-configs/aiconfig-projects/SKILL.md | 235 +++++-------------- 1 file changed, 61 insertions(+), 174 deletions(-) diff --git a/skills/ai-configs/aiconfig-projects/SKILL.md b/skills/ai-configs/aiconfig-projects/SKILL.md index 38f327d..0a09671 100644 --- a/skills/ai-configs/aiconfig-projects/SKILL.md +++ b/skills/ai-configs/aiconfig-projects/SKILL.md @@ -1,6 +1,6 @@ --- name: aiconfig-projects -description: Guide for setting up LaunchDarkly projects in your codebase. Helps you assess your stack, choose the right approach, and integrate project management that makes sense for your architecture. +description: "Create and configure LaunchDarkly projects, extract SDK keys per environment, and verify SDK connectivity. Supports single-project setup, multi-service architectures, cross-region cloning, and IaC automation. Use when the user needs to create a LaunchDarkly project, set up feature flags for a new service, obtain SDK keys, or organize AI Configs across teams or regions." compatibility: Requires LaunchDarkly API access token with projects:write permission or LaunchDarkly MCP server. metadata: author: launchdarkly @@ -9,21 +9,12 @@ metadata: # LaunchDarkly Projects Setup -You're using a skill that will guide you through setting up LaunchDarkly project management in a codebase. Your job is to explore the codebase to understand the stack and patterns, assess what approach makes sense, choose the right implementation path from the references, execute the setup, and verify it works. - ## Prerequisites **Choose one:** - LaunchDarkly API access token with `projects:write` permission - LaunchDarkly MCP server configured in your environment -## Core Principles - -1. **Understand First**: Explore the codebase to understand the stack and patterns. -2. **Choose the Right Fit**: Select an approach that matches your architecture. -3. **Follow Conventions**: Respect existing code style and structure. -4. **Verify Integration**: Confirm the setup works: the agent performs checks and reports results. - ## API Key Detection Before prompting the user for an API key, try to detect it automatically: @@ -34,211 +25,107 @@ Before prompting the user for an API key, try to detect it automatically: See [Quick Start](references/quick-start.md) for API usage patterns. -## What Are Projects? - -Projects are LaunchDarkly's top-level organizational containers that hold: -- All your AI Configs -- Feature flags and segments -- Multiple environments (Production and Test created by default) - -Think of projects as separate applications, services, or teams that need their own isolated set of configurations. - ## Project Setup Workflow -### Step 1: Explore the Codebase - -Before implementing anything, understand the existing architecture: - -1. **Identify the tech stack:** - - What language(s)? (Python, Node.js, Go, Java, etc.) - - What framework(s)? (FastAPI, Express, Spring Boot, etc.) - - Is there an existing LaunchDarkly integration? - -2. **Check environment management:** - - How are environment variables stored? (.env files, secrets manager, config files) - - Where is configuration loaded? (startup scripts, config modules) - - Are there existing LaunchDarkly SDK keys? - -3. **Look for patterns:** - - Are there existing API clients or service modules? - - How is external API integration typically done? - - Is there a CLI, scripts directory, or admin tooling? - -4. **Understand the use case:** - - Is this a new project being set up? - - Adding to an existing LaunchDarkly integration? - - Part of a multi-service architecture? - - Need for project cloning across regions/teams? - -### Step 2: Assess the Situation +### Step 1: Explore and Assess -Based on your exploration, determine the right approach: +Identify the tech stack, existing LaunchDarkly usage, environment variable patterns, and the use case (new project, multi-service, cross-region, IaC). Then select the right approach: | Scenario | Recommended Path | |----------|------------------| -| New project, no LaunchDarkly integration | **Quick Setup** - Create project and save SDK keys | -| Existing LaunchDarkly usage | **Add to Existing** - Create new project or use existing | -| Multiple services/microservices | **Multi-Project** - Create projects per service | -| Multi-region or multi-tenant | **Project Cloning** - Clone template project | -| Infrastructure-as-Code (IaC) setup | **Automated Setup** - Script-based creation | -| Need project management tooling | **CLI/Admin Tools** - Build project management utilities | - -### Step 3: Choose Your Implementation Path - -Select the reference guide that matches your stack and use case: - -**By Language/Stack:** -- [Python Implementation](references/python-setup.md) - For Python applications (FastAPI, Django, Flask) -- [Node.js/TypeScript Implementation](references/nodejs-setup.md) - For Node.js/Express/NestJS applications -- [Go Implementation](references/go-setup.md) - For Go services -- [Multi-Language Setup](references/multi-language-setup.md) - For polyglot architectures - -**By Use Case:** -- [Quick Start](references/quick-start.md) - Create first project and get SDK keys -- [Environment Configuration](references/env-config.md) - Save SDK keys to .env, secrets, or config -- [Project Cloning](references/project-cloning.md) - Clone projects for regions/teams -- [IaC/Automation](references/iac-automation.md) - Terraform, scripts, CI/CD integration -- [Admin Tooling](references/admin-tooling.md) - Build CLI or admin utilities +| New project, no LaunchDarkly integration | [Quick Start](references/quick-start.md) โ€” create project and save SDK keys | +| Existing LaunchDarkly usage | Check existing projects first; create new or reuse | +| Multiple services/microservices | Create one project per service | +| Multi-region or multi-tenant | [Project Cloning](references/project-cloning.md) โ€” clone a template project | +| Infrastructure-as-Code setup | [IaC/Automation](references/iac-automation.md) โ€” Terraform, scripts, CI/CD | + +### Step 2: Create the Project + +**Via MCP (preferred):** + +Use the `create-project` MCP tool: +```json +{ + "name": "My AI Service", + "key": "my-ai-service", + "tags": ["ai-configs"] +} +``` -### Step 4: Implement the Integration +**Via REST API:** +```bash +curl -X POST "https://app.launchdarkly.com/api/v2/projects" \ + -H "Authorization: {api_token}" \ + -H "Content-Type: application/json" \ + -d '{"name": "My AI Service", "key": "my-ai-service", "tags": ["ai-configs"]}' +``` -Follow the chosen reference guide to implement project management. Key considerations: +Project keys: lowercase, hyphens only, must start with a letter (e.g. `support-ai`, `chat-bot-v2`). Keys are immutable after creation. -1. **API Authentication:** - - Store API token securely - - Follow existing secrets management patterns - - Never commit tokens to version control +**If the API returns 409 Conflict**, the key already exists โ€” use `get-project` to check whether the existing project is the right one before creating a different key. -2. **Project Naming:** - - Use consistent, descriptive names - - Follow existing naming conventions - - Project keys: lowercase, hyphens, start with letter +### Step 3: Choose Implementation Path -3. **SDK Key Management:** - - Extract and store SDK keys for each environment - - Use the same pattern as other secrets in your codebase - - Consider separate keys for test/staging/production +Select the reference guide that matches the stack: -4. **Error Handling:** - - Handle existing projects gracefully (409 conflict) - - Provide clear error messages - - Don't fail silently +**By Language:** +- [Python](references/python-setup.md) โ€” FastAPI, Django, Flask +- [Node.js/TypeScript](references/nodejs-setup.md) โ€” Express, NestJS +- [Go](references/go-setup.md) โ€” Go services +- [Multi-Language](references/multi-language-setup.md) โ€” Polyglot architectures -### Step 5: Verify the Setup +**By Use Case:** +- [Environment Configuration](references/env-config.md) โ€” Save SDK keys to .env, secrets, or config +- [Admin Tooling](references/admin-tooling.md) โ€” Build CLI or admin utilities -After creating the project, verify it works: +### Step 4: Verify the Setup -1. **Fetch to confirm it exists.** Prefer the MCP `get-project` tool over raw `curl` โ€” it returns a typed object you can inspect directly. If you must call the REST API: +1. **Confirm the project exists.** Prefer the MCP `get-project` tool. If using the REST API: ```bash curl -X GET "https://app.launchdarkly.com/api/v2/projects/{projectKey}?expand=environments" \ -H "Authorization: {api_token}" ``` - **Do not pipe the response straight into a `.environments.items[]`-style `jq` filter.** The shape of `environments` varies by `expand` parameter โ€” sometimes it's `{items: [...]}`, sometimes a bare array โ€” and a hand-rolled filter will fail with `Cannot index array with string "items"`. Run `jq -e .` first to inspect the actual shape, or use `jq '.environments | if type == "object" then .items else . end'` to handle both. + The shape of `environments` varies by `expand` parameter โ€” sometimes `{items: [...]}`, sometimes a bare array. Use `jq '.environments | if type == "object" then .items else . end'` to handle both. -2. **Test SDK integration:** - Run a quick verification to ensure the SDK key works: +2. **Test SDK connectivity:** ```python import ldclient from ldclient.config import Config ldclient.set_config(Config("{sdk_key}")) - # SDK initializes successfully - - # Always flush events before closing โ€” trailing events are at risk of being - # lost otherwise, in short-lived scripts and long-running services alike. ldclient.get().flush() ldclient.get().close() ``` -3. **Report results:** +3. **If verification fails:** + - SDK initialization error โ†’ check the SDK key matches the correct environment (Production vs Test) + - 401/403 from API โ†’ confirm the API token has `projects:write` permission + - Project missing environments โ†’ re-create or contact LaunchDarkly support + +4. **Report results:** - โœ“ Project exists and has environments - โœ“ SDK keys are present and valid - - โœ“ SDK can initialize (or flag any issues) - -## Project Key Best Practices - -Project keys must follow these rules: - -``` -โœ“ Good examples: - - "support-ai" - - "chat-bot-v2" - - "internal-tools" - -โœ— Bad examples: - - "Support_AI" # No uppercase or underscores - - "123-project" # Must start with letter - - "my.project" # No dots allowed -``` - -**Naming Recommendations:** -- Keep keys short but descriptive -- Use team/service/purpose as naming scheme -- Be consistent across your organization - -## Common Organization Patterns - -### By Team -``` -platform-ai โ†’ Platform Team AI -customer-ai โ†’ Customer Success Team AI -internal-ai โ†’ Internal Tools Team AI -``` - -### By Application/Service -``` -mobile-ai โ†’ Mobile App AI Configs -web-ai โ†’ Web App AI Configs -api-ai โ†’ API Service AI Configs -``` - -### By Region/Deployment -``` -ai-us โ†’ US Region -ai-eu โ†’ Europe Region -ai-apac โ†’ Asia-Pacific Region -``` + - โœ“ SDK can initialize ## Edge Cases | Situation | Action | |-----------|--------| -| Project already exists | Check if it's the right one; use it or create with different key | -| Need multiple projects | Create separately for each service/region/team | -| Shared configs across services | Use same project, separate by SDK context | +| Project already exists (409) | Use `get-project` to inspect; reuse or pick a different key | | Token lacks permissions | Request `projects:write` or use MCP server | -| Project name conflict | Keys must be unique, names can be similar | - -## What NOT to Do - -- Don't create projects without understanding the use case first -- Don't commit API tokens or SDK keys to version control -- Don't use production SDK keys in test/development environments -- Don't create duplicate projects unnecessarily -- Don't skip the exploration phase +| Multiple projects needed | Create separately for each service/region/team | +| Shared configs across services | Use same project, separate by SDK context | ## Next Steps -After setting up projects: - -1. **Create AI Configs** - Use the `aiconfig-create` skill -2. **Set up SDK Integration** - Use the `aiconfig-sdk` skill -3. **Configure Targeting** - Use the `aiconfig-targeting` skill - -## Related Skills - -- `aiconfig-create` - Create AI Configs in projects -- `aiconfig-sdk` - Integrate SDK in your application -- `aiconfig-targeting` - Configure AI Config targeting -- `aiconfig-variations` - Manage config variations +- **Create AI Configs** โ€” `aiconfig-create` +- **Set up SDK Integration** โ€” `aiconfig-sdk` +- **Configure Targeting** โ€” `aiconfig-targeting` +- **Manage Variations** โ€” `aiconfig-variations` ## References -- [Python Implementation](references/python-setup.md) -- [Node.js Implementation](references/nodejs-setup.md) -- [Go Implementation](references/go-setup.md) - [Quick Start Guide](references/quick-start.md) -- [Environment Configuration](references/env-config.md) -- [Project Cloning](references/project-cloning.md) -- [IaC/Automation](references/iac-automation.md) -- [Admin Tooling](references/admin-tooling.md) +- [Python](references/python-setup.md) ยท [Node.js](references/nodejs-setup.md) ยท [Go](references/go-setup.md) ยท [Multi-Language](references/multi-language-setup.md) +- [Environment Configuration](references/env-config.md) ยท [Project Cloning](references/project-cloning.md) +- [IaC/Automation](references/iac-automation.md) ยท [Admin Tooling](references/admin-tooling.md)