Team-authored skills: let each team teach OpenSRE their own vendor workflows

[YauhenBichel]

The idea

Pi's progressive-disclosure skills: a skill is just a markdown file with
frontmatter, loaded only when it is needed — run it with /skill:commit, or
let the agent auto-load it by its description.

---
name: commit
description: Write a Conventional Commits message from staged changes.
---

# Commit

## Usage
1. Run `git diff --staged` to see what changed.
2. Write `type(scope): summary` under 72 chars.
3. Explain "why", then `git commit`.

The proposal for OpenSRE: let each team write their own skills for the vendors
they actually use. How your team triages a Datadog monitor, which dashboards
matter, what "sev2" means where you work — that is team knowledge, and it does
not belong in the OpenSRE repo.

OpenSRE already has this format

Almost exactly. Here is a real one from the tree
(integrations/github/tools/ci_fix/SKILL.md):

---
name: github-ci-fix
description: Use when the user asks OpenSRE to fix failing GitHub PR CI, ...
tools:
  - fix_github_pr_ci
---

# GitHub PR CI Fix

Use `fix_github_pr_ci` for GitHub pull request CI remediation requests, not
`github_cli` or `shell_run`.

Same frontmatter, same name + description, plus a tools: list that binds
the skill to the tools it governs. There are 14 of these today, and a skill_view
action tool the agent can call to read one.

So the format question is settled. Two other things are not.

Gap 1 — skills must live in the OpenSRE repo

tools/registry_skill_guidance.py builds its skill list from seven hardcoded
REPO_ROOT paths plus one glob over a single directory:

explicit = (
    REPO_ROOT / "integrations" / "github" / "tools" / "workflow" / "SKILL.md",
    REPO_ROOT / "integrations" / "sentry" / "tools" / "skills" / "sentry-summary" / "SKILL.md",
    ...
)
discovered = sorted((REPO_ROOT / "tools" / "system" / "python_execution_tool" / "skills").glob("*/SKILL.md"))

A team that wants a skill for how they use Grafana has to open a pull request
against OpenSRE — for knowledge that is specific to their company and useful to
nobody else.

There is no user directory, no project-local directory, no per-team location, and
no way to load one from outside the checkout.

Gap 2 — guidance is always loaded, never progressive

This is the more interesting difference, and it is the exact thing the Pi
screenshot is advertising.

OpenSRE attaches skill text to the tool description at registry load:

description=f"{tool.description}\n\nWorkflow guidance:\n{guidance}"

capped at 2400 characters per tool. So every attached skill's text sits in the
prompt on every turn, relevant or not. Add ten team skills and you have added
a permanent context cost to every conversation, whether the topic comes up or not.

Pi's model loads the file when the description matches or when the user asks for
it by name. OpenSRE already has the primitive for this — the skill_view action
tool reads a skill on demand — but the attachment path does not use it.

Worth noting the mechanism half-anticipates this: skills can set
disable_model_invocation, so "not always attached" is already a concept.

Questions this discussion is for

• Where should a team skill live? A user directory (~/.opensre/skills/), a
  project directory next to the code being operated, a git repo the team shares,
  or a pip-installable package? Each has different answers for review, versioning,
  and trust.
• Attached or on demand? Keep baking guidance into descriptions, move to
  load-on-match like Pi, or both — product skills attached, team skills
  on demand? This decides whether ten team skills are free or expensive.
• How does the agent choose? Pi matches on the description line. OpenSRE
  binds with an explicit tools: list. Description-matching scales to skills that
  are not about one tool ("how we do postmortems"); tools: is more precise.
  Do we need both?
• What may a skill do? Right now a skill is prose that shapes tool choice. Is
  that the boundary, or should a team skill be able to declare a preferred tool
  order, a required approval, or a forbidden action?
• Trust and review. A skill is instructions the model follows. A team skill
  loaded from a shared repo is a supply-chain surface — who reviews it, and does
  it need a different trust level from an in-tree one?
• Does this overlap with out-of-tree plugins? There is separate interest in
  loading tools from pip packages via entry points. Team skills have the same
  discovery problem. One mechanism or two?

What would help most

If your team has a vendor you use in a specific way — what would you write in the
skill? A real example beats a general mechanism, and one concrete file is enough
to test whether the format, the discovery, and the loading model actually fit.

[YauhenBichel]

Duplicate of #5671 — identical body, posted by a second run of the same script #5671.

Posted twice by a re-run of the discussion script; the bodies are identical.
Closing this copy so the conversation stays in one place.