Per-User Skill Exclusion Mechanism in TeamAI CLI: How It Works

The per-user skill exclusion mechanism in TeamAI CLI allows individual users to maintain a personal list of skill names that are automatically filtered out during teamai pull operations, stored locally in excludedSkills without affecting the shared team repository.

The TeamAI CLI provides a lightweight way for developers to customize their local AI tool environment without modifying shared configurations. This article examines the per-user skill exclusion mechanism implemented in the Tencent/teamai-cli repository, which enables users to skip specific skills during synchronization while keeping team repositories unchanged.

How the Per-User Skill Exclusion Mechanism Works

The mechanism operates through a local configuration array that persists across sessions. When a user executes teamai pull, the CLI checks this private exclusion list before downloading skills, ensuring unwanted or experimental skills never reach the local environment.

Configuration Storage and Schema

The exclusion list is defined in the TypeScript schema to ensure type safety.

In src/types.ts (lines 87-89), the LocalConfigSchema includes an optional excludedSkills array:

excludedSkills: z.array(z.string()).optional()

This array stores the skill names as strings, maintaining a per-user scope that remains isolated from project-level configurations.

CLI Commands for Managing Exclusions

Users interact with the exclusion system through the teamai exclude sub-command, registered in src/index.ts (lines 49-78). The command provides three distinct actions:

• list: Displays the current excluded skills from the local configuration
• add: Appends new skill names to the exclusion list (automatically deduplicated)
• remove: Deletes specific skill names from the list

Scope Resolution and Persistence Logic

The exclusion system handles both project-scoped and user-scoped configurations through dedicated functions in src/exclude.ts.

The resolveExcludeScope() function (lines 12-15) determines whether the current context is a project scope or plain user scope, returning the appropriate LocalConfig object. This ensures that exclusions apply correctly based on where the command executes.

When modifications occur, saveExcludeScopeConfig() (lines 17-30) writes the updated configuration back to disk. This function also clears state.lastPullRev to force a full synchronization on the next teamai pull, ensuring that newly excluded skills are immediately removed from the local environment.

Filtering During Pull Operations

The actual filtering logic executes during the pull phase in src/pull.ts. After loading the user configuration, the code constructs a Set called excludedSkills from localConfig.excludedSkills.

When processing the skills resource type, the implementation filters the items array:

const excludedSkills = new Set(localConfig.excludedSkills ?? []);

if (excludedSkills.size > 0) {
  items = items.filter((item) => !excludedSkills.has(item.name));
}

This filter removes any skill whose name exists in the user's exclusion set before constructing the final synchronization list. Because this filtering happens client-side using the local configuration, the team repository remains unaffected by individual user preferences.

Practical Usage Examples

To view your current exclusions:

teamai exclude list

Output:

Excluded skills (2):
  unused-skill
  experimental-skill

To add skills to your exclusion list:

teamai exclude add noisy-skill another-skill

To remove skills:

teamai exclude remove noisy-skill

After modifying the exclusion list, the next teamai pull automatically skips the excluded skills:

teamai pull   # runs a full sync; excluded skills are omitted

Summary

• The per-user skill exclusion mechanism stores excluded skill names in excludedSkills within the local configuration schema defined in src/types.ts
• Scope resolution via resolveExcludeScope() determines whether configurations apply at the project or user level in src/exclude.ts
• The CLI interface provides list, add, and remove sub-commands for managing exclusions, wired in src/index.ts
• Persistence through saveExcludeScopeConfig() clears the last pull revision to force full resynchronization
• Runtime filtering uses a Set data structure during teamai pull to efficiently exclude skills before local installation in src/pull.ts

Frequently Asked Questions

Where is the per-user skill exclusion list stored in TeamAI CLI?

The exclusion list is stored in the user's local configuration file, defined by the LocalConfigSchema in src/types.ts. Unlike project-level configurations, this file resides in the user's local environment and never commits to the shared team repository, ensuring personal preferences remain private.

How does TeamAI CLI handle adding or removing skills from the exclusion list?

When you run teamai exclude add or teamai exclude remove, the CLI invokes functions in src/exclude.ts. The saveExcludeScopeConfig() function persists changes to disk and clears state.lastPullRev, forcing a complete resynchronization during the next pull to apply the updated exclusions immediately.

Does excluding a skill affect other team members?

No. Because the excludedSkills array exists only in the local user configuration, filtering occurs client-side during teamai pull in src/pull.ts. The team repository remains unchanged, and other developers continue to receive all available skills unless they maintain their own exclusion lists.

Why does TeamAI CLI force a full pull after updating exclusions?

The mechanism clears state.lastPullRev in saveExcludeScopeConfig() (lines 17-30) to ensure that previously downloaded excluded skills are removed from the local environment. Without forcing a full synchronization, excluded skills might persist locally even after being added to the exclusion list.

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