feat!: add support for skills (#30)

* feat!: add support for skills

* chore: remove obsolete source of truth (#29)

* move skills

* docs: overhaul documentation for skills-based architecture (#35)

* docs: overhaul documentation for skills-based architecture

* Delete .gitignore

* Update DEVELOPER.md

* revert

* Update ORACLEDB.md

* Update README.md

Author: twishabansal

.github/workflows/skills-validate-fallback.yml

@@ -0,0 +1,37 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: lint
+
+on:
+  push:
+    paths-ignore:
+      - "skills/**"
+  pull_request:
+    paths-ignore:
+      - "skills/**"
+  pull_request_target:
+    types: [labeled]
+    paths-ignore:
+      - "skills/**"
+  workflow_dispatch:
+
+jobs:
+  skills-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Skip Skill Validation
+        run: |
+          echo "No changes detected in 'skills/' directory. Skipping validation."
+          echo "This job ensures the required 'skills-validate' status check passes."

.github/workflows/skills-validate.yml

@@ -0,0 +1,66 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Validate Skills
+
+on:
+  push:
+    paths:
+      - "skills/**"
+  pull_request:
+    paths:
+      - "skills/**"
+  pull_request_target:
+    types: [labeled]
+    paths:
+      - "skills/**"
+
+jobs:
+  skills-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+
+      - name: Install skills-ref
+        run: |
+          pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
+
+      - name: Validate Skills
+        run: |
+          failed=0
+          # Check if skills/ is a skill directory itself
+          if [ -f "skills/SKILL.md" ]; then
+            echo "Validating skills/..."
+            if ! skills-ref validate "skills/"; then
+              echo "Validation failed for skills/"
+              failed=1
+            fi
+          else
+            # Also check subdirectories (in case there are multiple skills)
+            for skill_dir in skills/*/; do
+              if [ -d "$skill_dir" ] && [ -f "${skill_dir}SKILL.md" ]; then
+                echo "Validating $skill_dir..."
+                if ! skills-ref validate "$skill_dir"; then
+                  echo "Validation failed for $skill_dir"
+                  failed=1
+                fi
+              fi
+            done
+          fi
+          exit $failed

DEVELOPER.md

@@ -10,85 +10,46 @@ Before you begin, ensure you have the following:
 1.  **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation
     instructions can be found on the official Gemini CLI documentation. You can
     verify your version by running `gemini --version`.
-2.  **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active 
+2.  **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active
     Oracle DB instance. We recommend using Public IP to eliminate the need to create and use a workspace
-    within the same VPC network as the database. 
+    within the same VPC network as the database.
 
 ## Developing the Extension
 
 ### Running from Local Source
 
-The core logic for this extension is handled by a pre-built `toolbox` binary. The development process involves installing the extension locally into the Gemini CLI to test changes.
-
 1.  **Clone the Repository:**
 
     ```bash
     git clone https://github.com/gemini-cli-extensions/oracledb.git
     cd oracledb
     ```
 
-2.  **Download the Toolbox Binary:** The required version of the `toolbox` binary
-    is specified in `toolbox_version.txt`. Download it for your platform.
+2.  **Install the Extension Locally:** Use the Gemini CLI to install the extension from your local directory.
 
     ```bash
-    # Read the required version
-    VERSION=$(cat toolbox_version.txt)
-
-    # Download the binary for your platform. The binary must be named `toolbox`.
-    # Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`).
-    # Example for macOS/amd64:
-    curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox
-    chmod +x toolbox
-
-    # For Windows, you will need to download the .exe file and rename it to `toolbox`.
-    # The `chmod` command is not required on Windows.
+    gemini extensions install .
     ```
 
-3.  **Link the Extension Locally:** Use the Gemini CLI to install the
-    extension from your local directory.
-
-    ```bash
-    gemini extensions link .
-    ```
-    The CLI will prompt you to confirm the linking. Accept it to proceed.
+    The CLI will prompt you to confirm the installation and enter your configuration.
 
-4.  **Testing Changes:** After linking, start the Gemini CLI (`gemini`).
-    You can now interact with the `oracledb` tools to manually test your changes
-    against your connected database.
+3.  **Testing Changes:** After installation, start the Gemini CLI (`gemini`). You can now interact with the `oracledb` skills to manually test your changes against your connected database.
 
 ## Testing
 
 ### Automated Presubmit Checks
 
-A GitHub Actions workflow (`.github/workflows/presubmit-tests.yml`) is triggered
-for every pull request. This workflow primarily verifies that the extension can
-be successfully installed by the Gemini CLI.
+A GitHub Actions workflow (`.github/workflows/presubmit-tests.yml`) is triggered for every pull request. This workflow primarily verifies that the extension can be successfully installed by the Gemini CLI.
 
-Currently, there are no automated unit or integration test suites
-within this repository. All functional testing must be performed manually. All tools
-are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox).
+All skills are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox).
 
-### Other GitHub Checks
-
-* **License Header Check:** A workflow ensures all necessary files contain the
-    proper license header.
-* **Conventional Commits:** This repository uses
-    [Release Please](https://github.com/googleapis/release-please) to manage
-    releases. Your commit messages must adhere to the
-    [Conventional Commits](https://www.conventionalcommits.org/) specification.
-* **Dependency Updates:** [Renovate](https://github.com/apps/forking-renovate)
-    is configured to automatically create pull requests for dependency updates.
-
-## Building the Extension
+The skills themselves are validated using the `skills-validate.yml` workflow.
 
-The "build" process for this extension involves packaging the extension's
-metadata files (`gemini-extension.json`, `ORACLEDB.md`, `LICENSE`) along with the
-pre-built `toolbox` binary into platform-specific archives (`.tar.gz` or `.zip`).
+### Other GitHub Checks
 
-This process is handled automatically by the
-[`package-and-upload-assets.yml`](.github/workflows/package-and-upload-assets.yml)
-GitHub Actions workflow when a new release is created. Manual building is not
-required.
+- **License Header Check:** A workflow ensures all necessary files contain the proper license header.
+- **Conventional Commits:** This repository uses [Release Please](https://github.com/googleapis/release-please) to manage releases. Your commit messages must adhere to the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+- **Dependency Updates:** [Renovate](https://github.com/apps/forking-renovate) is configured to automatically create pull requests for dependency updates.
 
 ## Maintainer Information
 
@@ -97,8 +58,8 @@ required.
 The primary maintainers for this repository are defined in the
 [`.github/CODEOWNERS`](.github/CODEOWNERS) file:
 
-* `@gemini-cli-extensions/senseai-eco`
-* `@gemini-cli-extensions/oracledb-maintainers`
+- `@gemini-cli-extensions/senseai-eco`
+- `@gemini-cli-extensions/oracledb-maintainers`
 
 ### Releasing
 
@@ -120,7 +81,6 @@ The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-
 3. **Filtering:** These release notes are filtered to include only changes
    relevant to this extension. The relevance is determined by a keyword (e.g.,
    `oracledb`), passed as an environment variable in the workflow file.
-   `oracledb`), passed as an environment variable in the workflow file.
 4. **Changelog Injection:** The script formats the filtered entries as
    conventional commits and injects them into the PR body within a
    `BEGIN_COMMIT_OVERRIDE` block.
@@ -145,7 +105,3 @@ The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-
 2.  **Merge Release PR:** A maintainer approves and merges the Release PR. This
     action triggers `release-please` to create a new GitHub tag and a
     corresponding GitHub Release.
-3.  **Package and Upload:** The new release triggers the
-    `package-and-upload-assets.yml` workflow. This workflow builds the
-    platform-specific extension archives and uploads them as assets to the
-    GitHub Release.

ORACLEDB.md

@@ -1,42 +1,26 @@
 # Setup
-## Required Gemini CLI Version
-To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`.
-gemini extensions install https://github.com/gemini-cli-extensions/oracledb
 
-## Oracle Database MCP Server (Data Plane: Connecting and Querying)
-This section covers connecting to a Oracle Database instance in different deployments and client configurations.
-
-### 1. Authentication
-Set the following environment variables before starting the Gemini CLI.
+## Required Gemini CLI Version
 
-* `ORACLE_USER`: Your Oracle database username.
-* `ORACLE_PASSWORD`: Your Oracle database password.
+To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`.
 
-### 2. Connection Method
-Choose **one** of the following connection methods and set the corresponding environment variables:
+## Oracle Database Agent Skills (Data Plane: Connecting and Querying)
 
-#### Method A: Host, Port, and Service Name
-*   `ORACLE_HOST`: The hostname or IP address of your Oracle Database server.
-*   `ORACLE_PORT`: The port number your Oracle Database is listening on.
-*   `ORACLE_SERVICE_NAME`: The service name for the Oracle Database.
+This section covers connecting to an Oracle Database instance.
 
-#### Method B: TNS Alias
-*   `ORACLE_TNS_ALIAS`: The TNS alias of your Oracle Database from your `tnsnames.ora` file.
-*   `ORACLE_TNS_ADMIN`: The path to the directory containing your `tnsnames.ora` file.
+1. **Extension Configuration**: This extension requires several settings (e.g., Connection String, Username, Password, and optionally Wallet Path and Use OCI). These values are gathered via prompts when you first install or link the extension:
 
-#### Method C: Direct Connection String
-*   `ORACLE_CONNECTION_STRING`: The direct connection string for your Oracle Database (e.g., in EZConnect format).
+* `ORACLE_CONNECTION_STRING`: The connection string for your Oracle Database (e.g., `host:port/service_name` or TNS alias).
+* `ORACLE_USERNAME`: Your Oracle database username.
+* `ORACLE_PASSWORD`: Your Oracle database password.
+* `ORACLE_WALLET`: (Optional) Path to the directory containing your Oracle Wallet files.
+* `ORACLE_USE_OCI`: (Optional) Set to `true` to use the OCI (thick client) driver.
 
-### 3. Optional Configuration
+If you need to update any of these values later, use the `gemini extensions config oracledb` command.
 
-#### Oracle Wallet / OCI
-If you are connecting to an OCI-based database or using an Oracle Wallet:
-*   `ORACLE_WALLET`: Path to the directory containing your Oracle Wallet files.
-*   `ORACLE_USE_OCI`: Set to `true` to use the OCI (thick client) driver. This is typically required for wallet authentication. When using wallet authentication, the `ORACLE_TNS_ADMIN` variable should be set to the wallet directory path, and you should connect using a TNS alias.
+2. **Handle Missing Variables**: If a command fails with an error related to a missing configuration, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it.
 
-### 4. Troubleshooting
-*   **Missing Variables**: If a command fails with an error related to a missing configuration, it signifies a missing environment variable. Please review the setup instructions and ensure the necessary variables are set.
-*   **Permission Errors**: If you encounter permission errors, ensure the user has the required database-level permissions. `CREATE SESSION` is required for any user to connect. For monitoring and diagnostic tools, `SELECT` privileges on various `V$` (Dynamic Performance Views) and `DBA_` (Data Dictionary Views) are often necessary.
+3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the required database-level permissions. `CREATE SESSION` is required for any user to connect. For monitoring and diagnostic skills, `SELECT` privileges on various `V$` (Dynamic Performance Views) and `DBA_` (Data Dictionary Views) are often necessary.
 
 ## Oracle DB Permisions 
 This section covers administrative operations like managing clusters, instances, and users.
@@ -55,14 +39,15 @@ This section covers administrative operations like managing clusters, instances,
 
 # Usage Guidelines
 ## Connecting to New Resources
-When you create a new Oracle DB instance, or database using the available tools, the connection is not automatically established. You will need to perform the following steps:
+When you create a new Oracle DB instance, or database using the available skills, the connection is not automatically established. You will need to perform the following steps:
 
 1.  **(Optional) Save your conversation:** To avoid losing your progress, save the current session by running the command: `/chat save <your-tag>`
 2.  **Stop the CLI:** Terminate the Gemini CLI.
-3.  **Update Environment Variables:** Set or update your environment variables (e.g. `ORACLE_TNSALIAS`, `ORACLE_USER`) to point to the new resource.
+3.  **Update Extension Configuration:** Use the command `gemini extensions config oracledb` to update your settings (e.g. `ORACLE_CONNECTION_STRING`, `ORACLE_USERNAME`) to point to the new resource.
 4.  **Restart:** Relaunch the Gemini CLI
 5.  **(Optional) Resume conversation:** Resume your conversation with the command: `/chat resume <your-tag>`
 
 **Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection.
-Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse of a specific value.
-Make sure to not use the environment variable names like `ORACLE_TNSALIAS`, `${ORACLE_TNSALIAS}`, or `$ORACLE_TNSALIAS`. The value can be found by using command: `echo $ORACLE_USER`.
+Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value.
+Make sure to not use the environment variable names like `ORACLE_CONNECTION_STRING`, `${ORACLE_CONNECTION_STRING}`, or `$ORACLE_CONNECTION_STRING`.
+The value can be verified by the user using the `gemini extensions config oracledb` command or by checking their local settings.