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

> Master the per-user skill exclusion mechanism in TeamAI CLI. Learn how to locally filter skills during pull operations without impacting the shared repository.

- Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli)
- Tags: deep-dive
- Published: 2026-09-11

---

**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`](https://github.com/Tencent/teamai-cli/blob/main/src/types.ts) (lines 87-89), the `LocalConfigSchema` includes an optional `excludedSkills` array:

```typescript
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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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:

```typescript
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:

```bash
teamai exclude list

```

Output:

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

```

To add skills to your exclusion list:

```bash
teamai exclude add noisy-skill another-skill

```

To remove skills:

```bash
teamai exclude remove noisy-skill

```

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

```bash
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`](https://github.com/Tencent/teamai-cli/blob/main/src/types.ts)
- **Scope resolution** via `resolveExcludeScope()` determines whether configurations apply at the project or user level in [`src/exclude.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/exclude.ts)
- The **CLI interface** provides `list`, `add`, and `remove` sub-commands for managing exclusions, wired in [`src/index.ts`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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`](https://github.com/Tencent/teamai-cli/blob/main/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.