@codemieai/code 0.2.0 → 0.2.1

package/dist/agents/plugins/claude/plugin/skills/codemie-sdk/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: codemie-sdk
+description: >-
+  Manage CodeMie platform assets (assistants, workflows, datasources, integrations, skills, users, assistant-categories) directly from CLI
+  using CodeMie SDK. Use when user says "create assistant", "list workflows", "update datasource",
+  "delete assistant", "show my assistants", "get workflow details", "manage integrations",
+  "create integration", "list integrations", "list llm models", "list embedding models",
+  "list skills", "get skill", "create skill", "update skill", "delete skill", "publish skill",
+  "import skill", "export skill", "attach skill", "list assistant categories", "get assistant category",
+  "create assistant category", "delete assistant category", "who am i", "current user", "my profile", "user info",
+  or any request to manage CodeMie platform resources.
+  NOTE: For analytics requests (usage analytics, summaries, spending, users activity, leaderboards, etc.) use the codemie-analytics skill instead.
+---
+
+# CodeMie SDK Asset Management
+
+Manage CodeMie platform assets from the CLI.
+
+> **Analytics requests** (usage data, summaries, spending, activity, etc.) are handled by the **codemie-analytics** skill — use that instead.
+
+**Asset Types:** `assistants`, `workflows`, `datasources`, `integrations`, `skills`, `users`, `assistant-categories`
+
+**Operations:** `list`, `get`, `create`, `update`, `delete`
+
+---
+
+## 🚨 Project Clarification (MANDATORY)
+
+**Before proceeding with any work, you must determine which project to use by following these steps:**
+
+### Step 1 — Fetch the User Profile
+
+```bash
+codemie sdk users me --json
+```
+
+This command returns `user_id`, `username`, `email`, `is_admin`, `applications`, and `applications_admin`.
+
+### Step 2 — Identify Available Projects
+
+- If `is_admin = true`: the user can access **all** projects on the platform, not just those listed in `applications`.
+- If `is_admin = false`: the user can only work with projects listed in `applications`.
+- The **default project** is the one matching the user's email (e.g., for `alice@acme.com`, the default project is `alice@acme.com`).
+
+### Step 3 — Confirm the Project Selection
+
+- If the user **explicitly** states a project name, or uses phrases like **"use my project"** or **"in my project"**, proceed with the identified project (use the default project for phrases like "my project" or "my default project").
+- In **all other cases**, ALWAYS ask the user which project to use.
+
+Aks the user what project to use with the options as follows:
+
+1. **Default project** — `<user-email>` *(personal default project)*
+2. **Choose a different project** — let the user to manually type the project name.
+
+**Example prompt:**
+> *Which project should I use?*  
+> *1. alice@acme.com (your default project)*  
+> *2. Choose a different project*
+
+---
+
+**Note:**  
+Only select a project automatically if the user has explicitly named it, or used clear phrases indicating the default (e.g., "my project", "my default project"). In all other situations, always ask for project clarification.
+
+### Step 4 — Proceed
+
+Once the project is known, use it in all subsequent commands:
+- Assistants, skills, assistant-categories: `"project": "<name>"`
+- Workflows, datasources, integrations: `"project_name": "<name>"`
+
+---
+
+## 📖 Consult Examples Before Working on an Asset (MANDATORY)
+
+**Before creating, updating, or querying any asset**, read the corresponding example file for complete field references, schemas, and commands to fetch referenced assets.
+
+| Asset | Example file |
+|-------|-------------|
+| Assistants | [examples/assistants.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/assistants.md) |
+| Workflows | [examples/workflows.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/workflows.md) |
+| Datasources | [examples/datasources.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/datasources.md) |
+| Integrations | [examples/integrations.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/integrations.md) |
+| Skills | [examples/skills.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/skills.md) |
+| Users | [examples/users.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/users.md) |
+| Assistant Categories | [examples/categories.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/categories.md) |
+
+Do **not** guess field names or skip this step — all required/optional fields, nested schemas, and asset cross-reference commands are documented there.
+
+---
+
+## Input / Output
+
+**Two ways to pass data:**
+- Inline JSON: `--data '{"key":"value"}'`
+- From file: `--json path/to/config.json`
+
+**IDs are UUIDs**, e.g. `bc1a4b75-955c-48a5-b26d-bf702c1fee5d`
+
+**Create does not return the new ID** in the output. After creating, use `list --search` to find the new asset's ID.
+
+**Update replaces non-primitive values in full** — arrays and objects are not merged with existing values; the value you provide replaces the entire field. To preserve existing entries, either do not provide the value at all or fetch the current state first (`get <id> --json`), merge locally, then send the full updated value.
+
+---
+
+## Assistants
+
+> See [examples/assistants.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/assistants.md) for full field reference and examples.
+
+```bash
+codemie sdk assistants list [--scope visible_to_user|marketplace] [--search <text>] [--projects <name>] [--page <n>] [--per-page <n>] [--full-response] [--json]
+codemie sdk assistants get <id> [--json]
+codemie sdk assistants get-tools [--json]
+codemie sdk assistants create --data '<json>' | --json <file>
+codemie sdk assistants update <id> --data '<json>' | --json <file>
+codemie sdk assistants delete <id>
+```
+
+**Required on create:** `name`, `project`, `system_prompt`
+
+---
+
+## Workflows
+
+> See [examples/workflows.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/workflows.md) for full field reference and examples.
+
+```bash
+codemie sdk workflows list [--search <text>] [--projects <name>] [--page <n>] [--per-page <n>] [--json]
+codemie sdk workflows get <id> [--json]
+codemie sdk workflows create --data '<json>' --config '<yaml>' | --config path/to/config.yaml
+codemie sdk workflows update <id> --data '<json>' [--config '<yaml>' | --config path/to/config.yaml]
+codemie sdk workflows delete <id>
+```
+
+**Required on create:** `name`, `project`, `mode` (`"Sequential"`), `shared` (boolean), plus `--config` with YAML graph definition
+
+---
+
+## Datasources
+
+> See [examples/datasources.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/datasources.md) for full field reference and examples.
+
+Type subcommands for create/update: `confluence`, `jira`, `file`, `code`, `google`, `provider`, `azure-devops-wiki`, `azure-devops-work-item`, `xray`, `sharepoint`
+
+```bash
+codemie sdk datasources list [--search <text>] [--projects <name>] [--status <status>] [--datasource-types <types>] [--sort-key date|update_date] [--sort-order asc|desc] [--page <n>] [--per-page <n>] [--json]
+codemie sdk datasources get <id> [--json]
+codemie sdk datasources create <type> --data '<json>' | --json <file>
+codemie sdk datasources update <type> <id> --data '<json>' | --json <file>
+codemie sdk datasources delete <id>
+# file type only: --file ./doc.pdf (repeatable, max 10)
+```
+
+**Required on create (all types):** `name` (no spaces, use hyphens), `project_name`, plus type-specific required fields
+
+---
+
+## Integrations
+
+> See [examples/integrations.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/integrations.md) for full field reference and examples.
+
+```bash
+codemie sdk integrations list [--setting-type user|project] [--search <text>] [--projects <name>] [--page <n>] [--per-page <n>] [--json]
+codemie sdk integrations get <id> [--setting-type user|project] [--json]
+codemie sdk integrations get-by-alias <alias> [--setting-type user|project] [--json]
+codemie sdk integrations create --data '<json>' | --json <file>
+codemie sdk integrations update <id> --data '<json>' | --json <file>
+codemie sdk integrations delete <id> [--setting-type user|project]
+```
+
+**Required on create:** `credential_type`, `project_name`, `credential_values` (must include `{"key":"alias","value":"<alias>"}`)
+
+---
+
+## LLM Models
+
+```bash
+codemie sdk llm list [--json]
+codemie sdk llm list --embeddings [--json]
+```
+
+Use `base_name` when setting `llm_model_type` on an assistant or `embeddings_model`/`summarization_model` on a datasource.
+
+---
+
+## Skills
+
+> See [examples/skills.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/skills.md) for full field reference and examples.
+
+```bash
+codemie sdk skills list [--scope marketplace|project|project_with_marketplace] [--page <n>] [--per-page <n>] [--json]
+codemie sdk skills get <id> [--json]
+codemie sdk skills create --data '<json>' | --json <file>
+codemie sdk skills update <id> --data '<json>' | --json <file>
+codemie sdk skills delete <id>
+codemie sdk skills import <file.md> --project <name> [--visibility private|project|public] [--json]
+codemie sdk skills export <id>
+codemie sdk skills attach <assistant-id> <skill-id>
+codemie sdk skills detach <assistant-id> <skill-id>
+codemie sdk skills list-assistant-skills <assistant-id> [--json]
+codemie sdk skills bulk-attach <skill-id> --assistant-ids <id1>,<id2>,...
+codemie sdk skills get-assistants <skill-id> [--json]
+codemie sdk skills publish <id> [--categories <cat1>,<cat2>]
+codemie sdk skills unpublish <id>
+codemie sdk skills list-categories [--json]
+codemie sdk skills get-users [--json]
+codemie sdk skills react <id> --reaction like|dislike
+codemie sdk skills remove-reactions <id>
+```
+
+**Required on create:** `name` (kebab-case, 3–64 chars), `description` (10–1000 chars), `content` (markdown, min 100 chars), `project`
+
+---
+
+## Users
+
+> See [examples/users.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/users.md) for full field reference and examples.
+
+```bash
+codemie sdk users me [--json]
+codemie sdk users data [--json]
+```
+
+---
+
+## Assistant Categories
+
+> See [examples/categories.md](${CLAUDE_PLUGIN_ROOT}/skills/codemie-sdk/examples/categories.md) for full field reference and examples.
+
+**Note:** Categories can only be used for assistants (set via the `categories` field on create/update).
+
+```bash
+codemie sdk assistant-categories list [--paginated] [--page <n>] [--per-page <n>] [--json]
+codemie sdk assistant-categories get <id> [--json]
+codemie sdk assistant-categories create --data '<json>' | --json <file>
+codemie sdk assistant-categories update <id> --data '<json>' | --json <file>
+codemie sdk assistant-categories delete <id>
+```
+
+**Required on create:** `name` (1–255 chars)
+

package/dist/agents/plugins/claude/plugin/skills/codemie-sdk/examples/assistants.md

@@ -0,0 +1,256 @@
+# Assistants Examples
+
+## List
+
+```bash
+# Basic list
+codemie sdk assistants list
+
+# Search by name
+codemie sdk assistants list --search 'Code Review'
+
+# Filter by project
+codemie sdk assistants list --projects MyProject
+
+# Marketplace assistants
+codemie sdk assistants list --scope marketplace
+
+# JSON output with pagination
+codemie sdk assistants list --page 0 --per-page 20 --json
+
+# Full assistant details in list
+codemie sdk assistants list --full-response --json
+```
+
+**JSON output fields (list):** `id`, `name`, `slug`, `type`, `description`, `shared`, `is_global`, `categories`, `created_by`
+
+## Get
+
+```bash
+codemie sdk assistants get bc1a4b75-955c-48a5-b26d-bf702c1fee5d
+codemie sdk assistants get bc1a4b75-955c-48a5-b26d-bf702c1fee5d --json
+```
+
+**Additional fields in get:** `project`, `llm_model_type`, `system_prompt`, `temperature`, `toolkits`, `skill_ids`
+
+## Create
+
+```bash
+# Minimal (required fields only)
+codemie sdk assistants create --data '{"name":"My Assistant","project":"MyProject","system_prompt":"You are a helpful assistant."}'
+
+# Full example from file
+codemie sdk assistants create --json assistant.json
+```
+
+**Field reference:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | ✅ | string | Display name of the assistant |
+| `project` | ✅ | string | Project to create the assistant in |
+| `system_prompt` | ✅ | string | Instruction text that defines the assistant's persona and behavior |
+| `description` | — | string | Short description shown in list and marketplace views |
+| `icon_url` | — | string | URL to an image used as the assistant's avatar |
+| `shared` | — | boolean | `true` = visible to all project members; `false` = private (default) |
+| `is_global` | — | boolean | `true` = available across all projects platform-wide |
+| `is_react` | — | boolean | Use ReAct (reasoning + acting) agent pattern; requires a model with `react_agent: true` |
+| `slug` | — | string | URL-friendly identifier for deep-linking to this assistant |
+| `llm_model_type` | — | string | Model `base_name` — if omitted, the platform default is used |
+| `temperature` | — | number | Sampling temperature 0.0–1.0; lower = more deterministic outputs |
+| `top_p` | — | number | Nucleus sampling 0.0–1.0; use either `temperature` or `top_p`, not both |
+| `conversation_starters` | — | string[] | Suggested prompts displayed to users as quick-start buttons |
+| `context` | — | array | Datasources attached as knowledge — see schema below |
+| `toolkits` | — | array | Integration toolkits (Git, Jira, etc.) — see schema below |
+| `mcp_servers` | — | array | MCP server connections for additional tools — see schema below |
+| `assistant_ids` | — | string[] | Sub-assistant IDs for orchestration (multi-agent workflows) |
+| `prompt_variables` | — | array | Dynamic `{{variable}}` placeholders in the system prompt — see schema below |
+| `categories` | — | string[] | Label IDs for marketplace classification (e.g. `["devops", "code-review"]`). You can manage assistants categories via codemie sdk assistant-categories command (get, create, update and so on). Only categories listed via this command can be used in this field |
+| `skill_ids` | — | string[] | Built-in platform skill IDs — **not** datasource IDs |
+| `skip_integration_validation` | — | boolean | Skip credential validation when attaching toolkits (useful with test credentials) |
+
+**Get available models:**
+```bash
+codemie sdk llm list --json | jq -r '.[] | "\(.base_name) (\(.label))"'
+```
+
+**`context` entry schema** — attach datasources:
+```json
+{ "id": "<datasource-id>", "context_type": "knowledge_base", "name": "<datasource-name>" }
+```
+Valid `context_type`: `"knowledge_base"` (file/confluence/jira/google), `"code"` (code repository).
+```bash
+# Get datasource IDs
+codemie sdk datasources list --projects MyProject --json | jq -r '.[] | "\(.id) \(.name)"'
+```
+
+**`toolkits` entry schema** — get the exact structure from the platform:
+```bash
+codemie sdk assistants get-tools --json
+```
+Then pick the desired toolkit object(s) and include them in your payload. Each entry looks like:
+```json
+{
+  "toolkit": "Jira",
+  "label": "Jira",
+  "settings_config": false,
+  "is_external": false,
+  "tools": [
+    { "name": "jira_get_issue", "settings_config": false },
+    { "name": "jira_search", "settings_config": false }
+  ]
+}
+```
+
+**`mcp_servers` entry schema:**
+```json
+{
+  "name": "my-mcp-server",
+  "description": "Custom tool server",
+  "enabled": true,
+  "config": {
+    "url": "https://mcp.example.com",
+    "auth_token": "<optional-token>",
+    "env": {}
+  },
+  "tools_tokens_size_limit": 4096
+}
+```
+
+**`assistant_ids`** — for multi-agent orchestration, reference other assistant IDs:
+```bash
+codemie sdk assistants list --projects MyProject --json | jq -r '.[] | "\(.id) \(.name)"'
+```
+
+**`prompt_variables` entry schema:**
+```json
+{ "key": "language", "description": "Programming language to focus on", "default_value": "TypeScript" }
+```
+Reference in system prompt as `{{language}}`.
+
+**Full `assistant.json` example:**
+```json
+{
+  "name": "Code Reviewer",
+  "project": "Engineering",
+  "description": "Reviews code for best practices and security",
+  "system_prompt": "You are a {{language}} code review assistant. Focus on {{focus_area}}.",
+  "shared": true,
+  "llm_model_type": "claude-3-7-sonnet",
+  "temperature": 0.3,
+  "conversation_starters": [
+    "Review my latest PR",
+    "Check this function for security issues"
+  ],
+  "context": [
+    { "id": "<datasource-id>", "context_type": "knowledge_base", "name": "Engineering Docs" }
+  ],
+  "toolkits": [
+    {
+      "toolkit": "Jira",
+      "label": "Jira",
+      "settings_config": false,
+      "is_external": false,
+      "tools": [
+        { "name": "jira_get_issue", "settings_config": false },
+        { "name": "jira_search", "settings_config": false }
+      ]
+    }
+  ],
+  "prompt_variables": [
+    { "key": "language", "description": "Primary language", "default_value": "TypeScript" },
+    { "key": "focus_area", "description": "Review focus", "default_value": "security and performance" }
+  ],
+  "categories": ["code-review", "engineering"]
+}
+```
+
+Output: `✓ Specified assistant saved` — **no ID is returned**. Find the new ID via:
+```bash
+codemie sdk assistants list --search 'My Assistant' --json | jq -r '.[0].id'
+```
+
+## Update
+
+```bash
+codemie sdk assistants update <id> --data '{"name":"Updated Name","shared":true}'
+codemie sdk assistants update <id> --json updates.json
+```
+
+## Delete
+
+```bash
+# Always verify before deleting
+codemie sdk assistants get <id>
+codemie sdk assistants delete <id>
+```
+
+## Linking a Datasource
+
+Datasources are attached via the `context` field — **not** `skill_ids`. Each entry requires `id`, `context_type`, and `name`.
+
+Valid `context_type` values: `"knowledge_base"` (file/confluence/jira datasources), `"code"` (code repository datasources).
+
+```bash
+# Get the datasource ID first
+codemie sdk datasources list --search 'my-docs' --json
+
+# Attach to assistant
+codemie sdk assistants update <id> --data '{
+  "context": [
+    {
+      "id": "<datasource-id>",
+      "context_type": "knowledge_base",
+      "name": "<datasource-name>"
+    }
+  ]
+}'
+```
+
+> **Note:** `skill_ids` holds built-in platform skills, not datasources. Do not use it to attach datasources.
+
+## Linking a Toolkit (Integration)
+
+Use the `toolkits` array to attach integrations (Git, Jira, etc.) to an assistant.
+
+Known toolkit names: `"Git"`, `"Jira"`, `"Confluence"`, `"Access Management"`, `"Codebase Tools"`, `"Project Management"`, `"Research"`.
+
+```bash
+# Attach Git toolkit
+codemie sdk assistants update <id> --data '{
+  "toolkits": [
+    {
+      "toolkit": "Git",
+      "label": "Git",
+      "settings_config": true,
+      "is_external": false,
+      "tools": [{ "name": "git_tools", "settings_config": false }]
+    }
+  ]
+}'
+```
+
+If the integration credentials can't be validated (test/fake credentials), add `"skip_integration_validation": true` at the top level:
+
+```bash
+codemie sdk assistants update <id> --data '{
+  "toolkits": [...],
+  "skip_integration_validation": true
+}'
+```
+
+## Scripting
+
+```bash
+# Create then immediately fetch the new ID
+codemie sdk assistants create --data '{"name":"My Bot","project":"Eng","system_prompt":"You are helpful."}'
+ID=$(codemie sdk assistants list --search 'My Bot' --json | jq -r '.[0].id')
+
+# Find assistant by name
+codemie sdk assistants list --search 'My Bot' --json | jq -r '.[].id'
+
+# Update all assistants in a project to shared
+codemie sdk assistants list --projects Engineering --json | jq -r '.[].id' | while read id; do
+  codemie sdk assistants update "$id" --data '{"shared":true}'
+done
+```

package/dist/agents/plugins/claude/plugin/skills/codemie-sdk/examples/categories.md

@@ -0,0 +1,101 @@
+# Categories Examples
+
+> **Note:** Categories can only be used for **assistants**. Set a category on an assistant via the `categories` field (array of category IDs) when creating or updating.
+
+## List
+
+```bash
+# List all categories (public, no admin required)
+codemie sdk assistant-categories list
+codemie sdk assistant-categories list --json
+
+# Paginated list with assistant counts (admin required)
+codemie sdk assistant-categories list --paginated
+codemie sdk assistant-categories list --paginated --page 0 --per-page 25 --json
+```
+
+**Non-paginated JSON fields:** `id`, `name`, `description`
+
+**Paginated JSON fields:** `categories[]` (with `id`, `name`, `description`, `marketplaceAssistantCount`, `projectAssistantCount`, `createdAt`, `updatedAt`), `page`, `per_page`, `total`, `pages`
+
+## Get
+
+```bash
+codemie sdk assistant-categories get <id>
+codemie sdk assistant-categories get <id> --json
+```
+
+Admin access required. Returns `id`, `name`, `description`, `marketplaceAssistantCount`, `projectAssistantCount`, `createdAt`, `updatedAt`.
+
+## Create
+
+```bash
+# Minimal (name only)
+codemie sdk assistant-categories create --data '{"name":"DevOps"}'
+
+# With description
+codemie sdk assistant-categories create --data '{"name":"Code Review","description":"Skills for reviewing code quality and security"}'
+
+# From file
+codemie sdk assistant-categories create --json category.json
+```
+
+**Field reference:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | ✅ | string | 1–255 chars |
+| `description` | — | string | Optional, max 1000 chars |
+
+Admin access required.
+
+## Update
+
+```bash
+codemie sdk assistant-categories update <id> --data '{"name":"Updated Name"}'
+codemie sdk assistant-categories update <id> --data '{"name":"DevOps","description":"Updated description"}'
+```
+
+Admin access required.
+
+## Delete
+
+```bash
+# Verify before deleting
+codemie sdk assistant-categories get <id>
+codemie sdk assistant-categories delete <id>
+```
+
+Admin access required. Fails with **409** if any assistants are still assigned to this category — reassign or remove those assistants first.
+
+## Using Categories with Assistants
+
+Categories are referenced by their `id` in the assistant `categories` field.
+
+```bash
+# Get available category IDs
+codemie sdk assistant-categories list --json | jq -r '.[] | "\(.id) \(.name)"'
+
+# Create an assistant with categories
+codemie sdk assistants create --data '{
+  "name": "Code Reviewer",
+  "project": "Engineering",
+  "system_prompt": "You are a code review assistant.",
+  "categories": ["<category-id-1>", "<category-id-2>"]
+}'
+
+# Update an assistant to add categories
+codemie sdk assistants update <assistant-id> --data '{
+  "categories": ["<category-id>"]
+}'
+```
+
+## Scripting
+
+```bash
+# Find category ID by name
+codemie sdk assistant-categories list --json | jq -r '.[] | select(.name == "DevOps") | .id'
+
+# List all categories with assistant counts (admin)
+codemie sdk assistant-categories list --paginated --json | jq -r '.categories[] | "\(.name): \(.marketplaceAssistantCount) marketplace, \(.projectAssistantCount) project"'
+```