debug-generated-project — Claude Code skill: setup and triage
Troubleshoots Tuist project generation failures, build errors, and runtime crashes. It sets up isolated reproductions and verifies fixes against the main branch.
npx skills add tuist/agent-skills --skill debug-generated-project -a claude-codeWhat debug-generated-project does
The skill isolates Tuist project defects by asking for manifest files like Project.swift, the exact command run, and the failure stage. It builds a minimal isolated test case in a temporary directory, then executes tuist generate via mise against the newest public release.
When the problem persists, it checks out the Tuist source repository and builds both the CLI executable and ProjectDescription via swift build. After testing against main, it determines if the defect stems from project misconfigurations, such as wrong dependency types or bad glob paths, or an actual bug in the generator.
Full compile and runtime triage depends on local macOS tooling, requiring Xcode, xcodebuild, and an active iOS Simulator via simctl.
What it helps with
- diagnose manifest errors in Project.swift and Tuist.swift
- isolate generation bugs inside a clean temporary workspace
- test reproduction projects against the latest Tuist source code
- trace runtime app crashes on an iOS simulator via simctl
Example prompts for the agent
- Debug why tuist generate fails on my external package dependencies
- The project generated by Tuist fails to compile in Xcode, help triage the error
- My app crashes immediately on launch after running tuist generate
How to install debug-generated-project
1Skills CLI (Vercel)
npx skills add tuist/agent-skills --skill debug-generated-project -a claude-code2Manually: put the files in place
~/.claude/skills/debug-generated-project/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-generated-project/
1Skills CLI (Vercel)
npx skills add tuist/agent-skills --skill debug-generated-project -a codex2Manually: put the files in place
.agents/skills/debug-generated-project/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tuist/agent-skills --skill debug-generated-project -a cursor2Manually: put the files in place
.cursor/skills/debug-generated-project/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tuist/agent-skills debug-generated-project2Manually: put the files in place
.github/skills/debug-generated-project/SKILL.md1Skills CLI (Vercel)
npx skills add tuist/agent-skills --skill debug-generated-project -a gemini-cli2Platform CLI
gemini skills install https://github.com/tuist/agent-skills --path skills/debug-generated-projectManually: put the files in place
.devin/skills/debug-generated-project/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tuist/agent-skills --skill debug-generated-project -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about debug-generated-project
How to install debug-generated-project in Claude Code?
Run npx skills add tuist/agent-skills --skill debug-generated-project -a claude-code.
What does debug-generated-project do?
It guides an assistant through reproducing Tuist project errors in clean test folders, testing against release and main branches, and identifying misconfigurations or software defects.
What tools must be installed on the machine?
You need mise to run Tuist releases, Swift to compile Tuist from source, and Xcode with simctl for build and simulator launch verification.
