How the OfficeCLI Skill Installer Detects AI Tools and Installs Skill Files Automatically

The OfficeCLI skill installer uses a static SkillInstaller helper class to scan the user's home directory for specific agent folders (like .claude or .copilot), then automatically copies embedded skill files into the detected agents' skill directories.

The iOfficeAI/OfficeCLI repository provides a command-line interface that bridges Office document manipulation with AI coding agents. Understanding how the OfficeCLI skill installer detects AI tools and installs skill files automatically reveals a robust file-system detection strategy that keeps agent capabilities synchronized with the CLI.

The Tool Detection Table

At the core of the detection logic lies a static table that maps supported AI agents to their file system signatures.

Mapping Agents to Directories

The installer maintains a Tools array in src/officecli/Core/SkillInstaller.cs that defines each supported agent using a tuple containing human-readable aliases, display names, detection directories, and target skill directories:

// src/officecli/Core/SkillInstaller.cs
private static readonly (string[] Aliases, string DisplayName, string DetectDir, string SkillDir)[] Tools =
[
    (["claude", "claude-code"],       "Claude Code",    ".claude",              Path.Combine(".claude", "skills")),
    (["copilot", "github-copilot"],   "GitHub Copilot", ".copilot",             Path.Combine(".copilot", "skills")),
    // … other agents omitted for brevity …
];

This table provides the detection strategy for the entire installation pipeline. The DetectDir column specifies the relative folder under the user's home directory that signals an agent's presence (e.g., .claude), while SkillDir indicates where skill files must be installed (e.g., .claude/skills).

Detecting AI Agents on the File System

The installer performs file system checks to determine which agents are present before copying any files.

When executing InstallBaseToAll(), InstallSkillToAll(), or RefreshInstalled(), the code iterates through the Tools array and verifies directory existence:

// src/officecli/Core/SkillInstaller.cs – InstallBaseToAll()
foreach (var tool in Tools)
{
    if (Directory.Exists(Path.Combine(Home, tool.DetectDir)))   // ← detection
    {
        // … install the base SKILL.md into the agent’s skill dir …
    }
}

If Directory.Exists returns true for a given DetectDir, the corresponding agent is considered active, and the installer proceeds with file operations for that specific tool.

Installing the Base SKILL.md Guide

Once an agent is detected, the installer deploys an umbrella skill file that provides the generic OfficeCLI guide.

The InstallBaseFile() method constructs the target path using the agent's SkillDir and an UmbrellaFolder constant:

// src/officecli/Core/SkillInstaller.cs – InstallBaseFile()
var targetPath = Path.Combine(Home, tool.SkillDir, UmbrellaFolder, "SKILL.md");
InstallBaseFile(tool.DisplayName, targetPath);

This method loads the embedded resource skills/officecli/SKILL.md and writes it to the target path, creating missing directories via SafeCreateDirectory. This ensures every detected agent receives the foundational OfficeCLI documentation.

Installing Specific Skills

When users request specific capabilities (e.g., pptx or morph-ppt), the installer follows a three-phase process to distribute the appropriate files.

The Installation Workflow

The InstallSkillToAll() method executes the following steps:

1. Lookup: Resolves the skill folder name from SkillMap (e.g., "pptx" maps to "officecli-pptx")
2. Enumeration: Retrieves all embedded files for that skill via GetEmbeddedSkillFiles()
3. Distribution: For each detected agent, writes files into ~/<agent‑skill‑dir>/<skill‑folder>/ using InstallSkillFiles(), which also rewrites cross-skill markdown links to proper CLI commands

// src/officecli/Core/SkillInstaller.cs – InstallSkillToAll()
var files = GetEmbeddedSkillFiles(folder);
foreach (var tool in Tools)
{
    if (Directory.Exists(Path.Combine(Home, tool.DetectDir)))
    {
        var skillDir = Path.Combine(Home, tool.SkillDir, folder);
        InstallSkillFiles(tool.DisplayName, skillDir, files);
        // … report installed agents …
    }
}

This approach ensures that skills are only installed to agents actually present on the system, avoiding unnecessary file operations.

Automatic Refresh After Binary Upgrades

The skill installer maintains synchronization with the CLI version through an automatic refresh mechanism triggered during updates.

When OfficeCLI upgrades, UpdateChecker invokes SkillInstaller.RefreshInstalled(). This method walks each detected agent's skill directory, identifies already-installed skill sub-folders by checking for the presence of SKILL.md, and rewrites the files with the newest embedded versions:

// src/officecli/Core/SkillInstaller.cs – RefreshInstalled()
if (!Directory.Exists(Path.Combine(Home, tool.DetectDir))) continue;
var skillsDir = Path.Combine(Home, tool.SkillDir);
…
var subSkillFile = Path.Combine(skillsDir, folder, "SKILL.md");
if (File.Exists(subSkillFile))
{
    var files = GetEmbeddedSkillFiles(folder);
    RewriteSkillFilesQuiet(targetDir, files);
}

The process is safeguarded so a failure for one agent does not prevent updates to others, ensuring robust multi-agent environments.

Summary

• Detection Strategy: The installer uses a static Tools table in SkillInstaller.cs that maps agent aliases to detection directories (DetectDir) and target skill directories (SkillDir)
• File System Scanning: Detection relies on Directory.Exists checks against the user's home directory to identify installed agents like Claude (.claude) or Copilot (.copilot)
• Base Installation: The umbrella SKILL.md is copied to each detected agent's skill folder via InstallBaseFile(), creating directory structures as needed
• Specific Skill Deployment: InstallSkillToAll() looks up skills in SkillMap, retrieves embedded resources, and installs them only to detected agents while rewriting internal links
• Automatic Updates: UpdateChecker triggers RefreshInstalled() to update existing skill files after binary upgrades without requiring manual reinstallation

Frequently Asked Questions

How does OfficeCLI know which AI agents are installed?

OfficeCLI checks for the presence of specific directories in your home folder. According to the source code in src/officecli/Core/SkillInstaller.cs, it looks for folders like .claude, .copilot, and others defined in the Tools array. If Directory.Exists returns true for a DetectDir path, the agent is considered present and eligible for skill installation.

What happens when I run officecli skills install without arguments?

Running the command without arguments installs the base SKILL.md guide to every detected AI agent. The InstallBaseToAll() method iterates through all supported agents, checks which directories exist on your system, and copies the umbrella skill file to each agent's skill folder (e.g., ~/.claude/skills/).

Where are the skill files actually stored on my system?

Skill files are stored in agent-specific subdirectories under your home folder. For example, Claude Code skills reside in ~/.claude/skills/ while GitHub Copilot skills go to ~/.copilot/skills/. Each specific skill creates its own folder within these directories (e.g., ~/.claude/skills/officecli-pptx/SKILL.md).

How does the installer handle updates to existing skills?

When you update OfficeCLI itself, the UpdateChecker class automatically invokes SkillInstaller.RefreshInstalled(). This method scans your existing skill directories, finds folders containing SKILL.md files, and overwrites them with the latest embedded versions from the new binary. This ensures your AI agents always have the most current documentation and capabilities without manual reinstallation.

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