darkroomengineering 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.
Before starting, run gh auth status and confirm the authenticated account can read
darkroomengineering/team-knowledge (or $KNOWLEDGE_REPO) with
gh api repos/${KNOWLEDGE_REPO:-darkroomengineering/team-knowledge} --jq .full_name. Stop with the
failed prerequisite if either check fails. Do not wait until the write step to surface missing
authentication or repository access.
Steps
Resolve the repo. Read
$KNOWLEDGE_REPOfrom the environment; default isdarkroomengineering/team-knowledge:KNOWLEDGE_REPO="${KNOWLEDGE_REPO:-darkroomengineering/team-knowledge}"Dedup against the index (required). Fetch the current index:
gh api repos/$KNOWLEDGE_REPO/contents/INDEX.md --jq .content | base64 -dScan 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;kindfrom the argument;added-byfromgh api user --jq .login(fall back togit config user.nameif that fails);tagsoptional;supersedesonly 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"- Frontmatter:
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
ghwrapper: you are exercising judgment about whether the corpus already knows this.