feat(devex): add SDK agent skills and editor guidance

.agents/skills/frontal-sdk

@@ -0,0 +1 @@
+../../skills/frontal-sdk

.agents/skills/python-lint

@@ -0,0 +1 @@
+../../skills/python-lint

.agents/skills/python-packaging

@@ -0,0 +1 @@
+../../skills/python-packaging

.agents/skills/python-pydantic-httpx-contracts

@@ -0,0 +1 @@
+../../skills/python-pydantic-httpx-contracts

.agents/skills/python-supply-chain

@@ -0,0 +1 @@
+../../skills/python-supply-chain

.agents/skills/python-sync-async-clients

@@ -0,0 +1 @@
+../../skills/python-sync-async-clients

.agents/skills/python-testing

@@ -0,0 +1 @@
+../../skills/python-testing

.agents/skills/python-typing

@@ -0,0 +1 @@
+../../skills/python-typing

.claude/rules/sdk-language.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python changes
+
+Support Python 3.9–3.12. Keep the import package frontal_sdk separate from the PyPI distribution name frontal. Use HTTPX, Pydantic v2, uv/Hatchling, Ruff, mypy, pytest, anyio, and offline RESPX tests. Treat contracts as endpoint authority.
+
+Follow the repository's `AGENTS.md` and `CLAUDE.md`. Use the relevant installed language skill under `.claude/skills/`. Add deterministic, offline tests for behavior changes, and run the repository's relevant format, lint, type/build, and contract checks.

.claude/settings.json

@@ -1,5 +1,12 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "permissions": {
-    "allow": []
+    "allow": [],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(**/.env)",
+      "Read(**/.env.*)"
+    ]
   }
 }

.claude/skills/frontal-sdk

@@ -0,0 +1 @@
+../../skills/frontal-sdk

.claude/skills/python-lint

@@ -0,0 +1 @@
+../../skills/python-lint

.claude/skills/python-packaging

@@ -0,0 +1 @@
+../../skills/python-packaging

.claude/skills/python-pydantic-httpx-contracts

@@ -0,0 +1 @@
+../../skills/python-pydantic-httpx-contracts

.claude/skills/python-supply-chain

@@ -0,0 +1 @@
+../../skills/python-supply-chain

.claude/skills/python-sync-async-clients

@@ -0,0 +1 @@
+../../skills/python-sync-async-clients

.claude/skills/python-testing

@@ -0,0 +1 @@
+../../skills/python-testing

.claude/skills/python-typing

@@ -0,0 +1 @@
+../../skills/python-typing

.cursor/README.md

@@ -0,0 +1,5 @@
+# Cursor project configuration
+
+This directory uses Cursor Project Rules in `.cursor/rules/*.mdc` and project commands in `.cursor/commands/*.md`. The shared rule applies to every task; the language rule is auto-attached to `**/*.py` files. The commands provide reusable review and verification workflows. root `.cursorignore` excludes generated output, dependency caches, and local secrets from Cursor context.
+
+Cursor Agent also reads root `AGENTS.md` and `CLAUDE.md`; Claude Code reads `CLAUDE.md`, which imports `AGENTS.md`. Project instruction sources are therefore shared without relying on the obsolete `.cursor.json` format.

.cursor/cli.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(.env*)",
+      "Read(**/.env*)",
+      "Write(.env*)",
+      "Write(**/.env*)"
+    ]
+  }
+}

.cursor/commands/review-sdk-contract.md

@@ -0,0 +1 @@
+Review the current diff for SDK contract correctness. Compare any changed endpoint paths, methods, request/response fields, and error behavior with `contracts/sdk-endpoints.json` and the corresponding committed OpenAPI snapshot. Flag unsupported API surface, accidental breaking changes, credential exposure, and missing offline coverage. Do not modify files. Report findings with file and line references; if none, say so.

.cursor/commands/verify-sdk-change.md

@@ -0,0 +1,10 @@
+Review the current diff and identify affected modules, public behavior, and relevant contract entries. Run only checks relevant to the changes, choosing from the repository commands below. Do not edit code unless I explicitly ask you to fix a failure. Report checks run and their results.
+
+```sh
+uv run ruff format --check .
+uv build
+uv run ruff check .
+uv run mypy --strict
+uv run python -m pytest
+uv run python scripts/check_contracts.py
+```

.cursor/rules/00-project.mdc

@@ -0,0 +1,13 @@
+---
+description: Shared Frontal SDK repository constraints
+alwaysApply: true
+---
+
+# Project guidance
+
+- Read `AGENTS.md` for repository layout, conventions, and canonical commands. `CLAUDE.md` imports it for Claude Code compatibility.
+- Treat `contracts/sdk-endpoints.json` and committed OpenAPI snapshots as authoritative for endpoint paths and wire shapes. Do not invent public operations or fields.
+- Preserve established public API and compatibility unless the requested change explicitly requires otherwise.
+- Keep credentials, tokens, and customer data out of code, logs, fixtures, and examples.
+- Follow relevant repository skills in `skills/` when changing SDK behavior.
+- Inspect the existing diff before editing. Run only the checks relevant to the change and report exactly what was run.

.cursor/rules/10-sdk-language.mdc

@@ -0,0 +1,11 @@
+---
+description: Python SDK code conventions and checks
+globs: **/*.py
+alwaysApply: false
+---
+
+# Python development rules
+
+Support Python 3.9–3.12. Keep the frontal_sdk import package distinct from the frontal distribution. Follow existing uv/Hatchling, HTTPX, Pydantic v2, Ruff, mypy, pytest, anyio, and RESPX patterns. Keep service behavior grounded in the committed contracts.
+
+When implementing behavior changes, add deterministic offline coverage using the repository's existing test tools. Update docs and runnable examples for public API changes. See `AGENTS.md` for project-specific rules and use the applicable skill under `skills/`.

.cursorignore

@@ -1,3 +1,4 @@
+# Cursor context exclusions
 .git/
 .venv/
 __pycache__/
@@ -7,3 +8,14 @@ __pycache__/
 .pyright/
 /build/
 /dist/
+
+# Local secrets and generated caches
+.env
+.env.*
+!.env.example
+!.env.*.example
+.gradle/
+.venv/
+venv/
+__pycache__/
+*.egg-info/

.gitignore

@@ -5,7 +5,6 @@
 
 # Operating systems and editors
 .DS_Store
-.vscode/
 *.swp
 *.swo
 

.vscode/README.md

@@ -0,0 +1,7 @@
+# VS Code workspace setup
+
+This folder contains portable workspace settings, extension recommendations, and manually invoked tasks. Open the repository root as a folder in VS Code; no machine-specific paths are configured. Tasks do not run automatically.
+
+Python testing is configured for pytest in tests/. The formatter and import actions use Ruff. Select the project interpreter with “Python: Select Interpreter”; no local interpreter path is hard-coded.
+
+The repository's `.editorconfig` remains authoritative for whitespace and line endings. See `AGENTS.md` for the full development workflow.

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "charliermarsh.ruff",
+    "editorconfig.editorconfig"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,34 @@
+{
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "files.encoding": "utf8",
+  "editor.renderWhitespace": "boundary",
+  "editor.minimap.enabled": false,
+  "editor.formatOnPaste": false,
+  "files.exclude": {
+    "**/.venv": true,
+    "**/__pycache__": true,
+    "**/*.egg-info": true,
+    "**/dist": true,
+    "**/build": true
+  },
+  "search.exclude": {
+    "**/.git": true,
+    "**/coverage": true,
+    "**/test-results": true
+  },
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestArgs": [
+    "tests"
+  ],
+  "python.terminal.activateEnvironment": true
+}

.vscode/tasks.json

@@ -0,0 +1,119 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Python: Sync development environment",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "sync",
+        "--extra",
+        "dev"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Ruff format check",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "run",
+        "ruff",
+        "format",
+        "--check",
+        "."
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Ruff lint",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "run",
+        "ruff",
+        "check",
+        "."
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Strict mypy",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "run",
+        "mypy",
+        "--strict"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Tests",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "run",
+        "python",
+        "-m",
+        "pytest"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Build distributions",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "build"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    },
+    {
+      "label": "Python: Check endpoint contracts",
+      "type": "process",
+      "command": "uv",
+      "args": [
+        "run",
+        "python",
+        "scripts/check_contracts.py"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "clear": false
+      }
+    }
+  ]
+}

.zed/settings.json

@@ -0,0 +1,12 @@
+{
+	"code_actions_on_format": {
+		"source.fixAll.biome": true,
+		"source.organizeImports.biome": true
+	},
+	"format_on_save": "on",
+	"formatter": {
+		"language_server": {
+			"name": "biome"
+		}
+	}
+}

CLAUDE.md

@@ -0,0 +1,28 @@
+@AGENTS.md
+
+# Python SDK repository instructions
+
+Read `AGENTS.md` first for repository layout, project conventions, and contract rules. Read `README.md` and the relevant design docs before changing public SDK behavior.
+
+## Contract and compatibility
+
+Support Python 3.9–3.12. Keep the import package frontal_sdk separate from the PyPI distribution name frontal. Use HTTPX, Pydantic v2, uv/Hatchling, Ruff, mypy, pytest, anyio, and offline RESPX tests. Treat contracts as endpoint authority.
+
+Do not add public endpoints, wire fields, or behavior unsupported by the committed contracts. Keep credentials, tokens, and customer data out of source, logs, fixtures, and examples. Make the smallest compatible change and update documentation/examples when public behavior changes.
+
+## Skills
+
+Use the matching skill in `.claude/skills/` when its topic applies. Skills are also linked from `.agents/skills/`; source files live in `skills/` and selected upstream sources are recorded in `skills/SOURCES.md`.
+
+## Verification commands
+
+Run only the commands relevant to the change; do not claim verification unless it was run.
+
+```sh
+uv run ruff format --check .
+uv build
+uv run ruff check .
+uv run mypy --strict
+uv run python -m pytest
+uv run python scripts/check_contracts.py
+```

README.md

@@ -2,6 +2,8 @@
 
 ![Frontal Banner](./banner.png)
 
+[![skills.sh](https://skills.sh/b/frontal-labs/sdk-python)](https://skills.sh/frontal-labs/sdk-python)
+
 The `frontal` package provides synchronous and asynchronous Python clients for
 the Frontal API. Services are available on the client as typed attributes such
 as `client.ai`, `client.agents`, and `client.workflows`.
@@ -87,6 +89,14 @@ The tests use RESPX at the HTTPX layer and do not need a running API or live
 credentials. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md),
 [`docs/TESTING.md`](docs/TESTING.md), and [`docs/PUBLISHING.md`](docs/PUBLISHING.md).
 
+## Agent skills
+
+Install this repository's Python-specific agent skills with the [skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add frontal-labs/sdk-python
+```
+
 ## License
 
 Apache-2.0. See [`LICENSE.md`](LICENSE.md).