comisai 1.0.4

package/node_modules/@comis/core/dist/tool-metadata.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool Metadata Registry
+ *
+ * Side-channel metadata store for tool definitions. The upstream AgentTool type
+ * cannot be extended, so per-tool metadata (result size caps, read-only flags,
+ * validators, etc.) is stored in a module-level Map keyed by tool name.
+ *
+ * Registry supports incremental registration via spread-merge semantics:
+ * different sources can register different fields for the same tool.
+ */
+/** Per-tool metadata stored in the side-channel registry. All fields optional. */
+export interface ComisToolMetadata {
+    /** Per-tool result size cap in characters. */
+    maxResultSizeChars?: number;
+    /** Tool does not mutate state -- safe for optimistic execution. */
+    isReadOnly?: boolean;
+    /** Safe for parallel execution with other concurrency-safe tools. */
+    isConcurrencySafe?: boolean;
+    /** BM25 keyword hints for deferred tool discovery. */
+    searchHint?: string;
+    /** JSON Schema describing tool output structure. */
+    outputSchema?: Record<string, unknown>;
+    /** Tool names that should be co-discovered whenever this tool is discovered (bidirectional). */
+    coDiscoverWith?: string[];
+    /** Pre-flight input validator. Returns error string on failure, undefined on success. */
+    validateInput?: (params: Record<string, unknown>) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * Register metadata for a tool. Merges with any existing metadata via spread,
+ * allowing incremental registration from different phases.
+ */
+export declare function registerToolMetadata(name: string, meta: ComisToolMetadata): void;
+/**
+ * Retrieve metadata for a tool by name.
+ * Returns undefined for unregistered tools (NOT an empty object).
+ */
+export declare function getToolMetadata(name: string): ComisToolMetadata | undefined;
+/**
+ * Returns the full registry as a ReadonlyMap for read-only iteration.
+ */
+export declare function getAllToolMetadata(): ReadonlyMap<string, ComisToolMetadata>;
+/**
+ * Clears the registry. Test-only -- underscore prefix signals internal use.
+ * Import directly from tool-metadata.ts in test files, NOT from index.ts.
+ */
+export declare function _clearRegistryForTest(): void;
+/** Content block shape matching the LLM tool-result format. */
+interface ContentBlock {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+/**
+ * Truncate text content blocks to fit within a character budget.
+ *
+ * - Returns the ORIGINAL array by reference when total chars <= maxChars
+ *   (critical for reference-equality checks in callers).
+ * - Applies proportional per-block budgets with a 500-char minimum.
+ * - Uses a 60/40 head/tail split with a marker indicating removed chars.
+ */
+export declare function truncateContentBlocks(content: ContentBlock[], maxChars: number): ContentBlock[];
+export {};

package/node_modules/@comis/core/dist/tool-metadata.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool Metadata Registry
+ *
+ * Side-channel metadata store for tool definitions. The upstream AgentTool type
+ * cannot be extended, so per-tool metadata (result size caps, read-only flags,
+ * validators, etc.) is stored in a module-level Map keyed by tool name.
+ *
+ * Registry supports incremental registration via spread-merge semantics:
+ * different sources can register different fields for the same tool.
+ */
+// ---------------------------------------------------------------------------
+// Registry (module-level singleton Map)
+// ---------------------------------------------------------------------------
+const registry = new Map();
+/**
+ * Register metadata for a tool. Merges with any existing metadata via spread,
+ * allowing incremental registration from different phases.
+ */
+export function registerToolMetadata(name, meta) {
+    registry.set(name, { ...registry.get(name), ...meta });
+}
+/**
+ * Retrieve metadata for a tool by name.
+ * Returns undefined for unregistered tools (NOT an empty object).
+ */
+export function getToolMetadata(name) {
+    return registry.get(name);
+}
+/**
+ * Returns the full registry as a ReadonlyMap for read-only iteration.
+ */
+export function getAllToolMetadata() {
+    return registry;
+}
+/**
+ * Clears the registry. Test-only -- underscore prefix signals internal use.
+ * Import directly from tool-metadata.ts in test files, NOT from index.ts.
+ */
+export function _clearRegistryForTest() {
+    registry.clear();
+}
+/** Minimum characters per block after truncation. */
+const MIN_CHARS_PER_BLOCK = 500;
+/**
+ * Truncate text content blocks to fit within a character budget.
+ *
+ * - Returns the ORIGINAL array by reference when total chars <= maxChars
+ *   (critical for reference-equality checks in callers).
+ * - Applies proportional per-block budgets with a 500-char minimum.
+ * - Uses a 60/40 head/tail split with a marker indicating removed chars.
+ */
+export function truncateContentBlocks(content, maxChars) {
+    // Step 1: Compute total text length across all blocks
+    let totalChars = 0;
+    for (const block of content) {
+        totalChars += block.text?.length ?? 0;
+    }
+    // Under or at budget -- return original array by reference
+    if (totalChars <= maxChars) {
+        return content;
+    }
+    // Step 2: Compute proportional ratio
+    const ratio = maxChars / totalChars;
+    // Step 3 & 4: Map each block, applying truncation to text blocks
+    return content.map((block) => {
+        // Skip non-text blocks or blocks without text
+        if (block.type !== "text" || !block.text) {
+            return block;
+        }
+        // Compute per-block budget with minimum floor
+        const budget = Math.max(MIN_CHARS_PER_BLOCK, Math.floor(block.text.length * ratio));
+        // Block fits within its budget -- return unchanged
+        if (block.text.length <= budget) {
+            return block;
+        }
+        // Apply 60/40 head/tail split
+        const head = Math.floor(budget * 0.6);
+        const tail = budget - head;
+        const removed = block.text.length - head - tail;
+        const marker = `\n[... ${removed} chars truncated. Reduce output scope (e.g., use limit param or narrower query). ...]\n`;
+        const text = block.text.slice(0, head) + marker + block.text.slice(-tail);
+        return { ...block, text };
+    });
+}

package/node_modules/@comis/core/dist/tool-metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@comis/core/dist/tool-metadata.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { registerToolMetadata, getToolMetadata, getAllToolMetadata, truncateContentBlocks, _clearRegistryForTest, } from "./tool-metadata.js";
+// ---------------------------------------------------------------------------
+// Registry tests
+// ---------------------------------------------------------------------------
+describe("tool metadata registry", () => {
+    it("getToolMetadata returns undefined for unregistered tool", () => {
+        expect(getToolMetadata("nonexistent_tool_xyz")).toBeUndefined();
+    });
+    it("registerToolMetadata stores and retrieves metadata", () => {
+        registerToolMetadata("reg_test_store", {
+            maxResultSizeChars: 5000,
+            isReadOnly: true,
+        });
+        const meta = getToolMetadata("reg_test_store");
+        expect(meta).toBeDefined();
+        expect(meta.maxResultSizeChars).toBe(5000);
+        expect(meta.isReadOnly).toBe(true);
+    });
+    it("registerToolMetadata merges metadata incrementally", () => {
+        registerToolMetadata("reg_test_merge", { isReadOnly: true });
+        registerToolMetadata("reg_test_merge", { maxResultSizeChars: 10000 });
+        const meta = getToolMetadata("reg_test_merge");
+        expect(meta).toEqual({ isReadOnly: true, maxResultSizeChars: 10000 });
+    });
+    it("registerToolMetadata overwrites fields on re-register", () => {
+        registerToolMetadata("reg_test_overwrite", { maxResultSizeChars: 5000 });
+        registerToolMetadata("reg_test_overwrite", { maxResultSizeChars: 10000 });
+        const meta = getToolMetadata("reg_test_overwrite");
+        expect(meta.maxResultSizeChars).toBe(10000);
+    });
+    it("getAllToolMetadata returns ReadonlyMap", () => {
+        registerToolMetadata("reg_test_all_a", { isReadOnly: true });
+        registerToolMetadata("reg_test_all_b", { maxResultSizeChars: 2000 });
+        const all = getAllToolMetadata();
+        expect(all.has("reg_test_all_a")).toBe(true);
+        expect(all.has("reg_test_all_b")).toBe(true);
+    });
+    it("_clearRegistryForTest clears all entries", () => {
+        registerToolMetadata("reg_test_clear", { isReadOnly: true });
+        expect(getToolMetadata("reg_test_clear")).toBeDefined();
+        _clearRegistryForTest();
+        expect(getToolMetadata("reg_test_clear")).toBeUndefined();
+        // Clean up (registry already clear, but be explicit)
+        _clearRegistryForTest();
+    });
+});
+// ---------------------------------------------------------------------------
+// Truncation tests
+// ---------------------------------------------------------------------------
+describe("truncateContentBlocks", () => {
+    it("returns original array when total chars under budget", () => {
+        const content = [{ type: "text", text: "x".repeat(100) }];
+        const result = truncateContentBlocks(content, 200);
+        expect(result).toBe(content); // Same reference
+    });
+    it("returns original array when total chars equal to budget", () => {
+        const content = [{ type: "text", text: "x".repeat(100) }];
+        const result = truncateContentBlocks(content, 100);
+        expect(result).toBe(content); // Same reference
+    });
+    it("truncates text blocks proportionally with 60/40 split", () => {
+        const content = [{ type: "text", text: "x".repeat(10000) }];
+        const result = truncateContentBlocks(content, 2000);
+        expect(result[0].text).toContain("chars truncated");
+        // Verify the truncated text has head (60%) + marker + tail (40%) structure
+        const text = result[0].text;
+        const markerIdx = text.indexOf("\n[...");
+        expect(markerIdx).toBeGreaterThan(0);
+        // Head should be roughly 60% of budget (2000 * 0.6 = 1200)
+        expect(markerIdx).toBeGreaterThanOrEqual(1100);
+        expect(markerIdx).toBeLessThanOrEqual(1300);
+    });
+    it("preserves non-text blocks unchanged", () => {
+        const imageBlock = { type: "image", url: "https://example.com/img.png" };
+        const textBlock = { type: "text", text: "x".repeat(5000) };
+        const content = [imageBlock, textBlock];
+        const result = truncateContentBlocks(content, 1000);
+        // Image block should be the exact same object reference
+        expect(result[0]).toBe(imageBlock);
+        // Text block should be truncated
+        expect(result[1].text).toContain("chars truncated");
+    });
+    it("enforces 500-char minimum per block", () => {
+        const content = [
+            { type: "text", text: "x".repeat(8000) },
+            { type: "text", text: "y".repeat(200) },
+        ];
+        const result = truncateContentBlocks(content, 100);
+        // The small block (200 chars) gets minimum budget of 500, which is > its length
+        // so it should NOT be truncated (200 < 500 min budget)
+        expect(result[1].text).toBe("y".repeat(200));
+    });
+    it("marker text includes char count and guidance", () => {
+        const content = [{ type: "text", text: "x".repeat(10000) }];
+        const result = truncateContentBlocks(content, 2000);
+        const text = result[0].text;
+        expect(text).toContain("chars truncated");
+        expect(text).toContain("Reduce output scope");
+    });
+    it("handles empty content array", () => {
+        const content = [];
+        const result = truncateContentBlocks(content, 1000);
+        expect(result).toBe(content); // Same reference
+    });
+    it("handles blocks with no text field", () => {
+        const content = [{ type: "text" }]; // no text property
+        const result = truncateContentBlocks(content, 100);
+        // Total chars is 0 (no text), 0 <= 100, returns original
+        expect(result).toBe(content);
+    });
+});

package/node_modules/@comis/core/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@comis/core",
+  "private": true,
+  "version": "1.0.4",
+  "author": "Moshe Anconina",
+  "license": "Apache-2.0",
+  "description": "Core domain types, ports, event bus, security, and config for Comis",
+  "keywords": [
+    "comis",
+    "ai",
+    "agent",
+    "core",
+    "hexagonal",
+    "ports"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comisai/comis.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/comisai/comis#readme",
+  "bugs": {
+    "url": "https://github.com/comisai/comis/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}

package/node_modules/@comis/daemon/bundled-skills/skill-creator/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: skill-creator
+version: "1.1.1"
+description: Create new Comis skills, modify and improve existing skills, and validate them against the platform's manifest schema. Use this skill whenever the user wants to create a skill from scratch, turn a workflow into a reusable skill, update or fix an existing skill, understand the skill format, or asks about how skills work in Comis -- even if they don't use the word "skill" explicitly.
+---
+
+# Skill Creator
+
+Create, validate, and iterate on Comis prompt skills.
+
+## How Skills Work
+
+Skills are Markdown instruction files that extend what the agent can do. When a user sends a message, the agent scans available skill descriptions and, if one matches, reads its SKILL.md and follows the instructions step by step. Skills are the primary way to teach the agent new capabilities without changing code.
+
+Skills are hot-reloaded -- save a file and it's available immediately, no restart needed.
+
+## Core Principles
+
+### The context window is a public good
+
+Skills share the context window with the system prompt, conversation history, other skills' metadata, and the user's request. Challenge each piece of information: "Does the agent really need this?" and "Does this paragraph justify its token cost?" Default assumption: the agent is already very smart -- only add context it doesn't already have. Prefer concise examples over verbose explanations.
+
+### Set appropriate degrees of freedom
+
+Match the level of specificity to the task's fragility:
+
+- **High freedom** (text-based instructions): Multiple approaches are valid, decisions depend on context. Like an open field -- many routes work.
+- **Medium freedom** (pseudocode or parameterized scripts): A preferred pattern exists but some variation is acceptable.
+- **Low freedom** (specific scripts, exact sequences): Operations are fragile, consistency is critical. Like a narrow bridge -- guardrails needed.
+
+### What NOT to include
+
+A skill should only contain files that directly support its function. Do not create:
+- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or any auxiliary documentation
+- User-facing docs about the process that went into creating the skill
+- Setup/testing procedures (those belong in the iteration loop, not the skill)
+
+## Private vs Shared Skills
+
+Skills can live in two places. **Default to private** unless the user explicitly asks for a shared skill.
+
+### Private skills (default)
+
+Created in the agent's own workspace under `skills/`.
+
+Workspace paths follow the pattern `~/.comis/workspace-<agent-id>/` (e.g., `~/.comis/workspace-ta-trader/` for the `ta-trader` agent). The default agent's workspace is simply `~/.comis/workspace/`. Your workspace path is shown in the "Workspace" section of your system prompt -- use it directly, don't guess.
+
+Create private skills at: `<your-workspace>/skills/<skill-name>/SKILL.md`
+
+- Full read/write access -- create, edit, and delete freely
+- Visible only to this agent (and its sub-agents who share the workspace)
+- Take priority over shared skills with the same name
+
+### Shared skills
+
+Created at `~/.comis/skills/`. Visible to all agents on the platform.
+
+- Use the absolute path `~/.comis/skills/<skill-name>/`
+- Only when explicitly requested ("make this available to all agents", "create a shared skill")
+
+## Creating a Skill
+
+**Before creating**, check if a skill with the same or similar name already exists:
+- `ls <workspace>/skills/` -- check the agent's private skills
+- `ls ~/.comis/skills/` -- check shared skills
+
+Two calls maximum. If a match is found, confirm with the user whether to modify the existing skill or create a new one.
+
+### Routing: simple vs complex
+
+**Simple skill** (no scripts, references, or assets -- most skills):
+1. Write `<workspace>/skills/<name>/SKILL.md` directly (the write tool creates parent dirs)
+2. Validate → suggest test prompt → done
+
+**Complex skill** (needs bundled scripts, reference docs, or asset files):
+Follow Steps 1-8 below.
+
+### Step 1: Understand intent
+
+You MUST ask at least one clarifying question unless the user's request already specifies ALL of: (1) the specific capability, (2) the tools or data sources, and (3) the expected output format.
+
+Four dimensions to clarify:
+
+1. What should this skill enable the agent to do?
+2. When should it trigger? (what user phrases, contexts, or tasks)
+3. What tools does the agent need? (file ops, exec, web search, memory, messaging)
+4. What's the expected output format or behavior?
+
+If the conversation already contains a workflow the user wants to capture ("turn this into a skill"), extract the steps, tools used, and corrections from the conversation history. Confirm before proceeding.
+
+Do NOT proceed to Step 2 until intent is clear on all four dimensions.
+
+### Step 2: Verify tools
+
+If the skill will reference specific tools (MCP servers, platform tools, or deferred tools), call `discover_tools` to load their schemas before writing any instructions.
+
+- Confirm parameter names, required fields, and return formats match what the skill instructions will reference
+- Do NOT assume tool capabilities from deferred-tool names alone -- always check the schema
+- If a tool is unavailable or its schema differs from expectations, flag this to the user before proceeding
+
+Skip this step if the skill uses only general-purpose capabilities (text generation, reasoning) with no specific tool references.
+
+### Step 3: Plan reusable resources
+
+Before writing, analyze the concrete examples to identify what should be bundled:
+
+- Will the same code be written on every invocation? → `scripts/`
+- Is there reference material the agent needs but only sometimes? → `references/`
+- Are there templates or files used in the output? → `assets/`
+
+### Step 4: Initialize resource directories (if needed)
+
+Skip this step for simple skills -- the write tool creates the skill directory automatically. Only run the init script when the skill needs `scripts/`, `references/`, or `assets/` directories:
+
+```
+python3 scripts/init-skill.py <skill-name> --path <workspace>/skills --resources scripts,references
+python3 scripts/init-skill.py <skill-name> --path <workspace>/skills --description "What it does and when to use it"
+```
+
+This creates the directory with a templated SKILL.md. If `--description` is provided, the template uses it directly instead of a TODO placeholder. Use the **absolute path** to `scripts/init-skill.py` from this skill-creator's directory (do NOT set `cwd` to this directory -- the exec tool will reject it as outside workspace bounds).
+
+For shared skills: `python3 scripts/init-skill.py <skill-name> --path ~/.comis/skills`
+
+### Step 5: Edit the SKILL.md
+
+#### Frontmatter
+
+Two fields are required -- `name` and `description`. Everything else is optional.
+
+```yaml
+---
+name: my-skill-name
+description: What this skill does and when to use it. Be specific and slightly pushy.
+---
+```
+
+**Name rules:** lowercase alphanumeric + hyphens, 1-64 chars, no consecutive/leading/trailing hyphens.
+
+**Description guidance:** This is the primary trigger mechanism. The agent decides whether to use a skill based on this field alone. All "when to use" info goes here -- not in the body (the body is only loaded after triggering).
+
+Bad: `"Dashboard builder."`
+Good: `"Build data visualization dashboards with charts, tables, and filters. Use whenever the user mentions dashboards, data visualization, metrics display, or chart creation -- even if they don't explicitly ask for a 'dashboard'."`
+
+Only two fields are required: `name` and `description`. For advanced fields (comis namespace, permissions, allowedTools, inputSchema), read `references/schema.md` in this skill's directory.
+
+#### Body structure
+
+Choose the pattern that fits the skill's purpose:
+
+**Workflow-based** -- for sequential processes:
+```
+## Overview → ## Decision Tree → ## Step 1 → ## Step 2 ...
+```
+
+**Task-based** -- for tool collections with different operations:
+```
+## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2 ...
+```
+
+**Reference/guidelines** -- for standards or specifications:
+```
+## Overview → ## Guidelines → ## Specifications → ## Usage ...
+```
+
+**Capabilities-based** -- for integrated systems:
+```
+## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature ...
+```
+
+Patterns can be mixed as needed.
+
+### Complete example
+
+A minimal working skill:
+
+~~~
+---
+name: commit-message
+description: Write conventional commit messages from staged changes. Use whenever the user asks to commit, write a commit message, or says "commit this" -- even if they don't mention conventional commits.
+---
+
+# Commit Message
+
+Generate a conventional commit message from the current staged diff.
+
+## Steps
+
+1. Run `git diff --cached` to see staged changes
+2. Analyze the diff: what changed, why, which components
+3. Write a message following conventional commits format: `type(scope): description`
+   - `feat` for new features, `fix` for bugs, `refactor` for restructuring, `docs` for documentation
+   - scope = package or component name
+   - description = imperative mood, lowercase, no period
+4. Present the message and wait for approval before committing
+~~~
+
+This skill needs no scripts, references, or assets -- just the SKILL.md file.
+
+#### Body writing principles
+
+1. **Explain the why.** The model handles edge cases better when it understands reasoning. Instead of "ALWAYS use format X", explain why format X matters.
+
+2. **Use imperative form.** "Read the config file" not "You should read the config file".
+
+3. **Progressive disclosure.** Keep SKILL.md body under 500 lines. Move detailed reference material to `references/` files -- keep only core workflow in the body. When splitting content, clearly reference the files and describe when to read them.
+
+4. **Bundle repeated work as scripts.** If the same helper code would be written every time, put it in `scripts/`. Scripts execute without loading into context -- saves tokens and ensures consistency.
+
+5. **Avoid duplication.** Information should live in SKILL.md or reference files, not both.
+
+6. **Include examples.** Concise examples over verbose explanations:
+```
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+#### Progressive disclosure patterns
+
+**Pattern 1: High-level guide with references**
+```markdown
+## Quick start
+Extract text with pdfplumber: [code example]
+
+## Advanced features
+- **Form filling**: See references/forms.md for complete guide
+- **API reference**: See references/api.md for all methods
+```
+
+**Pattern 2: Domain-specific organization**
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── references/
+    ├── finance.md
+    ├── sales.md
+    └── product.md
+```
+When the user asks about sales, the agent only reads `sales.md`.
+
+**Guidelines:**
+- Keep references one level deep from SKILL.md -- avoid nested references
+- For reference files over 100 lines, include a table of contents at the top
+- If a reference file is very large (>10k words), include grep search patterns in SKILL.md so the agent can find what it needs efficiently
+
+#### Body constraints
+
+- Maximum 20,000 characters (truncated with [TRUNCATED] at load time)
+- Aim for under 500 lines
+- No shell injection patterns (see content scanning rules in `references/schema.md`)
+
+### Step 6: Validate
+
+Run the validation script:
+
+```
+python3 scripts/validate-skill.py <path-to-skill-dir>
+```
+
+Use the **absolute path** to `scripts/validate-skill.py` from this skill-creator's directory (same rule -- no `cwd` override).
+
+This checks: frontmatter fields and types, name format, description length, body size, content scanning patterns, and unreferenced bundled scripts.
+
+Fix any errors, then save -- the skill watcher hot-reloads automatically.
+
+### Step 7: Hand off to the user
+
+Tell the user the skill is ready and suggest a sample prompt they can send to test it. Do NOT run the test yourself or spawn a sub-agent to test -- testing is the user's job. Example:
+
+> Your **{skill-name}** skill is live. Try sending: "{a natural prompt that would trigger it}."
+
+If the user later reports the skill didn't trigger, the description needs to be more specific or "pushy".
+
+### Step 8: Iterate
+
+1. **Generalize from feedback.** Don't overfit to test cases. If there's a stubborn issue, try different metaphors or patterns.
+2. **Keep it lean.** Remove instructions that aren't pulling their weight. Read transcripts -- if the agent wastes time on unproductive steps, trim the parts causing that.
+3. **Test bundled scripts.** Run scripts to verify they work. If there are many similar scripts, test a representative sample.
+
+## Modifying an Existing Skill
+
+1. Read the current SKILL.md to understand what it does
+2. Ask what's not working or what should change
+3. Make targeted edits -- don't rewrite from scratch unless the structure is fundamentally wrong
+4. Validate with the script
+5. Test the change
+
+## Bundled Resources
+
+### scripts/
+Executable code for deterministic, repeatable tasks. Signs you need a script:
+- The same code would be written on every invocation
+- Parsing, transforming, or validating data in a predictable way
+- Consistency across invocations is important
+
+Scripts can execute without loading into context (saves tokens). Only Python 3 stdlib is guaranteed. Scripts may still need to be read by the agent for patching or environment-specific adjustments.
+
+### references/
+Documentation loaded into context as needed. Signs you need a reference:
+- Information is important but not needed every time
+- Body is getting too long
+- Multiple domains or frameworks need separate docs
+
+### assets/
+Files used in the output the agent produces (templates, images, fonts, boilerplate). Not loaded into context -- copied or referenced in the final output.
+
+## Platform Features
+
+For advanced frontmatter fields (comis namespace, permissions, allowedTools, model visibility), read `references/schema.md`. Not needed for simple skills using only `name` and `description`.
+
+## Checklist
+
+Before considering a skill done:
+
+- [ ] Name follows format rules (lowercase, hyphens, 1-64 chars)
+- [ ] Description is specific, includes trigger phrases, and all "when to use" info
+- [ ] Body is under 500 lines (references/ for overflow)
+- [ ] No content scanning violations (run validate script)
+- [ ] Bundled scripts are referenced in the body and tested
+- [ ] No extraneous files (README, CHANGELOG, etc.)
+- [ ] Suggested a test prompt to the user