Words about extensions
- Extension
- Any named, reusable piece of capability or instruction that sits between you and the model. Skills, plugins, memories, and MCP connectors are the four kinds you'll work with this module.
- One-off prompt
- An instruction you type in chat, the agent runs it, the session ends, the instruction is gone. Most of what you do in any course module lives here and should stay here.
- Saved prompt / prompt snippet
- A prompt you keep in a notes file or snippet manager and paste at the start of each session. Persists across sessions because you moved it; the agent doesn't know it exists until pasted.
- Memory
- A short fact the agent carries across sessions — "I prefer concise responses," "skip the preamble on weekly reports." Tunes how the agent talks to you. Does not add a new job the agent can do; that's a skill.
- Skill
- A named, described, durable piece of capability stored as a folder the agent consults on its own. Has a trigger (a description the agent reads to decide whether this skill applies) and a body (the instructions, examples, scripts, etc.). The headline Module 7 object.
- Plugin
- A bundle of one or more skills, plus optional tool wiring and optional commands, packaged as a single installable unit. Different from a skill because it's a group — a shareable, removable bundle that travels as one unit.
- MCP connector
- A tool that gives agents new verbs — a way to talk to Slack, Google Calendar, a database, an API. Skills and plugins can use MCP connectors. The MCP is the layer where new capabilities enter the system; skills and plugins are how those capabilities get used.
- Extension register
- A single table where every authored or installed extension on your machine has a row. Columns: name, type, what it does, where it lives, invocation, audience, budget/model, next review date, keep-or-retire condition, status. The rail that prevents the pile-up failure mode.
Words about authoring skills
- SKILL.md
- The required file inside any Claude Code skill folder. Has two sections: the YAML frontmatter (structured fields the agent reads to decide whether to fire the skill) and the Markdown body (instructions for the agent to follow once the skill fires).
- Frontmatter
- A YAML block at the top of SKILL.md (or any Markdown file), bounded by --- lines. Carries structured fields the agent reads before reading the body.
- YAML
- A labeled-text format like JSON but with simpler punctuation. Used for skill frontmatter and many config files. Keys and values written as key: value; lists use - markers; indentation is meaningful.
- name field
- A short, kebab-cased name for the skill (e.g., research-sweep). Used as the skill's identifier in registries and traces.
- description field
- The string the agent reads to decide whether to fire this skill. The most important field in the file. Should be specific (what the skill does), inclusive (the phrases that should invoke it), and exclusive (the adjacent cases it does not cover) — in that order.
- model field
- Optional frontmatter field naming the model family the skill prefers (haiku, sonnet, opus). If omitted, the skill uses the parent session's model.
- allowed-tools field
- Optional frontmatter field listing the tools the skill is permitted to use. If omitted, the skill inherits the parent session's full tool surface. Use to narrow a skill's permissions — e.g., a research skill that should never run shell commands gets allowed-tools without Bash.
- Description-as-classifier
- The headline Module 7 insight: the description field is not decoration; it is the input to a classifier the agent uses to decide which skill to fire. Three failure modes — vague, overfit, triggerless — and one pattern that fixes all three: descriptive + inclusive + exclusive.
- Vague description (failure mode 1)
- A description so generic that the agent never reaches for the skill. "Helps with research." Fix: add specificity about inputs and outputs.
- Overfit description (failure mode 2)
- A description so broad that the skill fires on adjacent wrong work. "Runs when the user talks about research." Fix: add an explicit exclusion block.
- Triggerless description (failure mode 3)
- A description that describes the output but doesn't tell the agent when to use the skill. Fix: add an explicit Use when the user asks for... list.
- Trigger / triggering phrase
- A specific phrase that should invoke the skill. Listed in the description field. "Use when the user asks for: a research sweep, source triangulation, a sources.md, a competitive landscape, or a fabrication check."
- Three-round tuning loop
- The discipline for taking a skill from authored to ready: Round 1 (trigger test — does it fire on the right requests and not the wrong ones?), Round 2 (body test — does it produce outputs matching the contract?), Round 3 (scope test — how does it handle edge cases?). Each round produces a dated CHANGELOG.md entry.
- Output contract
- The section of a skill body that names what the skill produces — file names, section headings, required fields. The thing tests verify against.
- Failure modes section
- The body section students most often skip and most often regret skipping. Names the predictable ways the skill can go wrong and what the skill should do when each occurs.
- Two real-use traces
- The Module 7 capstone requirement that a skill have been invoked successfully on at least two real requests (not just tuning tests) before it gets frozen.
Words about plugins
- Plugin manifest
- The file at the root of a plugin folder that names the plugin and enumerates what it contains. Seven fields: name, version, description, author, bundled skills, MCP connectors, permission surface.
- Permission surface
- The union of what a plugin's bundled skills can read, write, and send, plus what credentials they inherit. Named explicitly in the manifest so the installer can audit before approving.
- SECURITY.md
- A file at the plugin root that answers the seven-question security questionnaire. Lives alongside the manifest. The audit document for installer-side review.
- Security questionnaire (S1–S7)
- Seven questions every plugin you author must answer before shipping: S1 (what does it do?), S2 (what tools does it grant?), S3 (what data can it read?), S4 (what can it send/post/write?), S5 (how does it handle credentials?), S6 (what does installing it remove from the user's control?), S7 (what's the update posture?).
- Least-privilege moves
- Three design moves that narrow a plugin's permission surface: prefer reading to writing; scope reads narrowly; don't wire MCP connectors you aren't using.
- Three bundling conditions
- A plugin (vs. a loose skill) is the right shape when one of three apply: capabilities share scope, share an install/uninstall story, or will be shared with someone else. If none applies, stay with a loose skill — Module 7 asks you to build a plugin anyway as a pedagogical drill.
- Clean uninstall
- Required for any Module 7 plugin: uninstalling must leave no orphan files, no lingering credentials, no skill entries in the registry. Tested explicitly before freeze.
Words about evaluating extensions (Lesson 7.2)
- Off-the-shelf-first heuristic
- When a working, well-maintained extension does the job, prefer it to authoring. Author only when one of four conditions applies: no off-the-shelf option exists; every option fails the audit; your need is materially more specific; or you're authoring for pedagogical reasons (Module 7's case).
- Minimum viable audit
- Five questions every candidate extension must pass before it enters the register: Q1 (what does it do?), Q2 (what tools does it grant?), Q3 (what data can it read?), Q4 (what can it send?), Q5 (how does it handle credentials?). Answers live in the register row.
- Outbound decision matrix (Options A–E)
- The Module 6 audience = only you rule applied to install-time. A = clean audit (no outbound, install). B = drafts-only mode available, install with it enabled. C = platform-scoped (the underlying provider blocks send via the OAuth scope). D = decline because no narrowing is possible. E = conscious override with a 30-day review and four required register fields.
- Conscious override
- An intentional exception to audience = only you — installing a send-capable extension for a specific, time-bound reason. Requires four register fields: the reason, what may be sent and to whom, a 30-day review date, and the condition under which the decision reverses.
- Manifest / description / changelog
- The three artifacts you read on every candidate. Manifest = what the plugin lists about itself. Description = what the agent reads to decide whether to fire it. Changelog = how it has changed over time.
- Permission widening
- A new version of an extension that grants more capability than the previous version (a new outbound verb, a wider read scope, a new MCP connector). The most important changelog signal to act on; requires a fresh audit, not an implicit approval.
Words about hygiene and retirement (Lesson 7.5)
- Pile-up failure mode
- The predictable failure without a register: extensions accumulate, lose names, overlap, drift, and silently degrade the workflow. The register exists to surface and prevent this.
- Three kinds of drift
- Tool drift (the underlying model, MCP, or data source has changed). Work drift (your work has moved; the description no longer matches). Ecosystem drift (a better option has matured in the marketplace).
- Hygiene ritual
- A quarterly five-step sweep across every register row: (1) read descriptions aloud, (2) check permissions vs. audit, (3) check review dates, (4) look for collisions, (5) decide per row.
- Per-row decision (keep / refactor / replace / retire)
- The four outcomes of the hygiene ritual. Keep = the row earns its place; set a new review date. Refactor = the row earns its place but description or body needs tightening; schedule the work. Replace = a better option has matured; install the new, retire the old. Retire = the row no longer earns its place; uninstall, revoke credentials, archive.
- Five retirement signals
- Reasons a row should retire: (1) use has stopped (30–60+ days without invocation); (2) the underlying tool has changed; (3) the description no longer matches your work; (4) the permission surface has widened; (5) a better option has matured.
- Sharing posture (A / B / C)
- What to do with extensions you authored. A = don't share (the recommended default for first-year authors). B = private share with a named, small audience (family member, co-op classmate). C = public share (marketplace, open repo) — high bar; requires the extension to have survived multiple hygiene cycles.
- Module 7 retrospective
- A 300–500 word section in my-first-loop.md answering four questions at the end of the module: what did I ship? what surprised me? what would I build next? what did I learn about description-as-classifier?
Words about file structure
- ~/.claude/skills/<name>/
- User-scoped Claude Code skill location — available to every project the user opens.
- <project>/.claude/skills/<name>/
- Project-scoped Claude Code skill location — available only when Claude Code is running against this project.
- <plugin-root>/skills/<name>/
- Skill bundled inside a plugin.
- /capstone/extension-register-v1-draft.md
- The working register file you build across Module 7. Becomes /capstone/extension-register-v1.md at freeze.
- /capstone/custom-skill-v1/
- Frozen folder with SKILL.md, README.md, CHANGELOG.md, and traces/. Module 7 capstone artifact 2 of 3.
- /capstone/custom-plugin-v1/
- Frozen folder with manifest, skills/, README.md, SECURITY.md, CHANGELOG.md, and traces/. Module 7 capstone artifact 3 of 3.