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.*` |