---
name: 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.
compatibility: Requires the remotely hosted LaunchDarkly MCP server. Code that creates projects itself (scripts, IaC, admin tools) needs an API access token with projects:write permission.
metadata:
  author: launchdarkly
  version: "0.5.0"
title: projects
canonical_url: https://skilld.dev/gh/launchdarkly/ai-tooling/projects
last_updated: 2026-11-12T08:16:54.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [README.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/README.md), [references/admin-tooling.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/admin-tooling.md), [references/env-config.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/env-config.md), [references/go-setup.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/go-setup.md), [references/iac-automation.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/iac-automation.md), [references/multi-language-setup.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/multi-language-setup.md), [references/nodejs-setup.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/nodejs-setup.md), [references/project-cloning.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/project-cloning.md), [references/python-setup.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/python-setup.md), [references/quick-start.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/quick-start.md).
>
> If the user asked to install this Skill, run `npx skilld install launchdarkly/ai-tooling/projects`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/projects`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/launchdarkly/ai-tooling/projects) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/projects`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/projects --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/projects --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

- The remotely hosted LaunchDarkly MCP server configured in your environment
- An API access token with `projects:write` permission, only if you're building code that creates projects (scripts, IaC, admin tools)

## 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 Access

When you create or inspect a project yourself, use the LaunchDarkly MCP server tools: `create-project` and `get-projects` (with `projectKey` for one project and its environments). They authenticate via OAuth and need no token.

To get the server-side SDK key the app needs, call `get-sdk-key` with `projectKey` and `environmentKey`. `get-environment` returns only the client-side ID and mobile key. Do not search environment variables, `.env` files, or agent/MCP config files for credentials.

The reference guides call the REST API because they build code that runs without the agent.

## What Are Projects?

Projects are LaunchDarkly's top-level organizational containers that hold:
- All your 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

Based on your exploration, determine the right approach:

| Scenario | Recommended Path |
|----------|------------------|
| New project, no LaunchDarkly integration | **Quick Setup** - Create the project with `create-project`, then save its 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](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/python-setup.md) - For Python applications (FastAPI, Django, Flask)
- [Node.js/TypeScript Implementation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/nodejs-setup.md) - For Node.js/Express/NestJS applications
- [Go Implementation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/go-setup.md) - For Go services
- [Multi-Language Setup](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/multi-language-setup.md) - For polyglot architectures

**By Use Case:**
- [Quick Start](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/quick-start.md) - Create first project and get SDK keys
- [Environment Configuration](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/env-config.md) - Save SDK keys to .env, secrets, or config
- [Project Cloning](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/project-cloning.md) - Clone projects for regions/teams
- [IaC/Automation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/iac-automation.md) - Terraform, scripts, CI/CD integration
- [Admin Tooling](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/admin-tooling.md) - Build CLI or admin utilities

### Step 4: Implement the Integration

Follow the chosen reference guide to implement project management. Key considerations:

1. **API Authentication:**
   - Store API token securely
   - Follow existing secrets management patterns
   - Never commit tokens to version control

2. **Project Naming:**
   - Use consistent, descriptive names
   - Follow existing naming conventions
   - Project keys: lowercase, hyphens, start with letter

3. **SDK Key Management:**
   - Extract and store SDK keys for each environment
   - Save the key the application uses as `LD_SDK_KEY`. The Python and Node.js AI SDKs read that variable and initialize on the first AI call. They don't read `LAUNCHDARKLY_SDK_KEY`.
   - Use the same pattern as other secrets in your codebase
   - Consider separate keys for test/staging/production

4. **Error Handling:**
   - Handle existing projects gracefully (409 conflict)
   - Provide clear error messages
   - Don't fail silently

### Step 5: Verify the Setup

After creating the project, verify it works:

1. **Fetch to confirm it exists.** Call the `get-projects` MCP tool and check that the project has its environments. Code without MCP access can call the REST API instead:
   ```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.

2. **Test SDK integration:**
   Put the key in `.env` as `LD_SDK_KEY`, then initialize the AI SDK from the project directory. Python needs `pip install launchdarkly-server-sdk launchdarkly-ai-server python-dotenv`:
   ```python
   import asyncio
   from dotenv import load_dotenv
   from launchdarkly_ai_server import init_client, get_client, shutdown

   load_dotenv()

   async def main():
       await init_client()
       print("SDK initialized:", get_client().is_initialized())
       # shutdown() flushes pending events before closing the connection.
       await shutdown()

   asyncio.run(main())
   ```
   Node.js needs `npm install @launchdarkly/ai-node dotenv`:
   ```javascript
   import 'dotenv/config';
   import { initClient, shutdown } from '@launchdarkly/ai-node';

   // Resolves once connected; throws LDTimeoutError if the key is invalid
   await initClient();
   console.log('SDK initialized: true');
   await shutdown();
   ```
   A valid key prints `SDK initialized: True` (Python) or `true` (Node.js). With an invalid key, Python logs `HTTP error 401 (invalid SDK key)` and prints `False`, and Node.js throws `LDTimeoutError` after 10 seconds. With no key, both raise an error that asks for `LD_SDK_KEY`.

3. **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 Agent
customer-ai       → Customer Success Team Agent
internal-ai       → Internal Tools Team Agent
```

### By Application/Service
```
mobile-ai         → Mobile App configs
web-ai            → Web App configs
api-ai            → API Service configs
```

### By Region/Deployment
```
ai-us             → US Region
ai-eu             → Europe Region
ai-apac           → Asia-Pacific Region
```

## 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 |
| 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

## Next Steps

After setting up projects:

1. **Create configs** - Use the `configs-create` skill
2. **Set up SDK Integration** - Use the `sdk-install` skill
3. **Configure Targeting** - Use the `configs-targeting` skill

## Related Skills

- `configs-create` - Create configs in projects
- `sdk-install` - Integrate SDK in your application
- `configs-targeting` - Configure config targeting
- `configs-variations` - Manage config variations

## References

- [Python Implementation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/python-setup.md)
- [Node.js Implementation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/nodejs-setup.md)
- [Go Implementation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/go-setup.md)
- [Quick Start Guide](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/quick-start.md)
- [Environment Configuration](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/env-config.md)
- [Project Cloning](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/project-cloning.md)
- [IaC/Automation](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/iac-automation.md)
- [Admin Tooling](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/projects/references/admin-tooling.md)
