How OfficeCLI Auto-Install Detects and Configures Skills for AI Coding Agents

OfficeCLI uses a three-stage pipeline—detection, dynamic installation, and agent registration—to automatically discover skill manifests, install missing dependencies, and expose functions to AI coding agents.

The OfficeCLI open-source project provides a built-in auto-install mechanism that bridges reusable code modules ("skills") with AI-driven development workflows. This system eliminates manual setup by scanning for skill definitions, resolving dependencies on-the-fly, and translating skill signatures into formats that AI agents like OpenAI's GPT models can invoke directly. Below is a detailed walkthrough of how each stage works, grounded in the actual source implementation.

---

Stage 1: Skill Detection via Manifest Scanning

When the CLI initializes, it scans the skills/ directory for sub-folders containing a skill.json manifest file. Each manifest declares:

• Skill name and description — human-readable metadata
• Entry point — the file that exports the skill's functionality
• Dependencies — required npm (JavaScript/TypeScript) or pip (Python) packages
• Function specifications — parameter schemas for AI agent integration

The detection logic is controlled by the autoInstall flag, defined in the Node SDK's type definitions at [sdk/node/index.d.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts#L31):

interface OfficeCLIOptions {
  autoInstall?: boolean;  // defaults to true
  // ... other options
}

When autoInstall is enabled (default), the CLI recursively searches skills/ for valid manifests before executing any user command.

---

Stage 2: Dynamic Dependency Installation

Missing dependencies trigger automatic installation via src/autoInstall.ts. This module implements two package manager wrappers:

• npmInstall() — for JavaScript/TypeScript skills declared in skill.json under dependencies.npm
• pipInstall() — for Python skills declared under dependencies.python

The installer performs version conflict detection against existing package.json or requirements.txt files in the working directory. This ensures that auto-installed packages do not collide with project-specific dependency constraints.

If the CLI detects a skill requiring python-pptx that isn't present, for example, it executes pip install python-pptx before proceeding to load the skill's entry point.

---

Stage 3: Agent Configuration via Function Registration

Once dependencies are resolved, the CLI registers skills with the AI coding agent through registerSkillFunctions() in src/agentIntegration.ts. This function transforms manifest declarations into OpenAI-compatible function objects.

For a skill with this manifest snippet:

{
  "name": "morphPpt",
  "functions": [
    {
      "name": "applyMorph",
      "description": "Apply a morph transition between two slides",
      "parameters": {
        "type": "object",
        "properties": {
          "slideFrom": {"type": "integer"},
          "slideTo": {"type": "integer"}
        },
        "required": ["slideFrom", "slideTo"]
      }
    }
  ]
}

The registration generates an OpenAIFunction object that gets appended to the chat completion request payload. The AI model then receives this schema:

{
  "name": "applyMorph",
  "description": "Apply a morph transition between two slides",
  "parameters": {
    "type": "object",
    "properties": {
      "slideFrom": {"type": "integer"},
      "slideTo": {"type": "integer"}
    },
    "required": ["slideFrom", "slideTo"]
  }
}

This enables the model to invoke applyMorph as a tool call without explicit prompt engineering from the user.

---

Practical Code Examples

Enabling Auto-Install in Node.js

import { OfficeCLI } from 'officecli/sdk/node';

// autoInstall defaults to true; explicitly enable for clarity
const cli = new OfficeCLI({ autoInstall: true });

// Execute command—skills detected, installed, and registered automatically
await cli.run('ppt morph --from 1 --to 3');

The autoInstall option type definition resides at [sdk/node/index.d.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts#L31).

Using the Python SDK

from officecli.sdk.python import OfficeCLI

# Python SDK implicitly enables auto-install

cli = OfficeCLI()
cli.run("ppt morph --from 1 --to 3")

Python implementation mirrors Node behavior; core logic is in [sdk/python/officecli.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/python/officecli.py).

Creating a Custom Skill

mkdir -p skills/text-utils
cat > skills/text-utils/skill.json <<'EOF'
{
  "name": "textUtils",
  "description": "String manipulation utilities",
  "entry": "index.js",
  "dependencies": { "npm": ["lodash"] },
  "functions": [
    {
      "name": "camelCase",
      "description": "Convert string to camelCase",
      "parameters": {
        "type": "object",
        "properties": { "input": { "type": "string" } },
        "required": ["input"]
      }
    }
  ]
}
EOF

cat > skills/text-utils/index.js <<'EOF'
const _ = require('lodash');
exports.camelCase = (args) => _.camelCase(args.input);
EOF

Running any CLI command now triggers automatic lodash installation and exposes camelCase to the AI agent.

---

Key Source Files and Their Roles

File	Purpose
[sdk/node/index.d.ts](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts#L31)	TypeScript declarations for autoInstall option
[sdk/python/officecli.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/python/officecli.py)	Python SDK entry point with implicit auto-install
[skills/morph-ppt/reference/morph-helpers.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/morph-ppt/reference/morph-helpers.py)	Example implementation of a detectable skill
src/autoInstall.ts	Core dependency installation logic (search repo for "autoInstall")
src/agentIntegration.ts	OpenAI function registration (search repo for "registerSkillFunctions")

---

Summary

• Detection — OfficeCLI scans skills/ directories for skill.json manifests on startup, governed by the autoInstall flag in sdk/node/index.d.ts.
• Installation — Missing npm or pip dependencies are resolved automatically via src/autoInstall.ts without manual intervention.
• Agent integration — Skill functions are translated to OpenAI-compatible schemas by registerSkillFunctions() in src/agentIntegration.ts, enabling direct model invocation.
• Cross-language support — Both Node.js and Python SDKs implement identical auto-install behavior, with Python defaulting to enabled.

---

Frequently Asked Questions

What happens if auto-install is disabled?

The CLI skips dependency resolution and only loads skills with already-satisfied requirements. Skills with missing dependencies remain unavailable but do not cause runtime errors; they're silently excluded from the agent's function registry.

Can auto-install cause version conflicts with my project's dependencies?

The installer checks existing package.json and requirements.txt files before installing. It prefers compatible version ranges and warns when conflicts cannot be resolved automatically, allowing manual intervention.

Does OfficeCLI support private npm registries or pip indexes?

Yes. The npmInstall() and pipInstall() helpers respect standard environment variables: NPM_CONFIG_REGISTRY for npm and PIP_INDEX_URL for pip. Configure these before launching the CLI to route auto-installation through private sources.

How do I verify which skills were detected and registered?

Enable verbose logging via the DEBUG=officecli:* environment variable. This outputs the manifest discovery sequence, installation decisions, and final function registry sent to the AI agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}