feat(quickstart): offer agent skill install before SDK generation

[simplesagar]

Summary

• After speakeasy quickstart configures the project but before running SDK generation, prompts the user to install the speakeasy-context agent skill for AI coding assistants
• Reuses the existing speakeasy agent setup-skills --auto command (runSetupSkills) — no duplicated logic
• Skips the prompt if skills are already installed or running in non-interactive mode

Resolves GEN-2504

How to verify locally

1. Build and run quickstart (interactive, accept skill install)

go build -o speakeasy . && ./speakeasy quickstart

After project setup (schema, target, output dir) but before generation starts, you should see:

Install Speakeasy agent skills for AI coding assistants (Claude Code, Cursor, etc.)? (Y/n)

Press Enter (default yes) → verify .agents/skills/speakeasy-context/SKILL.md and agent-specific symlinks are created in the output directory, then generation proceeds normally.

2. Decline skill install

Run quickstart again in a fresh directory, select "no" at the prompt → verify no .agents/ directory is created and generation proceeds normally.

3. Already-installed (idempotent)

Run quickstart in a directory that already has .agents/skills/speakeasy-context/ → the prompt should be skipped entirely.

4. Non-interactive mode

go build -o speakeasy . && ./speakeasy quickstart --skip-compile --target typescript --schema https://petstore3.swagger.io/api/v3/openapi.json --out-dir /tmp/test-sdk --name TestSDK --package-name test-sdk

No skill install prompt should appear.

Test plan

• Interactive quickstart → accept → skill files and symlinks created before generation runs
• Interactive quickstart → decline → no files created, generation proceeds
• Re-run in same dir → prompt skipped (already installed)
• Non-interactive mode → no prompt appears
• go build ./... passes

🤖 Generated with Claude Code

[linear]

GEN-2504 feat: Quickstart offers auto tool install in git repo

[simplesagar]

Superseded — rebasing onto main in a clean branch to remove already-merged commits from the diff.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 8 additional findings in Devin Review.

[devin-ai-integration]

🔴 Branch reference inconsistency between fetchSkillNames (default branch) and fetchSkillContent (hardcoded master)

The two GitHub-fetching functions use inconsistent branch references, which will cause fetchSkillContent to fail with a 404 if the speakeasy-api/skills repo's default branch is not master.

Root Cause

fetchSkillNames at cmd/agent_setup_skills.go:117 uses the GitHub Contents API without specifying a branch, so it defaults to the repo's default branch (e.g. main):

url := fmt.Sprintf("https://api.github.com/repos/%s/%s/contents/%s", skillsOwner, skillsRepo, skillsPath)

fetchSkillContent at cmd/agent_setup_skills.go:150 hardcodes master in the raw URL:

url := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/master/%s/%s/SKILL.md", ...)

If the default branch is main (GitHub's default for new repos since 2020), fetchSkillNames successfully lists skills from main, but fetchSkillContent tries to fetch from master and returns a 404. This causes installSkillsNative to fail.

In the quickstart flow (cmd/quickstart.go:697), the error is caught as a warning, so the user sees "Failed to install agent skills" but quickstart continues. In the standalone speakeasy agent setup-skills --auto path, the error propagates up and the command fails entirely.

Prompt for agents

In cmd/agent_setup_skills.go, the fetchSkillContent function on line 150 hardcodes the branch name 'master' in the raw.githubusercontent.com URL. This is inconsistent with fetchSkillNames on line 117 which uses the GitHub Contents API and defaults to the repo's default branch. To fix this, either: (1) Add a constant for the branch name and use the GitHub Contents API's download_url field in fetchSkillContent instead of constructing the raw URL manually, or (2) Replace 'master' with 'main' if that is the actual default branch of the speakeasy-api/skills repo, or (3) Use the GitHub Contents API for both functions so neither hardcodes a branch name.

---

Was this helpful? React with 👍 or 👎 to provide feedback.