{"slug":"create-team-skill","title":"create-team-skill","summary":"Authoring guide for creating a new skill in this plugin, matching the conventions the existing skills already use. Establishes the three decisions every skill must make before any prose is written: how it is invoked (entry point vs building block), how it acquires its input, and ","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-28T19:35:02.606901Z","repo":{"url":"https://github.com/bostonaholic/team","stars":11,"forks":2,"license":"MIT","updatedAt":"2026-09-29T13:52:37Z"},"bodyHtml":"<hr>\n<h2>name: create-team-skill\ndescription: |\nAuthoring guide for creating a new skill in this plugin, matching the conventions\nthe existing skills already use. Establishes the three decisions every skill must\nmake before any prose is written: how it is invoked (entry point vs building block),\nhow it acquires its input, and how it manages the context window.\nDo NOT hand-write a SKILL.md directly. Trigger on \"create a skill\",\n\"add a new skill\", \"scaffold a skill\", \"write a SKILL.md\", or a description of\nnew skill functionality the user wants to build.</h2>\n<h1>Creating a new Team skill</h1>\n<p>This is the dev-workspace guide for authoring a skill in this plugin. Follow it so a new\nskill matches the conventions the existing skills already use. A skill is a document the\nagent reads, not a function it calls. Before writing one, make three decisions in order.\nEach has a wrong-by-default failure mode, so decide deliberately rather than copying\nanother skill's wiring.</p>\n<ol>\n<li><strong>Invocation</strong> — is this an entry point (user/model triggers it) or a building\nblock (another skill composes it)? This defines what the skill <em>is</em>.</li>\n<li><strong>Input</strong> — how does it get the thing it operates on? Discover it. Do not demand it.</li>\n<li><strong>Context</strong> — how does it stay inside the window while it runs? Offload, delegate,\nsearch.</li>\n</ol>\n<h2>Shared convention: the artifacts directory</h2>\n<p>Every skill that hands off uses one durable, repo-local directory for what it would\notherwise \"keep in the conversation\". That covers inputs passed between skills,\ncheckpoints, and findings. In this repo that directory is <strong><code>docs/plans/&lt;id&gt;/</code></strong>, where\n<code>&lt;id&gt;</code> is <code>&lt;TICKET&gt;-&lt;topic&gt;</code> or <code>&lt;YYYY-MM-DD&gt;-&lt;topic&gt;</code>. This guide calls it\n<code>&lt;ARTIFACTS&gt;</code>. Producers write there. Consumers discover and read from there. The\nagreement matters more than the path: every handoff uses the same convention so skills\nstay decoupled.</p>\n<hr>\n<h2>Part 1 — Invocation surface</h2>\n<p>The load-bearing rule: <strong>composition never goes through the skill-invocation tool.</strong>\nThe invocation tool is for the top surface only — a user typing the skill, or the model\nauto-invoking it by intent. When one skill pulls in another, it <em>reads that skill's file</em>\nor <em>spawns a subagent</em>.</p>\n<p><strong>First, make the invocation-surface decision — do not skip it.</strong> Classify the skill\ninto exactly one of three buckets, then carry the verdict into the frontmatter:</p>\n<table>\n<thead>\n<tr>\n<th>Bucket</th>\n<th>What it means</th>\n<th>Frontmatter</th>\n<th>Examples</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><strong>Both</strong> (default for anything a user might run)</td>\n<td>A user triggers it by intent <strong>and</strong> the model/another skill may pull it in</td>\n<td>leave <code>user-invocable</code> unset (default)</td>\n<td><code>team</code>, <code>team-*</code>, <code>code-review</code></td>\n</tr>\n<tr>\n<td><strong>User-invocable only</strong></td>\n<td>A user must trigger it explicitly. The model must NOT auto-fire it</td>\n<td><code>disable-model-invocation: true</code></td>\n<td>irreversible actions: deploy, force-push, destructive cleanup</td>\n</tr>\n<tr>\n<td><strong>Model-invocable only</strong> (pure building block)</td>\n<td>Reference material loaded by agents / read by path. A <code>/&lt;skill&gt;</code> command is meaningless to users</td>\n<td><code>user-invocable: false</code></td>\n<td>every pure methodology skill (<code>qrspi-workflow</code>, <code>solid-principles</code>, …)</td>\n</tr>\n</tbody>\n</table>\n<p>Decide with these tests, in order:</p>\n<ol>\n<li><strong>Is it irreversible or side-effecting</strong> (deploys, pushes, deletes, sends)? →\n<strong>User-invocable only</strong>. Never let the model auto-trigger it.</li>\n<li><strong>Is it purely reference material</strong> — methodology, conventions, a protocol another\nagent reads — with no standalone \"do this now\" meaning for a user? →\n<strong>Model-invocable only</strong>.</li>\n<li><strong>Would a user plausibly type <code>/&lt;skill&gt;</code> to run it as an action</strong>, even if agents also\ncompose it? → <strong>Both</strong> (the default, do not over-restrict).</li>\n</ol>\n<p><strong>If you cannot place the skill in one bucket with high confidence, STOP and ask the user</strong>\nthrough <code>AskUserQuestion</code> (header <code>Invocation</code>), with the three buckets as options. State\nyour leaning and why, and let them confirm. Do not silently guess. The wrong choice\neither clutters the menu or hides a command users expect. Once decided, wire the\nsurface(s) per §1A / §1B below and set the frontmatter from the table above.</p>\n<h3>§1A — Wire it as an entry point</h3>\n<ol>\n<li><strong>Write the description as a router.</strong> Lead with WHAT it does, then end with the\ntrigger sentence naming the phrases and the slash name that should fire it:\n<pre><code>description: |\n  &lt;one line: what this does&gt;.\n  Trigger on \"&lt;phrase&gt;\", \"&lt;phrase&gt;\", or \"/&lt;name&gt;\".\n</code></pre>\nSpecific intents + example phrases = reliable triggering. Vague text = mis-routing.</li>\n<li><strong>Add one line to the routing map</strong> in your standing agent instructions — in this\nrepo that's the Entry Points table in <code>AGENTS.md</code>: <code>- &lt;user intent&gt; → invoke /&lt;skill&gt;</code>. This is guidance the agent reads, not a code gate, so keep it in sync\nwith the description.</li>\n<li><strong>Side-effecting or irreversible skills MUST guard.</strong> If the skill commits, pushes,\nopens a PR, moves a ticket, merges, deploys, or deletes, replace the plain\n<code>Trigger on</code> carrier with shipit-style explicit-intent guard wording (\"Invoke ONLY\non explicit … intent — … never infer …\"). Word its routing-map line with that same\nexplicit intent, so the map never invites the skill on a plain request — <code>team-fix</code>\nis listed as a command but reached only on stated pipeline intent, never on \"fix\nthis bug\". The description still carries the quoted phrases and the <code>/&lt;name&gt;</code> — the trigger\ntest has no opt-out, but it checks phrase presence only: no test checks the guard\nwording, so it is YOUR responsibility, and its absence on a side-effecting skill\nis a review-blocking defect. If your host honors a hard opt-out flag (e.g.\n<code>disable-model-invocation</code>), set it — but on hosts that ignore it, the description\nis the only control.</li>\n</ol>\n<h3>§1B — Wire it as a building block</h3>\n<p>Composability is never declared — any skill file can be composed. What you choose is HOW\na parent pulls it in, by if the parent needs coordination or isolation:</p>\n<ul>\n<li><p><strong>(a) Inline</strong> — parent reads this skill's file and follows it. For sequential work\nthe parent coordinates and weaves into one result. Parent instruction reads:</p>\n<blockquote>\n<p>\"Follow </p>\n</blockquote>\n</li>\n<li><p><strong>(b) Subagent</strong> — the parent spawns a fresh-context agent to run this. Use it for an\nunbiased perspective, such as adversarial review, or for parallelism, such as N\nvariants or specialists at once. Parent instruction reads:</p>\n<blockquote>\n<p>\"Dispatch as a subagent (fresh context). Launch all N in one message. Return the\nconclusion only.\"\nAuthor this child to be self-contained (it gets a clean window — say what to read up\nfront) and to return a conclusion, not a transcript.</p>\n</blockquote>\n</li>\n<li><p><strong>(d) Prerequisite offer</strong> — parent offers this when input is missing:</p>\n<blockquote>\n<p>\"No </p>\n</blockquote>\n</li>\n</ul>\n<p><strong>Hide it from the slash menu.</strong> A pure building block is reference material, not a user\naction, so a <code>/&lt;skill&gt;</code> command for it is meaningless. Set <code>user-invocable: false</code> in its\nfrontmatter to keep it out of the <code>/</code> menu. The field governs <em>menu visibility only</em>. It\ndoes not affect read-and-follow or subagent composition (those reach the file directly),\nand the model can still auto-load it when relevant. In this repo every pure methodology\nskill sets this. Entry-point skills leave it unset so they register as slash commands. (A\nskill wired as <em>both</em> surfaces stays user-invocable — do not set it. <code>code-review</code> is the\nrepo's standing example: it is loaded as composed methodology by the review agents yet is\nalso a direct user action (\"review this diff\"). It is the only methodology skill kept\nuser-invocable.)</p>\n<h3>Invocation invariants</h3>\n<ul>\n<li>Never compose through the skill-invocation tool. Composition = read-and-follow OR subagent.</li>\n<li>Heavy or adversarial sub-work → subagent (keeps the parent lean and unbiased).\nSequential/coordinated sub-work → inline.</li>\n<li>A skill can serve both surfaces. Just make its description trigger correctly AND its\nsections survive being inlined/subagented.</li>\n<li>Do not auto-trigger irreversible skills.</li>\n<li>Pure building block → <code>user-invocable: false</code> (out of the slash menu, still loadable).</li>\n</ul>\n<hr>\n<h2>Part 2 — Input acquisition</h2>\n<p>Skills DISCOVER their input from conventions and only ask the user as a fallback. Pick\nthe archetype that matches the input type. Default to §2A for documents.</p>\n<table>\n<thead>\n<tr>\n<th>If the skill operates on...</th>\n<th>Use</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>A plan / design / spec document</td>\n<td><strong>§2A — convention-based discovery</strong> (default)</td>\n</tr>\n<tr>\n<td>The current branch's code changes</td>\n<td><strong>§2B — branch-diff detection</strong></td>\n</tr>\n<tr>\n<td>A short scalar (URL, time window, ID)</td>\n<td><strong>§2C — positional args + flags</strong></td>\n</tr>\n<tr>\n<td>A problem the user must describe / scope</td>\n<td><strong>§2D — ask-first</strong></td>\n</tr>\n</tbody>\n</table>\n<h3>§2A — Convention-based document discovery (archetype A)</h3>\n<p>The skill takes an OPTIONAL artifact-directory arg and DISCOVERS it when omitted.\nDiscovery is the front door, and the arg is only an override. Declare the hint in\nfrontmatter and read <code>$ARGUMENTS</code>:</p>\n<pre><code>argument-hint: \"[docs/plans/&lt;id&gt;/]\"\n</code></pre>\n<p>Resolve the directory with the canonical <strong>three-tier</strong> block:</p>\n<ol>\n<li><strong>Explicit</strong> — <code>$ARGUMENTS</code> names an existing dir → use it verbatim.</li>\n<li><strong>Discover</strong> — newest-mtime dir under <code>docs/plans/</code> that matches <code>ID_RE</code> and holds\nthis skill's predecessor artifact (filter by <code>ID_RE</code> / <code>PHASE_FILES</code>). Announce the\nauto-picked directory before proceeding — never pick a topic silently.</li>\n<li><strong>None found</strong> — fall to the empty case below. Do not error.</li>\n</ol>\n<p>Do NOT hand-roll this block. Copy it <strong>verbatim</strong> from an existing archetype-A skill\n(e.g. <code>skills/team-research/SKILL.md</code>) — the dev gate\n<code>.claude/scripts/check-discovery-consistency.sh</code> asserts byte-identity across every\narchetype-A skill, so any variant fails the suite. Run it as a single bash call (an\nagent thread resets cwd between calls).</p>\n<ul>\n<li>If a directory resolves: read the predecessor artifact from it. Treat it as source of\ntruth for problem, constraints, approach.</li>\n<li>Empty case (REQUIRED): do NOT error. Fire <code>AskUserQuestion</code> (header <code>Setup</code>) with two\nlabeled options. <strong>Run the producer</strong> runs <code>/team-&lt;producer&gt;</code> to create the missing\nartifact. <strong>Give a path</strong> lets the user supply <code>docs/plans/&lt;id&gt;/</code>.</li>\n</ul>\n<h3>§2B — Branch-diff detection (code review)</h3>\n<p>No argument. Detect the base branch through a fallback chain, then diff:</p>\n<pre><code>BASE=$(gh pr view --json baseRefName -q .baseRefName 2&gt;/dev/null)\n[ -z \"$BASE\" ] &amp;&amp; BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2&gt;/dev/null | sed 's@^refs/remotes/origin/@@')\n[ -z \"$BASE\" ] &amp;&amp; BASE=main\ngit diff \"origin/$BASE\"...HEAD\n</code></pre>\n<p>Never hardcode the base branch without the chain above it.</p>\n<h3>§2C — Positional args + flags (scalars only)</h3>\n<p>Reserve arguments for scalars, never documents. Parse with sensible defaults (<code>/skill 7d</code>\n→ default <code>7d</code>, <code>/skill &lt;url&gt; --quick</code>). Auto-discover when a flag is omitted. Always\nstate the default you chose.</p>\n<h3>§2D — Ask-first</h3>\n<p>Start from what the user already typed. Auto-discover repo context (search, diff,\nREADME). Ask ONE question at a time, only for genuine gaps. Do not interrogate when the\nanswer is already on disk. (In this repo, <code>/team-question</code> is the ask-first producer that\nseeds <code>docs/plans/&lt;id&gt;/</code> for the archetype-A consumers downstream.)</p>\n<h3>Input invariants</h3>\n<ul>\n<li>Discover before you demand. A question is the fallback, not the front door (except §2D).</li>\n<li>The empty/not-found path uses <code>AskUserQuestion</code> to offer a producer or ask for a\npath — it never throws.</li>\n<li>Each shell block is its own process — recompute derived vars. Do not rely on persistence.</li>\n<li>An argument carries a scalar (URL/window/ID) or an OPTIONAL artifact-dir path that\ndiscovery resolves when omitted — never the document's contents.</li>\n<li><strong>Never write a <code>$</code> immediately followed by a digit anywhere in a SKILL.md.</strong> The\nloader reads it as an argument placeholder and substitutes the caller's Nth argument,\nwhich silently rewrites awk record/field variables and shell positional parameters in\nyour snippets. Read a line into a named variable and match it with <code>case</code>, or reach\nfor <code>cut</code>/<code>sed</code>, instead. The documented backslash escape is not enough: a host that\nsubstitutes the placeholder without implementing the escape leaves the backslash in\nthe command. <code>tests/regression-skill-body-positional-args.test.ts</code> enforces this.</li>\n</ul>\n<hr>\n<h2>Part 3 — Context discipline</h2>\n<p>There are two token economies. Treat them oppositely.</p>\n<ol>\n<li><strong>The payload</strong> (these instructions, the skill text) is cached and amortized. Do NOT\ncompress it for size's sake — completeness here is cheap. A long, complete skill\nbeats a terse, ambiguous one.</li>\n<li><strong>The working set</strong> (everything READ and GENERATED at runtime) is uncached and grows\nwithout bound. This is what you ration. Prefer to never pull bytes into the window\nover summarizing them after the fact.</li>\n</ol>\n<p>Be generous with the payload, ruthless with the working set. Execution rules, in order:</p>\n<ol>\n<li><strong>Offload state to disk.</strong> Write decisions, plans, and findings to <code>&lt;ARTIFACTS&gt;/*.md</code>.\nRead back on demand instead of keeping them resident. When a long task risks losing\nstate, checkpoint to <code>&lt;ARTIFACTS&gt;/checkpoint-&lt;timestamp&gt;.md</code> (branch, done,\ndecisions, remaining, open questions) — append-only, never overwrite. A fresh window\nresumes from the file, not from replayed history.</li>\n<li><strong>Delegate heavy reading to subagents.</strong> Broad fan-out (sweeping many files, comparing\nvariants, adversarial review) goes to a subagent that burns ITS window and returns\nonly the conclusion. Launch independent subagents in parallel (one message). Once you\ndelegate a search, don't also run it yourself.</li>\n<li><strong>Search, do not read whole files.</strong> For where/what/which questions, use semantic\nsearch if available, else targeted grep/glob; pull excerpts and line ranges. Don't\n<code>cat</code> a large file to \"see what's there.\" Don't re-read a file you just edited to\nmake sure it.</li>\n<li><strong>Reference, do not copy.</strong> When building inputs for a sub-task or test, extract the\nrelevant lines — never paste a 1000+ line file. Large irrelevant context causes\ntimeouts and multi-x slowdowns, not just cost.</li>\n</ol>\n<p>Gate yourself before acting:</p>\n<ul>\n<li>Before reading: \"Whole file or a section? Can a search answer this? Should a subagent read it?\"</li>\n<li>Before spawning: \"Broad enough to delegate? Can these run in parallel?\"</li>\n<li>Before continuing a long task: \"Is there state I'd lose on compaction? Checkpoint it now.\"</li>\n</ul>\n<h3>Context anti-patterns</h3>\n<ul>\n<li>Reading whole files to 'get oriented'.</li>\n<li>Keeping a doc/plan/findings resident across many turns instead of writing to\n<code>&lt;ARTIFACTS&gt;</code> and re-reading on demand.</li>\n<li>Pasting large files into sub-task prompts or fixtures.</li>\n<li>Doing a broad multi-file sweep inline when a subagent could return just the answer.</li>\n<li>Compressing your own instructions to \"save tokens\" — that is the cached payload, not\nwhere the cost is.</li>\n</ul>\n<hr>\n<h2>Acceptance checklist (verify before the skill is done)</h2>\n<p>Invocation</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Invocation surface decided — <strong>both</strong> / <strong>user-invocable only</strong> / <strong>model-invocable only</strong> — with high confidence. If not, asked the user through <code>AskUserQuestion</code>.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Frontmatter matches the verdict: both → neither flag. User-only → <code>disable-model-invocation: true</code>. Model-only → <code>user-invocable: false</code>.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Only the intended path(s) wired (entry point §1A, building block §1B, or both).</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Entry point: description has WHAT + explicit trigger intents/phrases. Added to routing map.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Building block: chose inline (sequential) vs subagent (isolated/parallel) deliberately.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> If subagented: self-contained, returns a conclusion not a transcript. If inlined: headed, independently-runnable sections.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> No skill invokes another through the skill-invocation tool.</li>\n</ul>\n<p>Input</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Correct archetype chosen (default §2A for documents).</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Archetype-A: <code>argument-hint</code> declared. Discovery block copied verbatim from an\nexisting skill (e.g. team-research), not hand-rolled — the dev consistency gate\nenforces byte-identity.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Discovery runs before any question (except §2D). An auto-picked topic is announced.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Empty/not-found path uses <code>AskUserQuestion</code> (run producer / give path) — never throws.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Base branch (if used) through the fallback chain, no bare <code>main</code>. Args carry a\nscalar or optional artifact-dir path, never document contents.</li>\n</ul>\n<p>Context</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> State offloaded to <code>&lt;ARTIFACTS&gt;</code>. Long tasks checkpoint.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Heavy/broad reading delegated to subagents. Conclusions returned, not transcripts.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Searches/excerpts over whole-file reads. No copying large files into sub-tasks.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> Payload left complete (not compressed for size). Working set kept lean.</li>\n</ul>\n","files":[{"path":"SKILL.md","sizeBytes":7457,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-29T20:58:27.304633Z","sha256":"737BCCA818FFD268CB2A38988E1EEDF280FB4EF03C5AEF5F65008527CEDAD15A","sizeBytes":3501},"review":null,"source":{"repositoryUrl":"https://github.com/bostonaholic/team","path":".claude/skills/create-team-skill","license":"MIT","commit":"6c69bd8ca8dd43fbcb27bef5f02180b07f3fd3eb","subtreeSha":"EC78EB5B30970454857D51284238D3FAF9014160BFFB413FC23232BD95F25AE8","lastSyncedAt":"2026-09-29T20:56:15.880837Z"},"reviewedAt":"2026-09-29T20:59:26.753285Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/bostonaholic/team/tree/main/.claude/skills/create-team-skill"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install bostonaholic-team@llmmart"},{"target":"git","command":"git clone https://github.com/bostonaholic/team.git"}]}