TeamAI Contribution Workflow: Promoting Learnings to Formal Skills and Rules

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, 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.

# 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 (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.

# 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 (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.

# 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:

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

Listing Qualified Candidates

Review which learnings meet the promotion thresholds before selecting one:

teamai recall maintenance --update-quality
teamai recall promote

Promoting with Category Inference

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

teamai recall promote learning-id-123

Dry-Run Promotion

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

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

Summary

• The contribution workflow spans three distinct stages: initial contribution via src/contribute.ts, candidate selection via findPromotionCandidates() in 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, 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 invokes Claude via the callClaude function (implemented in 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.

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