From ab44542f81e2c95a7f8046a090ba3423e0025d81 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 10 Jul 2026 18:47:06 +0000 Subject: [PATCH] Add get-started skill to skyflow-skills plugin Adds a "Get Started with Skyflow" skill that acts as the front door for new Skyflow integrations and POCs. It orients the user and agent, then hands off to the right existing skill. The skill walks through: - Account & environment check (trial/sandbox/production -> base URLs) - Secure credential setup (token stays out of the chat and logs) - Goal selection (explore / plan / POC / production-ready / specific task) - Working mode (educational-collaborative vs get-it-done) - Routing to the appropriate skill, API, SDK, and docs Supporting references: - environments.md: account-type/base-URL matrix, finding IDs, per-env cautions - credentials.md: token types, secure local provisioning, what never to do Also updates the marketplace README, plugin README, plugin/marketplace descriptions (version bumped to 0.6.0), and the CONTRIBUTING structure list. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01VL1KCtJyvnXQkbwKqc3gEh --- .claude-plugin/marketplace.json | 2 +- CONTRIBUTING.md | 2 + README.md | 4 +- .../.claude-plugin/plugin.json | 4 +- skyflow-skills-plugin/README.md | 7 + .../skills/get-started/SKILL.md | 145 ++++++++++++++++++ .../skills/get-started/credentials.md | 88 +++++++++++ .../skills/get-started/environments.md | 78 ++++++++++ 8 files changed, 325 insertions(+), 5 deletions(-) create mode 100644 skyflow-skills-plugin/skills/get-started/SKILL.md create mode 100644 skyflow-skills-plugin/skills/get-started/credentials.md create mode 100644 skyflow-skills-plugin/skills/get-started/environments.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4e05487..3bc2c8b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ { "name": "skyflow-skills", "source": "./skyflow-skills-plugin", - "description": "Skyflow skills for Claude Code: vault creation, REST API guidance, SDK migration, implementation planning, and SDK quickstarts." + "description": "Skyflow skills for Claude Code: getting started, vault creation, REST API guidance, SDK migration, implementation planning, and SDK quickstarts." }, { "name": "skyflow-developer-mcp", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc4dc56..fbf211d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,8 @@ This repository is organized as a Claude Code plugin marketplace: │ │ └── SKILL.md │ ├── create-vault/ │ │ └── SKILL.md +│ ├── get-started/ +│ │ └── SKILL.md │ ├── migrate-sdk-v1-to-v2/ │ │ └── SKILL.md │ ├── plan-skyflow-implementation/ diff --git a/README.md b/README.md index fbac52e..4227215 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ A Claude Code plugin marketplace that enables Skyflow's data privacy and protect | Plugin | What it does | Environment variables | Docs | | ------ | ------------ | --------------------- | ---- | -| `skyflow-skills` | Guided Skyflow workflows (vault creation, REST API guidance, SDK migration, implementation planning, SDK quickstarts) | None | [README](skyflow-skills-plugin/README.md) | +| `skyflow-skills` | Guided Skyflow workflows (getting started, vault creation, REST API guidance, SDK migration, implementation planning, SDK quickstarts) | None | [README](skyflow-skills-plugin/README.md) | | `skyflow-developer-mcp` | Developer MCP server — access to Skyflow documentation, skills, and integration resources | `SKYFLOW_BEARER_TOKEN`, `SKYFLOW_ACCOUNT_ID` | [README](skyflow-developer-mcp-plugin/README.md) | | `skyflow-runtime-mcp` | Runtime MCP server (optional) — on-demand de-identification of PII in text via the Detect APIs | `SKYFLOW_BEARER_TOKEN`, `SKYFLOW_ACCOUNT_ID`, `SKYFLOW_VAULT_ID`, `SKYFLOW_VAULT_URL` | [README](skyflow-runtime-mcp-plugin/README.md) | @@ -79,7 +79,7 @@ curl -L -O https://github.com/SkyflowFoundry/claude/releases/latest/download/cre unzip create-vault.zip -d ~/.claude/skills/ ``` -Available skills: `call-rest-apis`, `create-vault`, `migrate-sdk-v1-to-v2`, `plan-skyflow-implementation`, `quickstart-js-browser`, `quickstart-node`. A `SHA256SUMS.txt` is attached to each release so you can verify downloads. +Available skills: `call-rest-apis`, `create-vault`, `get-started`, `migrate-sdk-v1-to-v2`, `plan-skyflow-implementation`, `quickstart-js-browser`, `quickstart-node`. A `SHA256SUMS.txt` is attached to each release so you can verify downloads. > These zips are build artifacts generated from the same skills in this repo — the plugin and the standalone downloads are always in sync. diff --git a/skyflow-skills-plugin/.claude-plugin/plugin.json b/skyflow-skills-plugin/.claude-plugin/plugin.json index 1a91195..30d95c7 100644 --- a/skyflow-skills-plugin/.claude-plugin/plugin.json +++ b/skyflow-skills-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "skyflow-skills", - "description": "Skyflow skills for Claude Code: vault creation, REST API guidance, SDK migration, implementation planning, and SDK quickstarts.", - "version": "0.5.0", + "description": "Skyflow skills for Claude Code: getting started, vault creation, REST API guidance, SDK migration, implementation planning, and SDK quickstarts.", + "version": "0.6.0", "author": { "name": "Joseph McCarron", "email": "joe@skyflow.com", diff --git a/skyflow-skills-plugin/README.md b/skyflow-skills-plugin/README.md index d304ebe..8f48d12 100644 --- a/skyflow-skills-plugin/README.md +++ b/skyflow-skills-plugin/README.md @@ -28,6 +28,7 @@ Each skill is available as a slash command in the form `/skyflow-skills:. A trial is the fastest way to start. Come back here once they're signed in. +- **Has an account** → find out which *type*, because it drives every base URL and vault URL you'll use. Easiest tell: look at the browser URL while signed in to Studio. + +| Account type | Studio URL looks like | Management (API) base URL | Vault URL pattern | +| --- | --- | --- | --- | +| **Trial** | `try.skyflow.com/...` | `https://manage.skyflowapis.com` | `https://.vault.skyflowapis.com` | +| **Sandbox** | `.skyflow-preview.com` | `https://manage.skyflowapis-preview.com` | `https://.vault.skyflowapis-preview.com` | +| **Production** | `.skyflow.com` | `https://manage.skyflowapis.com` | `https://.vault.skyflowapis.com` | + +**The `-preview` suffix is the sandbox tell.** Trial and production both run on `skyflowapis.com`. + +> **Golden rule:** don't guess the URLs. Copy the exact **Management URL** and **Vault URL** from Studio → *vault menu icon → View vault details*. That view also has your **Account ID**, **Workspace ID**, and **Vault ID**. The table above is the usual mapping; Studio is the source of truth. + +Record for the session: account type, Management base URL, Vault URL, Account ID, Vault ID. + +Full detail, per-environment cautions, and how to find each ID → [environments.md](environments.md). + +--- + +## Step 2 — Credentials (handle with care) + +The quickest credential to start with is a **personal access / API bearer token** from Studio: **top-right profile (account) menu → Generate API Bearer Token**. + +**Never ask the user to paste the token into the chat.** Tokens are secrets — in a shared or logged session, and especially in sandbox/production, a pasted token is a leaked token. Instead, have them place it in the environment and read it from there: + +```bash +# Add to your shell profile (e.g. ~/.zshrc), then restart the terminal. +# These names match the Skyflow MCP plugins, so setting them once wires those up too. +export SKYFLOW_BEARER_TOKEN="your-token-here" +export SKYFLOW_ACCOUNT_ID="your-account-id-here" +``` + +Confirm it's set **without printing it**: + +```bash +[ -n "$SKYFLOW_BEARER_TOKEN" ] && echo "token is set" || echo "token is NOT set" +``` + +For a project, a **gitignored `.env`** works too — just make sure `.env` is in `.gitignore` before writing anything to it. + +Match the credential to the environment: + +| Environment | Recommended credential | +| --- | --- | +| Trial / POC | Personal access token (fastest to get going) | +| Sandbox | Personal access token is fine; start moving to a service account | +| Production | Service account or **API key** with least privilege; generate short-lived bearer tokens server-side; use a secrets manager | + +**Non-negotiables:** never paste tokens into chat, commit them, or echo them into logs; never send real customer PII to a trial/sandbox; the higher the environment, the more caution. + +Token types, secure provisioning options, and MCP wiring → [credentials.md](credentials.md). + +--- + +## Step 3 — What do you want to do? + +Propose these options and let the user pick (they can combine): + +- **A. Explore what's possible** — learn the concepts, kick the tires, see a working example. +- **B. Plan a full implementation** — design the vault, data model, and integration before building. +- **C. Build a POC / prototype** — get something working fast, correctness over polish. +- **D. Build a production-ready integration** — do it properly: security, access controls, real credentials. +- **E. A specific task** — e.g. create a vault, collect data in the browser, tokenize records, de-identify text/LLM data, or migrate an existing SDK. + +--- + +## Step 4 — Pick a working mode + +Offer both, and adapt for the rest of the session: + +- 🎓 **Educational / collaborative** — explain the *why*, go step by step, surface options and trade-offs, confirm understanding before moving on. Best for first-timers and anyone learning Skyflow. +- ⚡ **Get-it-done** — minimize back-and-forth, choose sensible defaults, execute end-to-end, then report what you did. Best when the user knows Skyflow or just wants the result. + +Get-it-done still **pauses before anything irreversible or production-facing** (writing real data, changing production config, rotating credentials). + +--- + +## Step 5 — Hand off to the right skill + +Match the goal to the skill and load it. All skills below ship in this same `skyflow-skills` plugin. + +| You want to… | Start here (skill) | Also useful | +| --- | --- | --- | +| Plan a full implementation / architecture | **plan-skyflow-implementation** | create-vault, call-rest-apis | +| Create or design a vault (schema, tokenization, redaction) | **create-vault** | call-rest-apis | +| Call the Skyflow REST APIs directly (curl/HTTP) | **call-rest-apis** | skyflow-developer-mcp | +| Integrate a Node.js / backend service | **quickstart-node** | call-rest-apis, migrate-sdk-v1-to-v2 | +| Collect sensitive data in the browser (Elements) | **quickstart-js-browser** | create-vault | +| De-identify PII in text or protect LLM prompts (Detect) | **call-rest-apis** (Detect) | skyflow-runtime-mcp | +| Upgrade an existing V1 SDK integration | **migrate-sdk-v1-to-v2** | — | +| Look things up live (docs, resources, skills) | **skyflow-developer-mcp** (MCP plugin) | — | + +**Typical first-timer path:** explore → `plan-skyflow-implementation` → `create-vault` → a quickstart (`quickstart-node` or `quickstart-js-browser`) → `call-rest-apis` as you build. + +### Companion MCP plugins (optional) + +The skills work standalone. For live access, pair with: + +- **skyflow-developer-mcp** — Skyflow docs, skills, and integration resources on demand. Most users want this. Reads `SKYFLOW_BEARER_TOKEN` and `SKYFLOW_ACCOUNT_ID` (the same vars from Step 2). +- **skyflow-runtime-mcp** — on-demand de-identification of PII in text via the Detect APIs. Add only if you need it. + +Install: `/plugin marketplace add SkyflowFoundry/claude` then `/plugin install skyflow-developer-mcp@skyflow-marketplace`. + +--- + +## Guardrails (apply throughout) + +- **Secrets stay out of the transcript.** Never request, print, or commit a token; read it from the environment. +- **Right environment, right data.** Trial and sandbox are for test data only — never real customer PII. +- **Escalate caution with the environment.** Production actions get confirmed first, always. +- **Confirm URLs from Studio**, don't hardcode from memory. +- **When unsure which skill fits, ask** — this skill is a router, not the destination. + +## Related documentation + +- [environments.md](environments.md) — account types, base URLs, finding your IDs, per-environment guidance +- [credentials.md](credentials.md) — token types, secure local setup, what never to do +- Skyflow docs: · API authentication: diff --git a/skyflow-skills-plugin/skills/get-started/credentials.md b/skyflow-skills-plugin/skills/get-started/credentials.md new file mode 100644 index 0000000..2ca7575 --- /dev/null +++ b/skyflow-skills-plugin/skills/get-started/credentials.md @@ -0,0 +1,88 @@ +# Skyflow Credentials — Secure Setup + +Every Skyflow API call needs a bearer token in an `Authorization: Bearer ` header. This guide covers the token types, how to get one, and — most importantly — how to handle it without leaking it. + +## The one rule that matters most + +**A token is a secret. It never belongs in the chat, a commit, or a log.** + +- Do **not** ask the user to paste their token into the conversation. +- Do **not** print it, echo it, or write it into a file that gets committed. +- Read it from the **environment** (or a gitignored `.env`) instead. +- The higher the environment (trial → sandbox → production), the more this matters. A leaked production token can expose real customer data. + +If a token ever does end up in the transcript or a shared log, treat it as compromised: **rotate/revoke it in Studio immediately.** + +## Token types + +| Type | Where it comes from | Lifetime | Best for | +| --- | --- | --- | --- | +| **Personal access / API bearer token** | Studio → top-right profile (account) menu → *Generate API Bearer Token* | Short-lived (typically ~60 min) | Getting started, trials, POCs. Tied to your user. | +| **API key** | Studio (service account settings) | Long-lived, revocable | Long-lived programmatic/backend access with least privilege | +| **Service account + generated bearer token** | Download a credentials JSON; sign a JWT assertion and exchange it for a bearer token server-side | Bearer token short-lived; you regenerate as needed | Production. Credentials never leave your backend. | + +For getting started, the **personal access token** is the fastest path. For anything production-facing, move to a **service account** or a least-privilege **API key**. See the `call-rest-apis` skill for how to exchange a service account JWT assertion for a bearer token, and the `plan-skyflow-implementation` skill for the auth decision tree. + +## Get a personal access token + +1. Sign in to Skyflow Studio (the right environment — see [environments.md](environments.md)). +2. Click the **profile / account icon in the top-right**. +3. Choose **Generate API Bearer Token**. +4. Copy the token — you'll place it in your environment below, not into the chat. + +Because these tokens expire (~60 min), you'll regenerate periodically during development. For anything longer-lived, use an API key or a service account. + +## Provide the token securely (pick one) + +### Option 1 — Shell environment variable (recommended for local dev) + +Add to your shell profile (e.g. `~/.zshrc` on macOS), then **restart the terminal**. These names match the Skyflow MCP plugins, so setting them here also wires those up: + +```bash +echo 'export SKYFLOW_BEARER_TOKEN="your-token-here"' >> ~/.zshrc +echo 'export SKYFLOW_ACCOUNT_ID="your-account-id-here"' >> ~/.zshrc +``` + +Verify **without printing the secret**: + +```bash +[ -n "$SKYFLOW_BEARER_TOKEN" ] && echo "SKYFLOW_BEARER_TOKEN is set" || echo "SKYFLOW_BEARER_TOKEN is NOT set" +``` + +### Option 2 — Gitignored `.env` file (project-local) + +1. Confirm `.env` is in `.gitignore` **before** creating it: + ```bash + grep -qxF '.env' .gitignore || echo '.env' >> .gitignore + ``` +2. Put the token in `.env`: + ```bash + SKYFLOW_BEARER_TOKEN=your-token-here + SKYFLOW_ACCOUNT_ID=your-account-id-here + ``` +3. Load it with your framework's env loader (`dotenv`, Vite's `import.meta.env`, etc.). Never hardcode the token in source. + +### Option 3 — Secrets manager (production) + +Store credentials in a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault, etc.) and inject them at runtime. Use a **service account** to generate short-lived bearer tokens on the backend — the raw credentials never reach a frontend or a developer's laptop. + +## Using the token in requests + +```bash +curl -s "$VAULT_URL/v1/vaults/$VAULT_ID/persons" \ + -H "Authorization: Bearer $SKYFLOW_BEARER_TOKEN" +``` + +The agent should reference `$SKYFLOW_BEARER_TOKEN` in commands rather than the literal value, so the secret stays out of the command it prints. + +## Frontend note + +Browser/mobile SDKs must **never** hold a service account or long-lived key. They call your backend for a **short-lived bearer token** via a `getBearerToken()` function. See the `quickstart-js-browser` skill's "Production Hardening" section for the token-endpoint pattern. + +## Checklist + +- [ ] Token stored in an env var, gitignored `.env`, or secrets manager — never in the chat +- [ ] `.env` is in `.gitignore` (if using a file) +- [ ] Token matches the target environment (trial/sandbox/production) +- [ ] Production uses a service account or least-privilege API key, not a personal token +- [ ] No token, credential, or real PII appears in logs, commits, or the transcript diff --git a/skyflow-skills-plugin/skills/get-started/environments.md b/skyflow-skills-plugin/skills/get-started/environments.md new file mode 100644 index 0000000..617112e --- /dev/null +++ b/skyflow-skills-plugin/skills/get-started/environments.md @@ -0,0 +1,78 @@ +# Skyflow Environments & Base URLs + +Your Skyflow account type decides which base URLs you talk to and how careful you should be. Get this right first — pointing an integration at the wrong environment is one of the most common early mistakes. + +## Identify your account type + +Sign in to Studio and look at the URL in your browser: + +| Browser URL | Account type | +| --- | --- | +| `try.skyflow.com/...` | **Trial** | +| `.skyflow-preview.com` | **Sandbox** | +| `.skyflow.com` (not `try`, not `-preview`) | **Production** | + +If you're not sure, the **`-preview` suffix means sandbox**. Trial and production both live on `skyflow.com` / `skyflowapis.com`. + +## Base URL matrix + +| Account type | Management (API) base URL | Vault URL pattern | Docs | +| --- | --- | --- | --- | +| **Trial** | `https://manage.skyflowapis.com` | `https://.vault.skyflowapis.com` | `docs.skyflow.com` | +| **Sandbox** | `https://manage.skyflowapis-preview.com` | `https://.vault.skyflowapis-preview.com` | `docs.skyflow-preview.com` | +| **Production** | `https://manage.skyflowapis.com` | `https://.vault.skyflowapis.com` | `docs.skyflow.com` | + +- **Management API** (create vaults, manage schemas/policies, auth) uses the `manage.*` host. +- **Data & Detect APIs** (insert, tokenize, detokenize, de-identify) use your **vault URL** — the per-vault `.vault.*` host. +- `` is the subdomain of your vault URL (e.g. for `https://ebfc9bee4242.vault.skyflowapis.com`, the cluster ID is `ebfc9bee4242`). + +> **Always confirm the exact URLs from Studio.** This table is the usual mapping, but Studio is the source of truth — copy the real values rather than reconstructing them from memory. + +## Find your IDs and URLs in Studio + +In Studio, open a vault and click the **vault menu icon → View vault details**. That panel gives you: + +- **Vault URL** — the base for Data and Detect API calls +- **Vault ID** — identifies the vault in API paths +- **Account ID** — sent as the `X-SKYFLOW-ACCOUNT-ID` header on many Management calls +- **Workspace ID** — needed when creating vaults + +Suggested environment variables for local work (these names line up with the Skyflow MCP plugins): + +```bash +export MANAGEMENT_URL=https://manage.skyflowapis.com # or ...-preview.com for sandbox +export SKYFLOW_ACCOUNT_ID= +export WORKSPACE_ID= +export VAULT_ID= +export VAULT_URL= +export SKYFLOW_BEARER_TOKEN= # see credentials.md +``` + +## Per-environment guidance + +### Trial +- **Purpose:** learning, demos, quick POCs. Time-limited. +- **Data:** synthetic/test data only — never real customer PII. +- **Credentials:** a personal access token in a local `.env` or env var is fine. +- **Mindset:** move fast, treat everything as disposable. + +### Sandbox (`-preview`) +- **Purpose:** pre-production development and staging against a stable environment. +- **Data:** test data only. Still no real PII. +- **Credentials:** personal access token works; begin moving to a **service account** as the integration matures. +- **Mindset:** build it the way you'll ship it, but it's still safe to break. + +### Production +- **Purpose:** real users, real sensitive data. +- **Data:** real PII/PHI/PCI — handle accordingly. Never log raw values. +- **Credentials:** **service account or least-privilege API key**, short-lived bearer tokens generated server-side, secrets stored in a secrets manager. No personal tokens. +- **Mindset:** highest caution. Confirm before any write, config change, or credential rotation. Get a security review before launch (see the `plan-skyflow-implementation` skill). + +## Common mistakes + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| `401 Unauthorized` on every call | Token from a different environment, or expired | Regenerate a token for the environment you're targeting | +| Calls hit the wrong data / vault | Mixed `skyflowapis.com` and `skyflowapis-preview.com` hosts | Use one environment's hosts consistently; copy URLs from Studio | +| `404` on Management calls | Wrong `manage.*` host for your account type | Sandbox uses `manage.skyflowapis-preview.com`; trial/prod use `manage.skyflowapis.com` | +| Vault operations fail | Using the Management host for Data/Detect calls | Data & Detect use the **vault URL**, not `manage.*` |