using-cortex-skills

# Using Cortex Skills ## Overview Cortex External Agent Skills is a collection of engineering workflow skills designed specifically for configuring, building, validating, and deploying data products in Cortex Framework V7. This meta-skill helps you discover and apply the right skill for your current task. ## Skill Discovery When a task arrives, identify the development phase and apply the corresponding skill: ``` Task arrives │ ├── Asked to setup/configure/validate environment config? ──→ setup-cortex-config │ ├── Asked to create or scaffold a data product? ────────────→ create-data-product │ ├── Asked to update or change an existing data product? ────→ update-data-product │ ├── Asked to validate/test/audit a data product? ───────────→ validate-data-product │ ├── Asked to write/generate python unit tests? ─────────────→ create-python-tests │ ├── Asked to compile/build/deploy/ship a data product? ─────→ build-and-deploy-data-product │ ├── Asked to generate ER diagrams or data model graphs? ────→ generate-er-diagram │ ├── Asked to create/scaffold a new skill or custom rules? ─→ create-skill │ └── Asked to align/review model against business rules? ────→ data-modeling-standards ``` --- ## Core Operating Behaviors These behaviors apply at all times, across all skills. They are non-negotiable. ### 1. Surface Assumptions Before implementing any changes, explicitly state your assumptions: ``` ASSUMPTIONS I'M MAKING: 1. [assumption about requirements] 2. [assumption about data foundation / tables] 3. [assumption about target environment / configuration] → Correct me now or I'll proceed with these. ``` Don't silently fill in ambiguous requirements. Surface uncertainty early — it's cheaper than rework. ### 2. Manage Confusion Actively When you encounter inconsistencies, conflicting requirements, or unclear specifications: 1. **STOP.** Do not proceed with a guess. 2. Name the specific confusion. 3. Present the tradeoff or ask the clarifying question. 4. Wait for resolution before continuing. **Bad:** Silently picking one interpretation and hoping it's right. **Good:** "I see X in the spec but Y in the existing code. Which takes precedence?" ### 3. AI Development & Research Rules * **Ignore Source Skill Directories:** You **MUST** completely ignore the root folders `external-skills/` and `internal-skills/` when reading, writing, or modifying code, configurations, or data products. All active code, configurations, and tests reside strictly inside `cortex-framework-core/`. Do not write files or reference paths inside the root `external-skills/` and `internal-skills/` directories unless explicitly instructed by setup scripts. * **No Hallucination:** Do not hallucinate business logic or SAP table fields. * **SAP Target Version & Live System Inspection:** When implementing SAP-related data models: - You **MUST** explicitly establish and confirm with the user whether the data product targets **ECC**, **S/4HANA**, or **Both**. Proper implementation is impossible without confirming this target version. - You **MUST** retrieve the exact field schemas, data types, key flags, and check table relations for **all** involved SAP tables directly from the replicated SAP Data Dictionary (DDIC) tables in BigQuery using the `query-sap-ddic` skill (via `cortex-framework-core/.venv/bin/python external-skills/.agents/skills/query_sap_ddic/scripts/query_sap_ddic.py`). - You **MUST** explicitly identify and document any structural, field name, or data type differences between ECC and S/4HANA, and handle these differences explicitly in your plan and code (e.g., using version-specific directories like `annotations/ecc/` and `annotations/s4/`, or conditional SQL logic). * **Extensibility & Namespace:** Custom development **MUST** prefer custom namespaces (e.g., `custom`, `myorg`). If the user has not explicitly specified a namespace, you **MUST** ask for a custom namespace before proposing a plan or writing code. Proceed with the standard `cortex` namespace **ONLY** after explicitly warning the user of overwrite/upgrade conflicts and getting their explicit confirmation. * **Verify Foundations:** NEVER assume a field exists in the foundation. You **MUST** verify all required tables exist in `src/data_modules/<namespace>/<source>/foundations/sap/table_settings.default.yaml` and column fields exist in `src/data_modules/<namespace>/<source>/foundations/sap/annotations/`. * **Python Environment & Dependencies:** If running python tools or scripts fails due to missing packages or env errors, you **MUST** run `uv sync` in the `cortex-framework-core/` folder first, and then execute using the virtual environment's interpreter (`cortex-framework-core/.venv/bin/python`). ### 4. Code Structure & File Formats * **Language & Engine:** Cortex V7 uses Dataform. All data models must be written as Dataform `.js` files. * **Target Paths:** * Data Product code goes under `src/data_modules/<namespace>/<source>/products/<type>/` * Data Product config files go under `config/<namespace>/<source>/products/<type>/` * Data Foundation elements belong under `src/data_modules/<namespace>/<source>/foundations/sap/`