Agent-Driven TeamCity Debugging: The teamcity-cli Skill

Where this fits

A developer pastes a failed TeamCity build URL into their chat window, expecting the agent to diagnose why the pipeline broke. Without a dedicated skill, the agent fumbles through vague API docs or asks for manual screenshots. The teamcity-cli skill bridges that gap by giving the agent a direct, authenticated command interface to TeamCity—so it can pull logs, inspect build chains, and identify root causes without human hand-holding.

Why agents benefit

• Pinpoint failure root causes: Agents can run teamcity run tree <id> to trace a composite build failure to the deepest failed dependency, ignoring noisy parent states.
• Read actual logs, not summaries: Using teamcity run log <id> --failed --raw lets agents dump full failure diagnostics to a temp file and grep for exceptions, stack traces, or custom error patterns.
• Navigate the CI/CD state machine: The skill enforces the correct vocabulary—runs for builds, jobs for configurations—so agents never confuse teamcity run with teamcity job when querying queues, agents, or projects.
• Handle composite-build gotchas: Agents know that composite builds have empty logs and drill into child builds automatically, avoiding false "no output" conclusions.
• Auth-aware execution: The skill handles TEAMCITY_URL and TEAMCITY_TOKEN correctly, preventing the all-too-common authentication bypass that occurs when only the URL is set.

Practical scenarios

Debugging a flaky integration test from a shared URL

Your agent receives a TeamCity URL pointing to a failed run. It authenticates, pulls the raw log, and spots a timeout in a child build. It then cross-references the build chain to confirm the flaky test is the only failure and suggests a re-run with increased timeout—all in one turn.

Monitoring a deployment pipeline across multiple agents

The agent polls teamcity run list --status failure periodically, filters by project, and alerts you only when a deploy job fails—not when a dependent unit test flakes. It uses --limit (not --count) to keep output bounded.

Root-causing a Kotlin DSL misconfiguration

The agent notices a build failed right after a configuration change. It checks whether .teamcity/ was pushed before the run; because --local-changes excludes DSL changes, it advises you to push and re-run, saving a 20-minute debugging loop.

Add it to your agent workflow

Install the skill with one command:

npx skills add JetBrains/teamcity-cli --skill teamcity-cli

Then, in your agent's system prompt, describe when to invoke it:

When the user shares a TeamCity URL or asks about CI/CD status, use the teamcity-cli skill. Always check auth, use `teamcity run` for builds and `teamcity job` for configurations, and never guess flags—refer to the command reference.

For a practical example, your agent can run:

teamcity auth status
teamcity run log <id> --failed --raw | tail -n 100

To see how this skill fits into the broader agent ecosystem, visit https://www.openagentskill.com/skills/jetbrains-teamcity-cli — it's one of many curated, quality-screened skills on that platform.

Compare before adopting

Before you make this a permanent part of your toolkit, weigh it against alternatives. Check the GitHub repo's recent activity—TeamCity CLI updates track JetBrains' own API changes, so freshness matters. Review the skill's test coverage and documentation clarity (the README's gotchas section is a good sign). Also, consider whether your team uses TeamCity enough to justify a dedicated skill vs. generic HTTP calls—and whether the agent's runtime inherits the CLI's auth model cleanly.

Why it is worth tracking

With 121 stars and maintenance by JetBrains, this skill is credible but not wildly popular—so it's a niche gem. Its quality signals are strong: explicit gotchas, versioned releases, and a clear command reference. Track it closely if you're already on TeamCity; if you migrate to another CI, evaluate the alternatives at that point. The skill's thoughtful design (e.g., distinguishing runs from jobs, safe auth handling) sets a high bar for other CI/CD integrations, so even non-TeamCity users can learn from its pattern.