Scenario: Member — publish a reusable skill
Goal: the user turns something they built into team knowledge everyone can pull. Any member can do this — you do not need to be an admin. The usual entry point is the user just asking in plain language, e.g. "share this xxx skill with my team", in whatever language they work in.
Publishing is a team-visible action — confirm before you run it. A plain
worded request tells you what the user wants, not that they are ready to push
it to everyone. Before teamai push / teamai contribute, show exactly what
will be shared (which skill or file, and that it goes to the whole team) and get
an explicit go-ahead. Do not publish from an offhand mention of "sharing" in
ordinary conversation — only when the user has clearly asked to publish this
thing now.
Which kind of contribution?
- A learning (a lesson, a gotcha, how you solved something) → this is
automatic once recall is on (off by default) and the teamai config loads: TeamAI prompts at the end of a session worth sharing and
offers the
teamai-share-learningsworkflow, whose learning step runs theshareskill (teamai skill get share) to summarize the session beforeteamai contribute. The user does not come through this flow for it. (Step A below is only a manual fallback for while recall is off.) - A reusable skill (a
SKILL.mdothers invoke) → author the skill, thenteamai push(Step B — the main purpose of this reference).
Step A — Contribute a learning by hand (fallback only)
Prefer the
shareworkflow (teamai skill get share). Use these manual steps only while it refuses because recall is off.
Write a short Markdown doc that captures the lesson. Keep it concrete and actionable — a knowledge base, not a diary. Include YAML frontmatter for search indexing:
--- title: "<short title of the problem or finding>" author: <username> date: <YYYY-MM-DD> tags: [tag1, tag2, tag3] --- ## Background What were you doing? What went wrong? ## Solution How did you fix it? Key steps. ## Takeaways - Lesson 1 - Lesson 2Save it to a temp file, then push it to the team:
teamai contribute --file /tmp/my-learning.md --title "K8s pod startup timeout"
The doc lands in the team's learnings/ and appears for teammates on their next
teamai pull. It is also searchable via teamai recall.
Tip: while recall is on,
teamai skill get shareauto-summarizes the current session instead of you writing the doc by hand.
Step B — Contribute a reusable skill
Create the skill directory with a
SKILL.md:skills/my-skill/SKILL.mdMinimal frontmatter:
--- name: my-skill description: "One line — what it does and when to use it" --- # My Skill Step-by-step instructions the AI should follow.Publish it:
teamai push --skill skills/my-skill # one skill # or teamai push # review and push everythingTo publish into a specific role namespace:
teamai push --skill <path> --role <id>.--skill <path>selects that exact local copy after resolving~and symlinks; a same-named copy in another tool is never a substitute.--role <ns>/--project <id>place every new resource, not only skills: a new rule and a new agent land in that namespace too (a project resolves each from its own axis —knowledgefor rules,agentsfor agents). Without one, the role and the active projects decide; with neither, a new rule or agent stays at the shared root and reaches the whole team. When an active project cannot be resolved (not inmanifest/projects.yaml, or that file is missing), push stops with exit 2 until you fix it or pass--role/--project, or explicitly choose the shared root with--shared. This flag places new resources at the shared root even when namespaces exist and cannot combine with--roleor--project. Shared-root skills retain the existing tag-subscription delivery rules. An edit of a skill, rule or agent you received from a namespace goes back to that namespace, even when it replaces a shared item of the same name; the shared one is left as it is. A delivered skill copy is pushed only when its recorded version matches exactly one current team skill, using that path's history since its latest creation after deletion.--role,--projectand--skilldo not establish an origin. If no unique origin is proven, push skips the edit with a warning; copy it under a new name to send it as a new skill. Use--branch <name>when a new push must target a specific branch; an existing open PR keeps its recorded branch. TeamAI refuses to reset a team-repo clone with user changes, so commit or stash unrelated modified, staged, untracked, or conflicted files before retrying.In self mode, a skill or rule under
.teamai/that matches an older version of the team's file, as it does when the branch is behind the default branch, is skipped with a warning that it "is an older version of" that file: pushing it would revert a teammate's update. To publish an edit of it, bring the current version in first (git fetch origin && git merge origin/<default>, or copy the team's current file over it), redo the edit on top, and push again. Any other team file under.teamai/that the default branch changed since your branch left it is left out of the push when you did not edit it. A file you edited too stops the push with exit 2; merge the default branch and push again. Skills are checked as whole directories, including reference files and deletions: a skill edit stops when it would replace any changed upstream file with a stale local copy, even if you edited a different file.
After contributing
- Confirm it landed:
teamai list skills(orteamai status). - Teammates receive it automatically on their next session, or via
teamai pull.
Before listing rules, push refreshes copies whose bodies still match a recorded
sync revision. The header teamai generates for a tool's own rules format
(Cursor .mdc, JoyCode's own .mdc, Copilot applyTo, Kiro inclusion, Qoder
trigger, Trae globs/alwaysApply, CodeBuddy and WorkBuddy alwaysApply, Oh My Pi alwaysApply/globs, Antigravity trigger) does not count as a local edit: unedited old copies update in that
format, including under COPILOT_HOME in user scope. Genuine local body edits remain push candidates.
Rule pre-sync leaves tools excluded by enabledAgents or disabledAgents untouched.
When only team paths change, applyTo refreshes if the local file still matches
a recorded version's generated copy; locally edited headers are kept.
The copies push refreshes are recorded, so a later teamai pull still updates them.
Oh My Pi and Kiro read only the top of their rules directories, so a namespaced
rule is written flat there (rules/fe/style.md as fe.style.md); an edit of that file
pushes back to rules/fe/style.md. Push requires a delivery record for the flat copy.
A personal file with that name is neither refreshed before push nor offered as
an edit of the team rule.
If two namespaced rules flatten to the same name, neither is written; teamai doctor
reports the collision even when no other rule reaches that tool. Rename one in the
team repo, then run teamai pull. Doctor also reports team-owned OpenCode globs
or inline blocks left after the last rule is removed.
A new file in the rules directory of a tool with a rules format of its own
(Cursor, JoyCode, Copilot, Kiro, Qoder, Trae, CodeBuddy, WorkBuddy, Oh My Pi, Antigravity) is the
member's own rule in that tool's format: push never offers it, and pull leaves
it. To author a new team rule, write it as a plain .md in .claude/rules/
(scope it with paths: frontmatter, which teamai renders into each tool's
format), then run teamai push. A YAML comment after an unquoted glob stays
outside its scope: paths: **/*.ts # TypeScript files matches **/*.ts, including
when written as a block-list entry under paths:.
If push is denied
A permission error usually means you don't have write access to the team repo.
Copy the exact error to your admin and ask them to grant access. (In read-only
HTTP mode, contribute / push are not available — you can only consume.)