creating-agents-and-skills

Skill: creating-agents-and-skills

The governance gate for extending this kit. Goal: people add capabilities only when they help, build them with quality, and every installed tool folder stays in sync.

Follow three phases in order: Decide → Author → Propagate.

---

Phase 1 — Decide what (if anything) to build

Run these gates before creating anything. If a gate says stop, explain why and stop.

• LLM-native? → don't create. If a capable model already does this well ("write clean code", "use CTEs", "explain this function"), no artifact is needed. Just do the task.
• Narrow knowledge / a tool / a format / a checklist / a script? → make a SKILL. This is the default for almost everything: a team naming standard, a framework's rules, a validation procedure. Skills auto-activate by description and cost almost nothing until used.
• A repeatable multi-step procedure the user invokes? → make a WORKFLOW (slash command).
• Overlaps an existing skill/agent? → extend it, don't add a near-duplicate.

The agent-survival rule

An agent is allowed only if it imposes something the model cannot impose on itself:

1. Restricted tools — a frontmatter tools list that removes capabilities (e.g. read-only).
2. Independent review — fresh context, without the author's reasoning.
3. A different model than the main session.
4. An automatic trigger that fires without the user asking.

If none applies, it is a skill: "a persona with a domain" is not a reason. Domain knowledge belongs in a skill, or is dropped if the model already knows it. Agents must not hand off to other agents.

Default to a skill. Recommend an agent only if you can name which of the four criteria it satisfies, and say so in the agent's description or body.

---

Phase 2 — Author it lean

Write only domain/org-specific signal. No filler, no restating what the model knows. English.

Agent — .agent/agents/<name>.md (example: pbi-visual-reviewer, a read-only reviewer):

---
name: pbi-visual-reviewer
description: Independently reviews Power BI report screenshots against the request and the PBIR folder; PASS/FAIL per page and visual. Use after a report change has been reloaded and screenshotted.
tools: Read, Grep, Glob        # the restriction that justifies the agent: no Bash/Edit/Write
model: inherit
---
# PBI Visual Reviewer
<1–2 line identity> → fixed checklist → output format (PASS/FAIL). No handoffs.

tools is the field that matters: list only what the agent needs.