| name | share-learning |
| description | Promote a team-relevant learning to the shared team-knowledge repo, deduping against existing notes first. Triggers "share this", "promote to the team repo", "add to the knowledge base", or after a gotcha/decision/convention worth team-wide awareness. |
| allowed-tools | ["Bash(gh api*)","Bash(base64*)"] |
share-learning
Promote a single learning to the team's shared knowledge repo (darkroomengineering/team-knowledge) —
the "public corpus" tier of the knowledge system (see docs/knowledge-system.md). Local,
personal knowledge stays in auto-memory; this skill is only for things another teammate's
agent would benefit from knowing.
When to use
Use when a learning meets the shared-tier bar from AGENTS.md (Knowledge Routing): an
architecture decision the team must follow, a library gotcha that affects everyone, a
convention, an incident postmortem, or a reusable pattern. If it is a personal preference,
local project state, or an external pointer, let auto-memory handle it instead — do NOT
post it.
Inputs
Invoked as /share-learning <kind> "<text>" where <kind> is one of:
decision, convention, gotcha, incident, pattern.
If invoked without arguments, infer the most likely kind and a concise text from the
recent conversation, then show the user what you intend to post and confirm before posting.
Steps
-
Resolve the repo. Read $KNOWLEDGE_REPO from the environment; default is
darkroomengineering/team-knowledge. If $KNOWLEDGE_REPO is unset and you do not want
to use the default, stop and tell the user to set it (see docs/knowledge-system.md for
setup).
-
Dedup against the index (required). Fetch the current index:
gh api repos/$KNOWLEDGE_REPO/contents/INDEX.md --jq .content | base64 -d
Scan the note names and titles in the index for an entry that already captures this
learning (semantic near-duplicate, not just exact match). If you find one:
- Show the user the existing note name and its summary line.
- Ask whether to skip (already covered), post anyway (genuinely distinct), or
revise your proposed entry to complement it.
Only continue to step 3 once the user has chosen, or when there is clearly no duplicate.
-
Post. Derive a name (kebab-case slug from the essence of the learning). Assemble
the note:
- Frontmatter:
name = the slug; kind from the argument; added-by from
gh api user --jq .login (fall back to git config user.name if that fails);
tags optional; supersedes only when this note replaces an existing one.
- Body: what happened + why it matters + how to apply it. One learning per note,
atomic and self-contained.
If creating a new note:
NOTE="---
name: <name>
kind: <kind>
tags: [<tag1>, <tag2>]
added-by: <login>
---
<body>"
gh api -X PUT repos/$KNOWLEDGE_REPO/contents/<name>.md \
-f message="knowledge: add <name>" \
-f content="$(printf '%s' "$NOTE" | base64)"
If updating an existing note, first GET its current sha:
SHA=$(gh api repos/$KNOWLEDGE_REPO/contents/<name>.md --jq .sha)
gh api -X PUT repos/$KNOWLEDGE_REPO/contents/<name>.md \
-f message="knowledge: update <name>" \
-f content="$(printf '%s' "$NOTE" | base64)" \
-f sha="$SHA"
-
Report. Surface the blob URL to the user:
https://github.com/$KNOWLEDGE_REPO/blob/main/<name>.md
Notes
- This skill posts to a shared, team-visible repo — treat it like publishing. Never post
secrets, credentials, or anything from
.env. When unsure whether something is
team-relevant, ask the user rather than over-sharing.
- The dedup step is what makes this more than a
gh wrapper: you are exercising judgment
about whether the corpus already knows this.
