feat(skills): add non-interactive auth/config guidance

skills/check-workspace-status/SKILL.md

@@ -5,41 +5,21 @@ description: Use when asking what targets/sources are configured, or wanting to
 
 # check-workspace-status
 
-Use `speakeasy status` to view workspace state.
-
 ## Command
 
 ```bash
-# Default visual output (requires TTY)
-speakeasy status
+# For LLMs/automation (recommended)
+speakeasy status --output json
 
-# Plain text for non-TTY environments (CI/CD, AI agents)
+# For human-readable output
 speakeasy status --output console
-
-# Structured JSON for automation and parsing
-speakeasy status --output json
 ```
 
-## Output Modes
+Requires `SPEAKEASY_API_KEY` env var (see `configure-authentication` skill).
 
-| Mode | Flag | Use Case |
-|------|------|----------|
-| summary | `--output summary` (default) | Interactive terminals with TTY |
-| console | `--output console` | CI/CD, AI agents, non-interactive |
-| json | `--output json` | Automation, scripting, programmatic access |
-
-## What It Shows
+## Output Includes
 
 - Workspace name and account type
-- Published targets (with version, URLs, last publish/generate info)
-- Configured targets (unpublished, with repository URLs)
-- Unconfigured targets
-- Any generation failures or upgrade recommendations
-
-## Use Cases
-
-- Verify setup before running generation
-- Debug workflow configuration issues
-- Check what targets are configured
-- Automate status checks in CI/CD pipelines
-- Parse workspace state programmatically with `--output json`
+- Published targets (version, URLs, last publish/generate)
+- Configured targets (unpublished, with repo URLs)
+- Unconfigured targets and generation failures

skills/configure-authentication/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: configure-authentication
+description: Use when setting up Speakeasy authentication, configuring API keys, or troubleshooting auth errors in non-interactive/CI environments
+---
+
+# configure-authentication
+
+## Quick Setup
+
+Set `SPEAKEASY_API_KEY` environment variable (takes precedence over config files):
+
+```bash
+export SPEAKEASY_API_KEY="<your-api-key>"
+```
+
+Get your API key: [Speakeasy Dashboard](https://app.speakeasy.com) → Settings → API Keys
+
+## Verifying Authentication
+
+```bash
+speakeasy status --output json
+```
+
+Returns workspace info if authenticated; `unauthorized` error if not.
+
+## Common Errors
+
+| Error | Solution |
+|-------|----------|
+| `unauthorized` | Set valid `SPEAKEASY_API_KEY` env var |
+| `workspace not found` | Check workspace ID in `~/.speakeasy/config.yaml` |
+
+## Alternative: Config File
+
+Create `~/.speakeasy/config.yaml`:
+
+```yaml
+speakeasy_api_key: "<your-api-key>"
+speakeasy_workspace_id: "<workspace-id>"  # optional
+# For multiple workspaces:
+workspace_api_keys:
+  org@workspace: "<api-key>"
+```

skills/get-ai-suggestions/SKILL.md

@@ -7,6 +7,14 @@ description: Use when SDK method names are ugly, wanting to improve operation ID
 
 Use `speakeasy suggest` for AI-powered improvements.
 
+## Prerequisites
+
+For non-interactive environments (CI/CD, AI agents), set:
+```bash
+export SPEAKEASY_API_KEY="<your-api-key>"
+```
+See `configure-authentication` skill for details.
+
 ## Commands
 
 ```bash

skills/improve-operation-ids/SKILL.md

@@ -5,6 +5,14 @@ description: Use when SDK methods have auto-generated names like GetApiV1Users,
 
 # improve-operation-ids
 
+## Prerequisites
+
+For non-interactive environments (CI/CD, AI agents), set:
+```bash
+export SPEAKEASY_API_KEY="<your-api-key>"
+```
+See `configure-authentication` skill for details.
+
 ## Check Current State
 
 ```bash

skills/regenerate-sdk/SKILL.md

@@ -7,6 +7,14 @@ description: Use when your spec changed and you need to regenerate the SDK, or r
 
 Use `speakeasy run` to execute the workflow and regenerate SDKs.
 
+## Prerequisites
+
+For non-interactive environments (CI/CD, AI agents), set:
+```bash
+export SPEAKEASY_API_KEY="<your-api-key>"
+```
+See `configure-authentication` skill for details.
+
 ## Command
 
 ```bash

skills/start-new-sdk-project/SKILL.md

@@ -7,6 +7,14 @@ description: Use when you have an OpenAPI spec and want to generate an SDK, or a
 
 Use `speakeasy quickstart` to initialize a new project with a workflow configuration.
 
+## Prerequisites
+
+For non-interactive environments (CI/CD, AI agents), set:
+```bash
+export SPEAKEASY_API_KEY="<your-api-key>"
+```
+See `configure-authentication` skill for details.
+
 ## Command
 
 ```bash