feat: Add agent skills and Cursor/Claude rules for Feast development

ntkathole · ntkathole · commit 312eea3e3639 · 2026-05-03T20:26:50.000+05:30
Add tool-agnostic agent skills (compatible with Claude Code, Cursor,
OpenAI Codex, and similar AI tools):

- skills/feast-architecture/SKILL.md: internals of each component
  (registry, provider, online/offline store, feature server, operator,
  data flows, serialization)
- skills/feast-dev/SKILL.md: contributor workflow, setup, Docker, docs
- skills/feast-testing/SKILL.md: how to run and write tests
- skills/feast-user-guide/SKILL.md: using Feast as an end user

Add Cursor rules (.cursor/rules/) and Claude rules (.claude/rules/)
with symlinks to the shared skill files so each tool picks up the
same guidance automatically.

Update AGENTS.md to reference the new skills table and tighten the
command examples. Update .gitignore to track .claude rules/skills
while still ignoring ephemeral local-state files.

Signed-off-by: ntkathole &lt;nikhilkathole2683@gmail.com&gt;
diff --git a/.claude/rules/feast-components.md b/.claude/rules/feast-components.md
@@ -0,0 +1,44 @@
+---
+paths:
+  - sdk/python/feast/infra/online_stores/**
+  - sdk/python/feast/infra/offline_stores/**
+  - sdk/python/feast/infra/registry/**
+  - sdk/python/tests/unit/infra/**
+  - go/**
+  - infra/feast-operator/**
+---
+
+Read `skills/feast-architecture/SKILL.md` for the relevant component section:
+
+| Working in… | Read section |
+|---|---|
+| `online_stores/` | Online Store — config pattern, entity key serialization, async support, registration |
+| `offline_stores/` | Offline Store — interface, PIT join, pull_latest, adding a new backend |
+| `infra/registry/` | Registry — proto vs SQL backend, caching, adding new object types |
+| `go/` | Go Feature Server — entry point, serving path, online store interface, build commands |
+| `infra/feast-operator/` | Feast Operator — CRD spec, reconcile loop, RBAC markers, dev workflow |
+
+For testing patterns and debugging, also read `skills/feast-testing/SKILL.md`.
+
+## When making any component change
+
+- **Unit tests**: add or update tests in `sdk/python/tests/unit/infra/<subsystem>/`
+- **Integration tests**: run `make test-python-integration-local`; add a universal test case in `sdk/python/tests/integration/` if the change affects retrieval or materialization behavior
+- **Protos**: if you add a field to a proto message, recompile with `make protos` and update serialization helpers in `proto_registry_utils.py`
+- **Both SDKs**: if the change affects online serving, check whether the Go server (`go/`) also needs updating
+- **Skills/Rules**: if the change introduces new patterns, interfaces, or conventions that agents should follow, update the relevant section in `skills/feast-architecture/SKILL.md` (and `skills/feast-testing/SKILL.md` if testing patterns changed)
+
+## Documentation — where to add/update
+
+| Change type | Doc location | Also update |
+|---|---|---|
+| New **online store** | `docs/reference/online-stores/<name>.md` (copy an existing one as template) | `docs/reference/online-stores/README.md`, `docs/SUMMARY.md` (under "Online stores") |
+| New **offline store** | `docs/reference/offline-stores/<name>.md` | `docs/reference/offline-stores/README.md`, `docs/reference/offline-stores/overview.md`, `docs/SUMMARY.md` |
+| New **registry backend** | `docs/reference/registries/<name>.md` | `docs/SUMMARY.md` |
+| Config option change | `docs/reference/feature-store-yaml.md` | — |
+| New CLI flag or command | `docs/reference/feast-cli-commands.md` | — |
+| How-to / integration guide | `docs/how-to-guides/customizing-feast/` or `docs/how-to-guides/` | `docs/SUMMARY.md` |
+| Architecture / concept | `docs/getting-started/architecture/` or `docs/getting-started/components/` | `docs/SUMMARY.md` |
+| Blog post | `/infra/website/docs/blog/` (NOT `docs/blog/`) | — |
+
+All `docs/` pages are rendered by GitBook via `docs/SUMMARY.md`. Any new page must be added to `SUMMARY.md` or it won't appear in the site navigation.
diff --git a/.claude/rules/feast-skills-maintenance.md b/.claude/rules/feast-skills-maintenance.md
@@ -0,0 +1,28 @@
+---
+paths:
+  - skills/**
+  - AGENTS.md
+  - .cursor/rules/**
+  - .claude/rules/**
+---
+
+## When editing skills or rules
+
+Skills and rules are only useful if they accurately reflect the real codebase. Before finalising any skill/rule edit:
+
+**Verify against source code:**
+- Command examples (lint, test, type-check) — confirm they still match `Makefile` targets and `pyproject.toml`
+- File paths and class names — confirm they exist in the repo
+- Interface signatures (e.g. `OnlineStore`, `OfflineStore`, `BaseRegistry`) — confirm against the actual base class files
+- Config field names — confirm against `RepoConfig` and `FeastConfigBaseModel` subclasses in `sdk/python/feast/repo_config.py`
+
+**Keep scope consistent:**
+- `AGENTS.md` — entry point only; commands, skills table, code style. Max ~120 lines.
+- `skills/feast-architecture/SKILL.md` — how each component works internally; data flows; adding new backends
+- `skills/feast-testing/SKILL.md` — how to run, write, and debug tests
+- `skills/feast-dev/SKILL.md` — contributor workflow; setup; Docker; docs locations; PR process
+- `skills/feast-user-guide/SKILL.md` — how to use Feast as an end user; feature definitions; retrieval; RAG
+- `.cursor/rules/feast-components.mdc` / `.claude/rules/feast-components.md` — component checklist (tests, docs, skills); keep in sync with each other
+
+**Keep the two rule files in sync:**
+`.cursor/rules/feast-components.mdc` and `.claude/rules/feast-components.md` contain the same content with only different frontmatter (`globs:` vs `paths:`). Any content change must be applied to both.
diff --git a/.claude/skills/feast-architecture/SKILL.md b/.claude/skills/feast-architecture/SKILL.md
@@ -0,0 +1 @@
+../../../skills/feast-architecture/SKILL.md
diff --git a/.claude/skills/feast-dev/SKILL.md b/.claude/skills/feast-dev/SKILL.md
@@ -0,0 +1 @@
+../../../skills/feast-dev/SKILL.md
diff --git a/.claude/skills/feast-testing/SKILL.md b/.claude/skills/feast-testing/SKILL.md
@@ -0,0 +1 @@
+../../../skills/feast-testing/SKILL.md
diff --git a/.claude/skills/feast-user-guide/SKILL.md b/.claude/skills/feast-user-guide/SKILL.md
@@ -0,0 +1 @@
+../../../../skills/feast-user-guide/SKILL.md
diff --git a/.cursor/rules/feast-components.mdc b/.cursor/rules/feast-components.mdc
@@ -0,0 +1,40 @@
+---
+description: Component-level guidance for Feast subsystems
+globs: sdk/python/feast/infra/online_stores/**,sdk/python/feast/infra/offline_stores/**,sdk/python/feast/infra/registry/**,sdk/python/tests/unit/infra/**,go/**,infra/feast-operator/**
+alwaysApply: false
+---
+
+Read `skills/feast-architecture/SKILL.md` for the relevant component section:
+
+| Working in… | Read section |
+|---|---|
+| `online_stores/` | Online Store — config pattern, entity key serialization, async support, registration |
+| `offline_stores/` | Offline Store — interface, PIT join, pull_latest, adding a new backend |
+| `infra/registry/` | Registry — proto vs SQL backend, caching, adding new object types |
+| `go/` | Go Feature Server — entry point, serving path, online store interface, build commands |
+| `infra/feast-operator/` | Feast Operator — CRD spec, reconcile loop, RBAC markers, dev workflow |
+
+For testing patterns and debugging, also read `skills/feast-testing/SKILL.md`.
+
+## When making any component change
+
+- **Unit tests**: add or update tests in `sdk/python/tests/unit/infra/<subsystem>/`
+- **Integration tests**: run `make test-python-integration-local`; add a universal test case in `sdk/python/tests/integration/` if the change affects retrieval or materialization behavior
+- **Protos**: if you add a field to a proto message, recompile with `make protos` and update serialization helpers in `proto_registry_utils.py`
+- **Both SDKs**: if the change affects online serving, check whether the Go server (`go/`) also needs updating
+- **Skills/Rules**: if the change introduces new patterns, interfaces, or conventions that agents should follow, update the relevant section in `skills/feast-architecture/SKILL.md` (and `skills/feast-testing/SKILL.md` if testing patterns changed)
+
+## Documentation — where to add/update
+
+| Change type | Doc location | Also update |
+|---|---|---|
+| New **online store** | `docs/reference/online-stores/<name>.md` (copy an existing one as template) | `docs/reference/online-stores/README.md`, `docs/SUMMARY.md` (under "Online stores") |
+| New **offline store** | `docs/reference/offline-stores/<name>.md` | `docs/reference/offline-stores/README.md`, `docs/reference/offline-stores/overview.md`, `docs/SUMMARY.md` |
+| New **registry backend** | `docs/reference/registries/<name>.md` | `docs/SUMMARY.md` |
+| Config option change | `docs/reference/feature-store-yaml.md` | — |
+| New CLI flag or command | `docs/reference/feast-cli-commands.md` | — |
+| How-to / integration guide | `docs/how-to-guides/customizing-feast/` or `docs/how-to-guides/` | `docs/SUMMARY.md` |
+| Architecture / concept | `docs/getting-started/architecture/` or `docs/getting-started/components/` | `docs/SUMMARY.md` |
+| Blog post | `/infra/website/docs/blog/` (NOT `docs/blog/`) | — |
+
+All `docs/` pages are rendered by GitBook via `docs/SUMMARY.md`. Any new page must be added to `SUMMARY.md` or it won't appear in the site navigation.
diff --git a/.cursor/rules/feast-skills-maintenance.mdc b/.cursor/rules/feast-skills-maintenance.mdc
@@ -0,0 +1,26 @@
+---
+description: Guidance for keeping skills and rules accurate and up to date
+globs: skills/**,AGENTS.md,.cursor/rules/**,.claude/rules/**
+alwaysApply: false
+---
+
+## When editing skills or rules
+
+Skills and rules are only useful if they accurately reflect the real codebase. Before finalising any skill/rule edit:
+
+**Verify against source code:**
+- Command examples (lint, test, type-check) — confirm they still match `Makefile` targets and `pyproject.toml`
+- File paths and class names — confirm they exist in the repo
+- Interface signatures (e.g. `OnlineStore`, `OfflineStore`, `BaseRegistry`) — confirm against the actual base class files
+- Config field names — confirm against `RepoConfig` and `FeastConfigBaseModel` subclasses in `sdk/python/feast/repo_config.py`
+
+**Keep scope consistent:**
+- `AGENTS.md` — entry point only; commands, skills table, code style. Max ~120 lines.
+- `skills/feast-architecture/SKILL.md` — how each component works internally; data flows; adding new backends
+- `skills/feast-testing/SKILL.md` — how to run, write, and debug tests
+- `skills/feast-dev/SKILL.md` — contributor workflow; setup; Docker; docs locations; PR process
+- `skills/feast-user-guide/SKILL.md` — how to use Feast as an end user; feature definitions; retrieval; RAG
+- `.cursor/rules/feast-components.mdc` / `.claude/rules/feast-components.md` — component checklist (tests, docs, skills); keep in sync with each other
+
+**Keep the two rule files in sync:**
+`.cursor/rules/feast-components.mdc` and `.claude/rules/feast-components.md` contain the same content with only different frontmatter (`globs:` vs `paths:`). Any content change must be applied to both.
diff --git a/.gitignore b/.gitignore
@@ -266,4 +266,7 @@ Desktop.ini
 .agentready/
 
 # Claude Code project settings
-.claude/
+# Claude Code local state (conversation history, credentials, cache)
+.claude/settings.local.json
+.claude/todos/
+.claude/cache/
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,98 +17,51 @@ Feast (Feature Store) is a Python-based project that provides:
 
 ### Setup
 ```bash
-# Install development dependencies
 make install-python-dependencies-dev
-
-# Install minimal dependencies
 make install-python-dependencies-minimal
 ```
 
 ### Code Quality
 ```bash
-# Format Python code
+# Format Python code (entire codebase)
 make format-python
 
-# Lint Python code
+# Lint Python code (entire codebase)
 make lint-python
 
-# Type check
-cd sdk/python && python -m mypy feast
-```
-
-### Testing
-```bash
-# Run unit tests
-make test-python-unit
-
-# Run integration tests (local)
-make test-python-integration-local
+# Full type check (entire codebase)
+uv run bash -c "cd sdk/python && mypy feast"
 
-# Run integration tests (CI)
-make test-python-integration
-
-# Run all Python tests
-make test-python-universal
+# Full type check including tests
+make mypy-full
 ```
 
-### Protobuf Compilation
+#### Single-file lint and type-check
+When working on a specific file, run checks scoped to that file to get fast feedback:
 ```bash
-# Compile Python protobuf files
-make compile-protos-python
-
-# Compile all protos
-make protos
+uv run ruff check sdk/python/feast/path/to/file.py          # lint
+uv run ruff check --fix sdk/python/feast/path/to/file.py    # lint + auto-fix
+uv run ruff format sdk/python/feast/path/to/file.py         # format
+uv run bash -c "cd sdk/python && mypy feast/path/to/file.py" # type-check
 ```
 
-### Go Development
+### Testing
 ```bash
-# Build Go code
-make build-go
-
-# Test Go code
-make test-go
-
-# Format Go code
-make format-go
-
-# Lint Go code
-make lint-go
+make test-python-unit                  # unit tests
+make test-python-integration-local    # integration tests (local)
+make test-python-integration          # integration tests (CI)
+make test-python-universal            # all Python tests
 ```
 
-### Docker
+### Protobuf Compilation
 ```bash
-# Build all Docker images
-make build-docker
-
-# Build feature server Docker image
-make build-feature-server-docker
+make compile-protos-python   # Python protobufs
+make protos                  # all protos
 ```
 
-### Documentation
+### Go Development
 ```bash
-# Build Sphinx documentation
-make build-sphinx
-
-# Build templates
-make build-templates
-
-# Build Helm docs
-make build-helm-docs
-```
-
-## Project Structure
-
-```
-feast/
-├── sdk/python/          # Python SDK and core implementation
-├── go/                 # Go implementation
-├── ui/                 # Web UI
-├── docs/               # Documentation
-├── examples/           # Example projects
-├── infra/              # Infrastructure and deployment
-│   ├── charts/         # Helm charts
-│   └── feast-operator/ # Kubernetes operator
-└── protos/             # Protocol buffer definitions
+make build-go && make test-go && make format-go && make lint-go
 ```
 
 ## Key Technologies
@@ -120,24 +73,30 @@ feast/
 - **Offline Stores**: BigQuery, Snowflake, Redshift, Spark, Dask, DuckDB
 - **Cloud Providers**: AWS, GCP, Azure
 
-## Common Development Tasks
+## Agent Skills
+
+The `skills/` directory contains tool-agnostic skills (compatible with Claude Code, OpenAI Codex, and other agent tools):
+
+| Skill | Path | Use when… |
+|---|---|---|
+| **feast-user-guide** | `skills/feast-user-guide/SKILL.md` | Working with Feast as a user: defining features, retrieval, CLI, RAG |
+| **feast-dev** | `skills/feast-dev/SKILL.md` | Contributing to Feast: setup, tests, Docker, docs, PR workflow |
+| **feast-architecture** | `skills/feast-architecture/SKILL.md` | Understanding how each component works: registry, materialization, feature server, data flows |
+| **feast-testing** | `skills/feast-testing/SKILL.md` | Writing tests, running targeted tests, debugging registry/online store issues |
+
+Reference docs: `skills/references/` — feature definitions, configuration, retrieval & RAG.
 
-### Running Tests
-The project uses pytest for Python testing with extensive integration test suites for different data sources and stores.
+Architecture & design intent: `docs/getting-started/architecture/` (overview, write patterns, RBAC), `docs/getting-started/components/` (per-component pages), `docs/adr/` (design decisions).
+
+## Code Style
 
-### Code Style
 - Use type hints on all Python function signatures
 - Follow existing patterns in the module you are modifying
 - PR titles must follow semantic conventions: `feat:`, `fix:`, `ci:`, `chore:`, `docs:`
 - Sign off commits with `git commit -s` (DCO requirement)
-- Uses `ruff` for Python linting and formatting
-- Go uses standard `gofmt`
-
-### Protobuf Development
-Protocol buffers are used for data serialization and gRPC APIs. Recompile protos after making changes to `.proto` files.
-
-### Multi-language Support
-Feast supports Python and Go SDKs. Changes to core functionality may require updates across both languages.
+- Uses `ruff` for Python linting and formatting; Go uses standard `gofmt`
+- Recompile protos after making changes to `.proto` files (`make protos`)
+- Changes to core functionality may require updates across both Python and Go SDKs
 
 ## Documentation and Blog Posts
 
diff --git a/skills/feast-architecture/SKILL.md b/skills/feast-architecture/SKILL.md
diff --git a/skills/feast-dev/SKILL.md b/skills/feast-dev/SKILL.md
diff --git a/skills/feast-testing/SKILL.md b/skills/feast-testing/SKILL.md
diff --git a/skills/feast-user-guide/SKILL.md b/skills/feast-user-guide/SKILL.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../skills/feast-architecture/SKILL.md`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../skills/feast-user-guide/SKILL.md`