feat: add AI agent skills suite - #304
Merged
Merged
Conversation
Five skills teaching AI coding agents (Claude Code, Cursor, Codex) the poly CLI workflow, structured against google/agents-cli conventions: - poly-adk-workflow: entrypoint - setup, core loop, invariants, routing - poly-adk-testing: validate, scripted chat, test_suite, functions execute - poly-adk-branching: merge model, conflict resolution, review gists - poly-adk-conversations: real-call inspection, logging/metrics - poly-adk-rtc: RTC cycle, drift protection, live-push safety Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
8 tasks
jamesosullivan-polyai
approved these changes
Sep 9, 2026
Ruari-Phipps
added a commit
that referenced
this pull request
Sep 10, 2026
## Summary Adds `poly setup` — a single onboarding command covering authentication, shell completion, AI agent skill installation, and project setup — and removes `poly start`, which it supersedes. Second PR of the stack: stacked on #304 (the skills it installs), and the base for #303, which makes `poly update` keep them current. ## Motivation Onboarding currently spans several commands users must discover one by one (`poly login`, `poly completion`, `poly project create`), and the new agent skills had no installation path. `poly setup` runs all of it in one command, skipping any step that is already done, so it doubles as a repair command. `poly start` covered a subset of this (auth + project, hardcoded to the `studio` region) and is not referenced in published material, so it is removed rather than left as a second entry point. ## Changes - New `poly setup` command with `--region`, `--base-path`, `--skip-auth`, `--skip-skills`, `--agent` (repeatable), `--dev`, and `--global/-g` flags - New `cli_commands/skills.py`: wrapper around the pinned `npx skills` package with a Node.js 18+ gate; skill installation is non-fatal — a missing Node warns and setup continues - `poly login` (and setup) now wait up to 20s for a newly created API key to become active before returning - Region selection extracted to a shared picker; `poly start`'s four hardcoded `studio` call sites removed along the way - `poly start` removed from the CLI, docs, and nav - Docs: new `setup` reference page; getting-started restructured to "install, then `poly setup`"; tooling page now leads with skill installation via setup - `poly-adk-workflow` skill updated to mention `poly setup` for fresh machines - Root README quickstart updated from `poly start` to `poly setup` ## Test strategy - [x] Added/updated unit tests - [x] Manual CLI testing (`poly <command>`) - [ ] Tested against a live Agent Studio project - [ ] N/A (docs, config, or trivial change) 60 new tests (node gate, npx argument construction and non-raising failures, per-step skip logic, real rc-file completion installs in throwaway home directories — set via both HOME and USERPROFILE so they are hermetic on Windows — region threading, and activation-poll behavior). Manually verified end-to-end with an isolated `$HOME`: completion install + idempotent re-run, `--dev -g --agent claude-code` installing all five skills via npx, graceful skip without a TTY, and `poly start` now reporting an invalid choice. ## Checklist - [x] `ruff check .` and `ruff format --check .` pass - [x] `pytest` passes - [x] No breaking changes to the `poly` CLI interface (or migration path documented) — `poly start` is intentionally removed; `poly setup` / `poly login` are the migration path - [x] Commit messages follow [conventional commits](https://www.conventionalcommits.org/) ## Screenshots / Logs N/A
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
skills/directory with five agent skills that teach AI coding agents (Claude Code, Cursor, Codex, etc.) thepolyCLI workflow, plus a README describing the suite. Installable vianpx skills add.First PR of a three-part stack: #305 adds
poly setup, which installs these skills, and #303 makespoly updatekeep them current.Motivation
AI coding agents working on ADK projects currently have no contextual knowledge of the
polyworkflow — resource schemas, the no-mainrule, pushed-state testing semantics, or conflict resolution. These skills provide that context on demand, structured after Google'sagents-cliskills suite: a workflow entrypoint plus task-specific skills that load only when relevant.Changes
skills/poly-adk-workflow/SKILL.md— entrypoint: install/update, auth,poly docshabit, resource-choice guidance, project structure, the core edit → validate → push → test → merge loop, and a routing table to the task skillsskills/poly-adk-testing/SKILL.md—poly validate, scriptedpoly chat,test_suite/authoring withapi_mocks,poly functions execute/validateskills/poly-adk-branching/SKILL.md— branch semantics, three-way merge model, conflict markers, non-interactivemerge --resolutions, review gistsskills/poly-adk-conversations/SKILL.md—poly conversations, instrumenting withconv.logand metrics, real-call → test-case loopskills/poly-adk-rtc/SKILL.md— RTC pull/push cycle, drift protection, live-environment safetyskills/README.md— suite overview and install instructionsResource schemas are deliberately not duplicated — skills instruct agents to run
poly docs, which ships schemas with the installed CLI. Skillmetadata.versionis pinned to the current release (0.53.1).Test strategy
poly <command>)Markdown-only change. Skills were installed locally via
npx skills add(frontmatter validated by the tool) and exercised in Claude Code sessions against a real project. All CLI commands and flags referenced were cross-checked againstdocs/and, where relevant, the source.Checklist
ruff check .andruff format --check .passpytestpassespolyCLI interface (or migration path documented)Screenshots / Logs
N/A
🤖 Generated with Claude Code