contextos-agents 1.5.0 → 1.6.1

package/.agents/validate.js

@@ -414,6 +414,58 @@ function checkValidationJson(sourceSkills) {
   info(`[validation] ${pass} VALIDATION.json files are valid`);
 }
 
+// ═════════════════════════════════════════════════════════════════════════════
+//  CHECK 9 — MCP Bundle Synchronization
+// ═════════════════════════════════════════════════════════════════════════════
+function checkMcpBundleSync() {
+  const mcpSrcDir = path.join(ROOT, 'contextos-mcp', 'src');
+  const bundlePath = path.join(AGENTS_DIR, 'mcp', 'server.mjs');
+
+  if (!fs.existsSync(mcpSrcDir)) {
+    return;
+  }
+
+  if (!fs.existsSync(bundlePath)) {
+    warn(`[mcp-sync] Missing compiled MCP server bundle at .agents/mcp/server.mjs. Run: cd contextos-mcp && npm run build:bundle`);
+    return;
+  }
+
+  const bundleStat = fs.statSync(bundlePath);
+  const bundleMtime = bundleStat.mtimeMs;
+
+  let newestSrcFile = null;
+  let newestSrcMtime = 0;
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        const stat = fs.statSync(full);
+        if (stat.mtimeMs > newestSrcMtime) {
+          newestSrcMtime = stat.mtimeMs;
+          newestSrcFile = path.relative(ROOT, full);
+        }
+      }
+    }
+  }
+
+  walk(mcpSrcDir);
+
+  if (newestSrcMtime > bundleMtime) {
+    warn(`[mcp-sync] Compiled MCP bundle (.agents/mcp/server.mjs) is older than source file ${newestSrcFile}. Run: cd contextos-mcp && npm run build:bundle`);
+  } else {
+    info(`[mcp-sync] Compiled MCP bundle (.agents/mcp/server.mjs) is up to date with contextos-mcp/src/`);
+  }
+}
+
 // ═════════════════════════════════════════════════════════════════════════════
 //  REPORT
 // ═════════════════════════════════════════════════════════════════════════════
@@ -487,6 +539,7 @@ function run() {
   checkContentQuality(sourceSkills);
   checkCostarHeaders(sourceSkills);
   checkValidationJson(sourceSkills);
+  checkMcpBundleSync();
 
   const passed = printReport();
   process.exit(passed ? 0 : 1);

package/.agents/watch.js

@@ -0,0 +1,161 @@
+/**
+ * .agents/watch.js
+ * ContextOS — Continuous Context Sync & File Watcher Daemon
+ *
+ * Watches:
+ *   1. .agents/core/skills/ — regenerates agent configs on skill markdown edits
+ *   2. package.json & manifests — detects tech stack drift and recommends profile adjustments
+ *
+ * Provides instant feedback during local development without manual re-exports.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const profiles = require('./profiles.js');
+
+/**
+ * Runs the ContextOS watch daemon.
+ *
+ * @param {string} [projectDir=process.cwd()] - Target project directory
+ * @param {Object} [options={}] - Watcher configuration options
+ * @param {number} [options.debounceMs=300] - Debounce delay in milliseconds
+ * @param {Function} [options.onSync] - Callback after a sync event completes
+ * @param {boolean} [options.exitOnSigint=true] - Whether to register process exit handlers
+ * @returns {Object} Controller object with a `close()` method
+ */
+function runWatch(projectDir = process.cwd(), options = {}) {
+  const debounceMs = options.debounceMs || 300;
+  const agentsDir = path.join(projectDir, '.agents');
+  const skillsDir = path.join(agentsDir, 'core', 'skills');
+  const ctxPath = path.join(agentsDir, 'ctx.js');
+
+  console.log('\n[ContextOS Watch] Initializing background continuous sync daemon...');
+  console.log(`[ContextOS Watch] Project directory: ${projectDir}`);
+
+  let lastStack = profiles.detectStack(projectDir);
+  console.log(`[ContextOS Watch] Initial stack: ${lastStack.detected.join(', ') || 'Generic JS'} (${lastStack.recommendedProfile})`);
+
+  let debounceTimer = null;
+  let isSyncing = false;
+  const watchers = [];
+
+  function triggerRecompile(sourceReason) {
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    debounceTimer = setTimeout(() => {
+      if (isSyncing) return;
+      isSyncing = true;
+
+      try {
+        const time = new Date().toLocaleTimeString();
+        console.log(`[${time}] [SYNC] Changes detected in ${sourceReason}. Recompiling agent skills...`);
+
+        if (fs.existsSync(ctxPath)) {
+          execFileSync(process.execPath, [ctxPath, 'export', 'all'], {
+            cwd: projectDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+          console.log(`[${time}] [OK] Skills exported to all agents (Gemini, Claude, Cursor, Copilot, Aider, Zed).`);
+        }
+
+        if (typeof options.onSync === 'function') {
+          options.onSync({ type: 'recompile', reason: sourceReason });
+        }
+      } catch (err) {
+        console.error(`[WARN] Auto-recompile failed: ${err.message}`);
+      } finally {
+        isSyncing = false;
+      }
+    }, debounceMs);
+  }
+
+  function checkStackChange() {
+    try {
+      const currentStack = profiles.detectStack(projectDir);
+      const prevStr = lastStack.detected.sort().join(',');
+      const currStr = currentStack.detected.sort().join(',');
+
+      if (prevStr !== currStr) {
+        const time = new Date().toLocaleTimeString();
+        console.log(`\n[${time}] [DETECT] Project dependencies changed!`);
+        console.log(`       Detected stack : ${currentStack.detected.join(', ')}`);
+        console.log(`       Recommendation : Profile '${currentStack.recommendedProfile}'`);
+        console.log(`       Run: contextos profile apply ${currentStack.recommendedProfile}\n`);
+        lastStack = currentStack;
+
+        if (typeof options.onSync === 'function') {
+          options.onSync({ type: 'stack_change', stack: currentStack });
+        }
+      }
+    } catch {
+      // ignore transient filesystem read errors
+    }
+  }
+
+  // 1. Watch .agents/core/skills/ directory
+  if (fs.existsSync(skillsDir)) {
+    try {
+      const skillsWatcher = fs.watch(skillsDir, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        const norm = filename.replace(/\\/g, '/');
+        if (norm.endsWith('.md') || norm.endsWith('.json') || norm.endsWith('.yaml') || norm.endsWith('.yml')) {
+          triggerRecompile(`skills/${filename}`);
+        }
+      });
+      watchers.push(skillsWatcher);
+    } catch (e) {
+      console.warn(`[WARN] Could not establish recursive watcher on skills directory: ${e.message}`);
+    }
+  }
+
+  // 2. Watch package.json
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkgWatcher = fs.watch(pkgPath, () => {
+        checkStackChange();
+      });
+      watchers.push(pkgWatcher);
+    } catch (e) {
+      console.warn(`[WARN] Could not watch package.json: ${e.message}`);
+    }
+  }
+
+  console.log('[ContextOS Watch] Watching for skill updates and dependency shifts. Press Ctrl+C to stop.\n');
+
+  function close() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) {
+      try {
+        w.close();
+      } catch {}
+    }
+  }
+
+  if (options.exitOnSigint !== false) {
+    const onExit = () => {
+      console.log('\n[ContextOS Watch] Stopping watcher daemon.');
+      close();
+      process.exit(0);
+    };
+    process.once('SIGINT', onExit);
+    process.once('SIGTERM', onExit);
+  }
+
+  return {
+    close,
+    triggerRecompile,
+    checkStackChange,
+  };
+}
+
+if (require.main === module) {
+  runWatch();
+}
+
+module.exports = {
+  runWatch,
+};

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/contextos-agents.svg)](https://www.npmjs.com/package/contextos-agents)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D16.7.0-brightgreen.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#testing)
 
 This is an open-source set of skills and behavioral rules for AI assistants. The package automatically installs an `.agents` folder into your project, teaching your AI assistant software development best practices (UI Design, Architecture, Security, and more).
@@ -12,7 +12,8 @@ This is an open-source set of skills and behavioral rules for AI assistants. The
 You do not need to clone anything manually. Just open your terminal in the root of your project and run:
 
 ```bash
-npx contextos-agents
+npx contextos
+# or: npx contextos-agents
 ```
 
 The script will automatically detect your project tech stack, create the `.agents` folder, configure skills, and compile them for your AI agent.
@@ -20,15 +21,16 @@ The script will automatically detect your project tech stack, create the `.agent
 ### Options
 
 ```bash
-npx contextos-agents --help          # Show all options
-npx contextos-agents --version       # Show version
-npx contextos-agents --profile mvp   # Install with specific profile (mvp, startup, enterprise, frontend, backend)
-npx contextos-agents --auto          # Auto-detect tech stack and apply recommended profile
-npx contextos-agents --with-mcp      # Install with MCP execution server enabled (.agents/mcp/)
-npx contextos-agents setup-mcp       # Add MCP server to an existing .agents/ project
-npx contextos-agents --dry-run       # Preview what will be installed
-npx contextos-agents --force         # Overwrite an existing .agents/ folder
-npx contextos-agents --skip-compile  # Skip auto-compilation step
+npx contextos --help             # Show all options
+npx contextos --version          # Show version
+npx contextos --minimal          # Install only 5 core skills (lightweight footprint)
+npx contextos --profile mvp      # Install with specific profile (mvp, startup, enterprise, frontend, backend)
+npx contextos --auto             # Auto-detect tech stack and apply recommended profile
+npx contextos --with-mcp         # Install with MCP execution server enabled (.agents/mcp/)
+npx contextos setup-mcp          # Add MCP server to an existing .agents/ project
+npx contextos --dry-run          # Preview what will be installed
+npx contextos --force            # Overwrite an existing .agents/ folder
+npx contextos --skip-compile     # Skip auto-compilation step
 ```
 
 ## Why ContextOS?
@@ -49,10 +51,10 @@ Most AI coding assistants suffer from two extremes: they either operate in a vac
 
 ### Key Developer Advantages
 
-- 🚀 **Zero-Config Onboarding:** Run `npx contextos-agents` in your repository. It auto-detects your stack (React, Node, Python, etc.) and sets up the ideal profile in seconds.
-- 🎯 **Tailored Project Profiles:** Use `mvp` for lean, rapid prototyping without bloated microservices boilerplate, or `enterprise` for strict TDD, DDD, and security auditing.
-- 🛡️ **Autonomous Multi-Agent Worktrees:** Run parallel tasks safely with the bundled MCP server—subagents work in isolated Git worktrees without corrupting your active workspace.
-- 📊 **Verifiable Benchmarks:** Backed by reproducible side-by-side benchmarks demonstrating measurable code quality improvements and reduced token usage.
+- **Zero-Config Onboarding:** Run `npx contextos-agents` in your repository. It auto-detects your stack (React, Node, Python, etc.) and sets up the ideal profile in seconds.
+- **Tailored Project Profiles:** Use `mvp` for lean, rapid prototyping without bloated microservices boilerplate, or `enterprise` for strict TDD, DDD, and security auditing.
+- **Autonomous Multi-Agent Worktrees:** Run parallel tasks safely with the bundled MCP server—subagents work in isolated Git worktrees without corrupting your active workspace.
+- **Verifiable Benchmarks:** Backed by reproducible side-by-side benchmarks demonstrating measurable code quality improvements and reduced token usage.
 
 ## Project Profiles & Stack Auto-Detection
 
@@ -70,16 +72,17 @@ ContextOS allows you to tailor your AI rules to the project lifecycle and archit
 
 ```bash
 # Auto-detect tech stack in the current project
-node .agents/ctx.js detect
+contextos detect
+# or: node .agents/ctx.js detect
 
 # List available profiles and current active profile
-node .agents/ctx.js profile list
+contextos profile list
 
 # Apply a profile
-node .agents/ctx.js profile apply mvp
+contextos profile apply mvp
 
 # Recompile all agent exports for the active profile
-node .agents/ctx.js export all
+contextos export all
 ```
 
 ## What's Inside?
@@ -146,9 +149,9 @@ ContextOS maps development phases directly to slash commands in your AI chat:
 | `/review` | Staff Engineer + Designer | 5-axis quality gate (correctness, architecture, security, performance, design) |
 | `/ship` | Release Engineer | Verify clean CI, lint checks, docs, and rollback plan before merging |
 
-## Dynamic Skill Resolution & CLI (`ctx.js`)
+## Dynamic Skill Resolution & Unified CLI (`contextos` / `ctx.js`)
 
-The `.agents/ctx.js` file is the **Context Engine** — it resolves minimal skills on the fly and compiles exports for AI assistants.
+ContextOS provides a unified CLI (`contextos` or `npx contextos`) and local engine (`.agents/ctx.js`) to resolve minimal skills on the fly, run health diagnostics, and compile exports for AI assistants.
 
 ### Dynamic Skill Resolution (`resolve` & `index`)
 
@@ -156,48 +159,74 @@ To prevent context bloat, ContextOS dynamically resolves the exact 2–4 skills
 
 ```bash
 # Resolve skills for a task description (English):
-node .agents/ctx.js resolve "Build an accessible modal component with React and Tailwind"
+contextos resolve "Build an accessible modal component with React and Tailwind"
 
 # Output:
 # [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
 # Skills loaded: ponytail-mindset, engineering-workflow, react, ui-ux-pro, web-accessibility
 
 # Multilingual support (Russian):
-node .agents/ctx.js resolve "создай модальное окно авторизации и напиши юнит-тесты"
+contextos resolve "создай модальное окно авторизации и напиши юнит-тесты"
 
 # Output:
 # [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
 # Skills loaded: ponytail-mindset, engineering-workflow, react, ui-ux-pro, security, testing
 
-# Resolve skills based on active files:
-node .agents/ctx.js resolve --files "app/api/auth/route.ts"
+# Resolve skills based on active files (hybrid AST & config analysis):
+contextos resolve --files "app/api/auth/route.ts"
 
 # Generate/update progressive lightweight skills index:
-node .agents/ctx.js index
+contextos index
 
 # Clean up lingering .swarm-worktrees directories and orphaned swarm/* git branches:
-node .agents/ctx.js clean-worktrees
+contextos clean-worktrees
+```
+
+### Diagnostic Health Check (`contextos doctor`)
+
+Run a comprehensive pre-flight verification across your repository to ensure valid skills, profile alignment, symlinks, git worktree status, and compiler synchronization:
+
+```bash
+contextos doctor
+# or: npx contextos doctor
+```
+
+### Context Savings Analytics (`contextos stats`)
+
+Measure your real token savings. Compares monolithic prompt injection against ContextOS dynamic skill resolution across frontend, backend, security, and full-stack tasks:
+
+```bash
+contextos stats
+```
+
+### Continuous Auto-Sync Daemon (`contextos watch`)
+
+Watch your source skills in `.agents/core/skills/` and automatically recompile adapter outputs (`.cursorrules`, `.zed/rules.md`, `.github/copilot-instructions.md`, etc.) upon saving:
+
+```bash
+contextos watch
+# or: npm run watch
 ```
 
 ### Supported Agents & Compilation
 
 | Agent | Command | Output Format |
 |-------|---------|---------------|
-| **Gemini / Antigravity** | `export gemini` | `.agents/generated/gemini/skills/` |
-| **Claude Code** | `export claude` | `.agents/generated/claude/skills/` |
-| **Cursor IDE** | `export cursor` | `.cursor/rules/*.mdc` (modular globs) + `.cursorrules` |
-| **GitHub Copilot** | `export copilot` | `.github/copilot-instructions.md` |
-| **Aider** | `export aider` | `.aider.conf.yml` + `CONVENTIONS.md` |
-| **Zed IDE** | `export zed` | `.zed/rules.md` + `.zed/prompts/*.md` |
+| **Gemini / Antigravity** | `contextos export gemini` | `.agents/generated/gemini/skills/` |
+| **Claude Code** | `contextos export claude` | `.agents/generated/claude/skills/` |
+| **Cursor IDE** | `contextos export cursor` | `.cursor/rules/*.mdc` (modular globs) + `.cursorrules` |
+| **GitHub Copilot** | `contextos export copilot` | `.github/copilot-instructions.md` |
+| **Aider** | `contextos export aider` | `.aider.conf.yml` + `CONVENTIONS.md` |
+| **Zed IDE** | `contextos export zed` | `.zed/rules.md` + `.zed/prompts/*.md` |
 
 ```bash
-node .agents/ctx.js export all       # Compile for all agents
-node .agents/ctx.js export gemini    # Compile for Gemini / Antigravity
-node .agents/ctx.js export claude    # Compile for Claude Code
-node .agents/ctx.js export cursor    # Compile for Cursor (.cursor/rules/*.mdc)
-node .agents/ctx.js export copilot   # Compile for GitHub Copilot
-node .agents/ctx.js export aider     # Compile for Aider
-node .agents/ctx.js export zed       # Compile for Zed IDE
+contextos export all       # Compile for all agents (or: node .agents/ctx.js export all)
+contextos export gemini    # Compile for Gemini / Antigravity
+contextos export claude    # Compile for Claude Code
+contextos export cursor    # Compile for Cursor (.cursor/rules/*.mdc)
+contextos export copilot   # Compile for GitHub Copilot
+contextos export aider     # Compile for Aider
+contextos export zed       # Compile for Zed IDE
 ```
 
 ### Pre-Compiled Artifacts & Git Architecture
@@ -209,19 +238,46 @@ ContextOS commits generated adapter configurations (`.cursorrules`, `.cursor/rul
 - **Automated Sync & Drift Prevention:** CI strictly validates that generated exports match source skills (`node .agents/ctx.js validate`). Any uncommitted adapter drift fails CI checks via `git diff --exit-code`.
 - **Contributor Workflow:** Source rules are authored exclusively in `.agents/core/skills/<name>/SKILL.md`. Running `node .agents/ctx.js export all` regenerates all assistant configurations deterministically.
 
+### CI Quality Gate Action (`contextos-gate`)
+
+You can guard your repository against skill drift, secret leaks, and rule regressions using the official reusable GitHub Composite Action:
+
+```yaml
+# .github/workflows/pr-gate.yml
+name: ContextOS Quality Gate
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@main
+        with:
+          node-version: '20'
+```
+
+The action validates skill frontmatter integrity, checks for adapter configuration drift, scans for accidental secrets or API keys, and runs your test suite.
+
 ### Plugin Skills & Validation
 
 You can expand your `.agents` folder with community plugins or validate your own custom skills using the top-level commands:
 
 ```bash
 # Launch the interactive skill installer to browse and install community skills
-npx contextos-agents install-skill
+contextos install-skill
+# or: npx contextos install-skill
 
 # Or install a specific skill from a GitHub repository automatically
-npx contextos-agents install-skill --from-repo kok-o/awesome-skill
+contextos install-skill --from-repo kok-o/awesome-skill
 
 # Validate your local skills (checks frontmatter, dependencies, and sync)
-npx contextos-agents audit
+contextos audit
 ```
 
 ## ContextOS MCP Server & Autonomous Multi-Agent Swarm
@@ -286,39 +342,39 @@ Add ContextOS to your IDE's MCP settings (e.g. in `.agents/mcp_config.json`):
 
 Tests use the **Node.js built-in test runner** for the core framework and **Vitest** for the MCP engine — zero external test bloat.
 
-### 1. Root Test Suite (121 tests)
+### 1. Root Test Suite (131 tests)
 
 ```bash
 npm test
 ```
 
 ```text
-# tests 121
+# tests 131
 # suites 27
-# pass  121
+# pass  131
 # fail  0
 ```
 
-### 2. MCP Server Test Suite (428 tests)
+### 2. MCP Server Test Suite (440 tests)
 
 ```bash
 cd contextos-mcp && npm test
 ```
 
 ```text
-Test Files  24 passed (24)
-     Tests  428 passed (428)
+Test Files  25 passed | 1 skipped (26)
+     Tests  440 passed | 13 skipped (453)
 ```
 
 **Test coverage:**
 
-- `tests/install.test.js` — installer CLI flags (--help, --dry-run, --force)
-- `tests/export.test.js` — ctx.js export for gemini, claude, cursor (.mdc rules), copilot, aider
+- `tests/install.test.js` — installer CLI flags (--help, --minimal, --dry-run, --force)
+- `tests/export.test.js` — ctx.js export for gemini, claude, cursor (.mdc rules), copilot, aider, zed
 - `tests/skills.test.js` — validates all skill source files and frontmatter
 - `tests/profile.test.js` — profile resolution, stack auto-detection, and skill filtering
 - `tests/validate.test.js` — validator rules, dependency graph, and sync checks
 - `tests/plugins.test.js` — plugin lockfile, registry fetching, and security checks
-- `tests/resolver.test.js` — dynamic skill resolution, progressive index, and bilingual prompt matching
+- `tests/resolver.test.js` — dynamic skill resolution, AST import graph analysis, progressive index, and bilingual prompt matching
 - `tests/benchmark.test.js` — benchmark scoring engine, static AST checks, runtime sandbox, and reporters
 - `contextos-mcp/tests/unit/session-persistence.test.ts` — session disk persistence, thread state tracking, and orphan purge
 - `contextos-mcp/tests/unit/contextos-tools.test.ts` — all 6 MCP tool handlers and validation
@@ -381,7 +437,7 @@ The runtime sandbox evaluates model outputs against real-world engineering invar
 | **DDD Order Aggregate Root** | Architecture & DDD | `ddd`, `system-design`, `decisions` | Immutable `Money` Value Object, state-machine invariants (PENDING → PAID → SHIPPED), explicit Domain Event classes with queue draining. |
 | **Resilient API Client** | Reliability & Async | `typescript`, `system-design`, `performance` | 3-state Circuit Breaker (CLOSED → OPEN → HALF-OPEN), `AbortController` timeouts, typed error taxonomy without credential leakage. |
 
-### Running Benchmarks Locally
+### Running Benchmarks Locally & in CI
 
 You can run the benchmark suite locally with your own API keys:
 
@@ -393,10 +449,24 @@ npm run benchmark:runtime -- --provider gemini --model gemini-2.5-flash
 # Run with OpenAI:
 $env:OPENAI_API_KEY = "sk-..."
 npm run benchmark:runtime -- --provider openai --model gpt-4o
+
+# Run complete multi-model runtime matrix (Gemini, OpenRouter, AgentRouter):
+GEMINI_API_KEY=... OPENROUTER_API_KEY=... AGENTROUTER_API_KEY=... node benchmarks/run-multi-runtime.cjs
 ```
 
 When executed, reports are generated in `benchmarks/results/` (`.html`, `.md`, `.json`) and tracked so results are visible and shareable.
 
+> [!NOTE]
+> **Why Runtime Benchmarks Are Dispatch-Only in CI:** Standard CI checks (`validate-skills.yml`) run hermetically without external API calls to avoid flaky network dependencies and API token expenditures on every pull request. Live runtime evaluation is triggered on demand via GitHub Actions **Workflow Dispatch** ([`benchmark-runtime.yml`](.github/workflows/benchmark-runtime.yml)) using secure repository secrets.
+
+
+## Security — Third-Party Skills
+
+ContextOS skills are **executable context** — they become part of the system prompt that controls your AI agent's behavior. A malicious skill could instruct the AI agent to exfiltrate environment variables, modify files, or ignore your project's security policies.
+
+> [!CAUTION]
+> **Install skills only from repositories you trust as you would trust executable code.** Skills installed via `ctx.js skill add` from npm or GitHub are not sandboxed. ContextOS includes a built-in prompt injection scanner, but it cannot guarantee safety of arbitrary third-party content.
+
 ## Contributing
 
 We are open to pull requests! See [CONTRIBUTING.md](./CONTRIBUTING.md) for a step-by-step guide on how to add a new skill.