Best practices for shared team agents

A shared agent speaks for your team in other people’s WispOS. The answers carry your team’s name and yours. These practices keep them right.

Scope it to one team’s subject

One agent, one subject that one team owns: “classroom policy”, “the expense process”, “how to deploy our app”. Narrow agents route cleanly and answer well. A “knows everything about the company” agent routes on everything, ties with every other agent, and answers vaguely.

If you have two subjects owned by two teams, publish two agents.

Write knowledge it can quote

The agent answers only from knowledge/. Write those files for a reader who will quote them:

• One topic per file, with a clear name: late-work.md, not notes-final-2.md. File names show up as sources.
• Headings people would search for. “Late work”, “Make-up tests”, “Phones in class”.
• The rule first, then the detail. “Late work loses 10% per school day, to a floor of 50%.” Then the exceptions.
• Dates and versions in the text. “2026-27 school year.” An answer that says when the rule is from is an answer people can trust.
• No secrets. Everyone who can ask can effectively read every file. Keep keys, passwords and personal data out of the repo entirely.

Tell it what not to do

In PROMPT.md, say what the agent should do when the files don’t cover a question: say so and point to a person or office. An agent that admits a gap is worth more than one that guesses. For example:

If the files don’t answer it, say “The policy doesn’t cover that” and suggest asking the Education office. Don’t guess and don’t generalise from other districts.

Pick topics that route well

• Use the phrases people actually type. “late work”, “phones in class”, “expense report”. Two-word phrases count double, so they route on their own.
• Avoid generic single words like “policy”, “help” or “question”. They match everything and cause ties with other agents.
• Test the routing. Ask the questions you expect, in different words, and check the agent answered. Remember people can always address it by name.

Always cite

WispOS already asks your agent to end every answer with a Sources: line, and shows those files with the answer. Don’t tell it otherwise in PROMPT.md. People check sources; an answer without them reads as a guess.

Choose the smallest model that answers well

sonnet is the default and right for most agents. haiku is faster and lighter on everyone’s plan for simple lookups. Use opus only if your subject needs real reasoning across many files. Each question runs on the asker’s own AI plan, so a lighter model is a kindness.

Keep it current

Answers are only as good as the files. Give the repo an owner (it’s on the card for a reason), update it when the rules change, and remember that a push reaches everyone on their next question.

Control who can ask

askers is checked on every question, against the asker’s git email. Use "@yourcompany.com" for internal agents. The repository’s own access is the stronger gate: someone who can’t clone the repo can’t install the agent.

Checklist

• One subject, owned by the team named on the card
• An owner who’ll keep it current
• knows uses the real phrases people type, mostly two-word ones
• One topic per knowledge file, with clear headings and dates
• PROMPT.md says what to do when the files don’t cover it
• PROMPT.md doesn’t fight the Sources: line
• No secrets or personal data anywhere in the repo
• Installed from a local folder and tested with real questions before sharing