# TeamAI Contribution Workflow: Promoting Learnings to Formal Skills and Rules

> Discover the TeamAI contribution workflow. Promote developer learnings to formal skills and rules via a three-stage pipeline. Enhance your team's knowledge base effectively.

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

---

**The TeamAI contribution workflow transforms informal developer learnings into formal skills, rules, or documentation through a three-stage pipeline: contributing the learning to the repository, identifying promotion candidates based on confidence thresholds, and executing the promotion with AI-assisted content transformation.**

TeamAI CLI treats every recorded learning as raw, unstructured team knowledge that can mature into structured artifacts. When a learning accumulates sufficient trust signals—**high confidence scores**, **enough up-votes**, **contributions from multiple members**, and **minimum age requirements**—the platform advances it from the `learnings/` directory to the appropriate formal category. This article explains the complete technical implementation of the contribution workflow for promoting learnings to formal skills/rules in TeamAI, from initial file creation to final AI-driven transformation.

## The Three-Stage Promotion Pipeline

The promotion workflow consists of three distinct stages, each implemented in specific source files within the Tencent/teamai-cli repository:

1. **Contribute**: Push a Markdown file into the repository's `learnings/` folder using namespace resolution.
2. **Candidate Selection**: Scan existing learnings and filter based on quality thresholds.
3. **Promotion**: Copy the selected learning to `skills/`, `rules/`, or `docs/` and rewrite it with AI assistance.

## Stage 1: Contributing a Learning to the Repository

The workflow begins when a developer runs `teamai contribute` to record informal knowledge. In [`src/contribute.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/contribute.ts), the `contribute()` function (lines 33-34) handles file validation and determines the active scope (project-specific or user-shared).

The system calls `resolveLearningsSubdir()` (lines 36-48) to locate the correct sub-directory based on the manifest's `resources.learnings` settings. If exactly one active learnings namespace exists, the file lands in a project-specific sub-directory; otherwise, it writes to the shared root. The utility `generateFilename` (lines 13-23) creates a safe filename before writing the file to `repoPath/learnings/<subdir>/<filename>`.

After the Git push, `rebuildIndexAfterContribute()` (lines 51-87) rebuilds the local search index, making the new learning instantly recallable by the team.

```bash

# Record a session note and contribute it to the team repo

echo "# How to deploy a Lambda function

Run \`npm run deploy\` after building." > /tmp/deploy-note.md

teamai contribute --file /tmp/deploy-note.md --title "Deploy Lambda"

```

## Stage 2: Identifying Promotion Candidates

Before promotion, the system evaluates whether a learning has matured sufficiently. The `findPromotionCandidates()` function in [`src/maintenance/promote.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/maintenance/promote.ts) (lines 33-89) implements this filtering logic, triggered by `teamai recall maintenance --update-quality` or the UI's "KB Health" maintenance console.

The function applies four strict thresholds to each learning file:

- **Confidence ≥ 0.90** (`MIN_CONFIDENCE`)
- **At least 5 up-votes** (`MIN_UPVOTED`)
- **Minimum 2 distinct contributors** (`MIN_USERS`)
- **Minimum 14 days old** (`MIN_AGE_DAYS`)

Already-promoted learnings are skipped by checking for the `promoted_to` front-matter marker (line 65). The function returns a sorted array of `PromotionCandidate` objects (lines 9-18) based on pre-computed confidence scores from `computeAllConfidence`.

```bash

# Display all learnings that satisfy promotion criteria

teamai recall promote

```

## Stage 3: Executing the Promotion

Once a candidate is selected, the `executePromotion()` function in [`src/maintenance/promote.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/maintenance/promote.ts) (lines 52-86) handles the transition to formal status. The user initiates this via `teamai recall promote <learningId> --category <type>`.

The function determines the target directory—`skills/`, `rules/`, or `docs/`—either from an explicit `--category` flag or from the AI-inferred `suggestedCategory`. It creates the target directory using `ensureDir` (line 59), then copies the source file.

The critical transformation occurs in `generatePromotedContent()` (lines 5-50), which builds a format-specific prompt and calls Claude via `callClaude` to rewrite the markdown into the appropriate formal structure. If the AI call fails, the system falls back to the original content (lines 46-48). Finally, the function updates the original learning's front-matter with a `promoted_to` field (lines 78-82), ensuring traceability and preventing duplicate promotions.

```bash

# Promote a specific learning to the skills directory with AI transformation

teamai recall promote deploy-lambda-2024-08-01-abc123 --category skills

# Preview the promotion without writing changes

teamai recall promote deploy-lambda-2024-08-01-abc123 --dry-run

```

## Practical CLI Examples

### Contributing a Learning

Record ad-hoc knowledge and push it directly to the repository's main branch:

```bash
teamai contribute --file ./incident-retro.md --title "Database Connection Pool Tuning"

```

### Listing Qualified Candidates

Review which learnings meet the promotion thresholds before selecting one:

```bash
teamai recall maintenance --update-quality
teamai recall promote

```

### Promoting with Category Inference

Let the AI suggest the appropriate category based on content analysis:

```bash
teamai recall promote learning-id-123

```

### Dry-Run Promotion

Validate the target path and preview AI-generated content without modifying files:

```bash
teamai recall promote learning-id-123 --category rules --dry-run

```

## Summary

- The **contribution workflow** spans three distinct stages: initial contribution via [`src/contribute.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/contribute.ts), candidate selection via `findPromotionCandidates()` in [`src/maintenance/promote.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/maintenance/promote.ts), and final promotion via `executePromotion()`.
- **Quality gates** require 0.90 confidence, 5 up-votes, 2 contributors, and 14 days of age before a learning qualifies for promotion.
- **AI transformation** uses Claude to rewrite raw learnings into structured skills, rules, or documentation formats.
- **Traceability** is maintained by preserving the original learning with a `promoted_to` marker in its front-matter.
- The CLI exposes these functions through `teamai contribute` and `teamai recall promote` commands.

## Frequently Asked Questions

### What criteria must a learning meet to become a promotion candidate?

According to [`src/maintenance/promote.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/maintenance/promote.ts), a learning must satisfy four thresholds: confidence score ≥ 0.90 (`MIN_CONFIDENCE`), at least 5 up-votes (`MIN_UPVOTED`), contributions from 2 or more distinct users (`MIN_USERS`), and a minimum age of 14 days (`MIN_AGE_DAYS`). The system also excludes any learning that already contains a `promoted_to` front-matter field.

### How does TeamAI ensure the original learning remains accessible after promotion?

The `executePromotion()` function preserves the original file in the `learnings/` directory while stamping its front-matter with a `promoted_to` field that references the new formal artifact location. This creates a permanent audit trail and prevents the learning from reappearing in future candidate scans.

### Can I preview a promotion before committing changes to the repository?

Yes. Append the `--dry-run` flag to the `teamai recall promote` command to output the intended target path and AI-generated content preview without writing any files to disk. This allows teams to validate the transformation quality before finalizing the promotion.

### Which AI model performs the content transformation during promotion?

The `generatePromotedContent()` utility in [`src/maintenance/promote.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/maintenance/promote.ts) invokes Claude via the `callClaude` function (implemented in [`src/utils/ai-client.js`](https://github.com/Tencent/teamai-cli/blob/main/src/utils/ai-client.js)) to rewrite the markdown. If the Claude API call fails or returns an error, the system gracefully falls back to preserving the original learning content without AI modification.