Projects and Skills — Reusable Claude

You paste the same block of context into every new chat — the same background about the codebase, the same style constraints, the same definition of "done." Claude gives you a fresh answer, you move on, and the next session starts from zero again. A Project ends that loop.

What a Project actually is

A Project is a working set — three things held together across every conversation inside it: a system prompt that tells Claude who it is and what the rules are, a set of attached files that contain the knowledge it needs, and a shared conversation history that accumulates context over time.

Open a new conversation inside a Project and Claude already knows the standing instructions and the attached material. You do not re-paste. You do not re-establish constraints. You start at the work.

The mechanism is straightforward: every time a conversation opens inside a Project, Claude's context window is pre-filled with the system prompt and the full text of every attached file before your first message arrives. The history of prior conversations is also available for reference. None of this is search or retrieval — it is direct injection into context.

What it is not

A Project is not a folder for organizing past chats. The UI may look like a folder; the function is different. The past conversations are available for reference, but Claude is not "reading through your history" at query time the way a person would. The context it loads is the system prompt and the attached files — not an intelligent summary of everything you've ever said.

A Project is not a saved prompt shortcut. A shortcut fires once and vanishes. A Project's system prompt is active in every conversation, invisibly, before you type.

A Project is not a knowledge base that Claude searches at query time. Every word in your attached files is loaded into the context window at conversation start, whether Claude needs it or not. This is the constraint that matters most when you decide what to attach.

The line between Projects and ad-hoc chats

Ask two questions. Does this task recur — will I do it again next week, or next month? Does it require stable context that doesn't change between sessions?

If both answers are yes: Project. If either answer is no: ad-hoc chat.

Drafting a new blog post on a topic you've never written about: ad-hoc chat. Reviewing blog posts against your editorial guide, every week, for the same publication: Project.

Answering a one-off question about a codebase you're unfamiliar with: ad-hoc chat. Reviewing pull requests against your team's standards, ongoing, for the same repository: Project.

The workflow that benefits from a Project is not just the recurring one — it's the recurring one where the context is stable. A weekly review task where the criteria change every week is still a poor candidate for a Project, because you'd be updating the attached files constantly. The setup cost only pays off when the context holds.

The maintenance cost is real from day one

Every Project has a maintenance cost from the moment you create it. The attached files will go stale. The system prompt was written for the workflow as it existed when you set it up; the workflow will change. The chat history will eventually anchor Claude to assumptions that no longer hold.

This is not a reason to avoid Projects. It is a reason to build them with the minimum viable context — attach only what Claude needs to do the work, not everything you think might be relevant. The leaner the Project, the lower the maintenance cost, and the easier it is to update when the workflow shifts.

If you get stuck

The most common failure: the Project's outputs are not noticeably better than a fresh chat. The cause is almost always a system prompt that describes Claude's role in general terms rather than specifying the output format and quality bar. "You are a helpful assistant for my engineering team" is not a system prompt. "You are a code reviewer. Responses cite the specific line number, name the rule being violated, and suggest the corrected form." is a system prompt. Fix the prompt first before adding more files.

The second most common failure: you attach a large document because it feels comprehensive, and Claude's answers become unfocused — it references sections of the document that aren't relevant to the question. Trim the attached files to the minimum that actually constrains the output. A five-page style guide is better than a fifty-page one if only five pages apply.

Deliverable

Name one workflow in your week where you paste the same context block into every chat. Write one sentence describing the role, one sentence describing the output format, one sentence describing the quality bar. That is the system prompt for your first Project.

Further reading

• "The Bible Reads First" — the system-prompt-as-bible argument: what gets loaded before the first user turn changes everything that follows.

The most common mistake is opening the Projects panel before deciding what the Project is for. You get a blank system prompt, stare at it, write something generic, and end up with a Project that behaves no differently than a fresh chat. Start with the workflow, not the UI.

Pick the workflow first

The workflow that earns a Project is one you can describe in a single sentence before you open Claude. "I review PRs every weekday against our team's style guide." "I draft investor updates from a bullet list of metrics every Monday." "I triage customer support tickets into categories before handing them off."

If you cannot write that sentence, you do not yet know what the Project is for. Do not build it yet.

Once you have the sentence, you have the three things you need to start: what Claude's role is, what material it needs, and what the output looks like.

Step one: write the system prompt

One paragraph. Three components: the role, the output format, and the constraint that defines quality.

A weak system prompt:

You are a technical writing assistant. Help me write documentation.

A functional system prompt:

You are a technical writer for a developer tools company. Every response
is structured as: one-paragraph summary, then a bulleted list of specific
details. Avoid passive voice. Flag any term that is not in the attached
glossary as [UNDEFINED TERM].

The difference is specificity. The functional version tells Claude what to do when it encounters something the instructions didn't anticipate — it has a decision rule (flag undefined terms) rather than a general disposition (be helpful).

Write the system prompt before you attach any files. This forces you to articulate what Claude needs to know versus what it needs to reference. Those are different things.

Step two: attach the right files

Attach only what Claude needs to do the job — a style guide, a template, a list of company-specific terminology. Not everything you have; just the working material.

Each attached file costs context window space in every conversation, whether Claude uses it or not. A Project with ten attached files where Claude only ever needs two is a Project that loads slowly, costs more tokens per conversation, and risks Claude surfacing material from the unused files in ways that are subtly off-target.

The test for whether a file belongs: would Claude give a wrong answer without it? If no, don't attach it.

Step three: test it twice on real work

Run the first real task — not a toy example, an actual instance of the workflow. Read the output against your actual quality bar, not against what you hoped to see.

Find the one thing that was off. Change only the system prompt, not the attached files, to address it. If the issue is that Claude didn't reference the style guide correctly, that is a system prompt problem (you didn't tell it when to consult the guide), not a file problem.

Run the task again. If the second output would satisfy you in production, the Project is ready. If not, identify the second thing that was off and repeat. Do not iterate more than three times before reconsidering whether the workflow is actually a good Project candidate — sometimes the problem is not the configuration, it is that the task requires too much judgment to constrain in a system prompt.

If you get stuck

Claude keeps doing something you told it not to do. Check whether the instruction is in the system prompt or in a conversation message. Instructions in conversation messages are not permanent — they apply to that conversation only. Move behavioral rules to the system prompt.

The output format drifts across conversations. The format rule needs to be in the system prompt, not demonstrated in an example conversation. Claude does not carry format habits from one conversation to the next; it only carries what is in the system prompt and the attached files.

The Project feels slower than a fresh chat. You have probably attached too many large files. Profile this by starting a new conversation inside the Project and checking how long before Claude's first token appears. Trim the attachments to the minimum that maintains output quality.

Cross-reference

l3 covers the conditions under which a Project is the wrong tool — read it before investing heavily in a Project for a workflow that might not warrant one.

Deliverable

A working Project with a system prompt under 150 words and at most two attached files. Run it on one real task before calling it done.

A Project that is wrong for a workflow does not fail loudly. It produces outputs that are slightly off — coherent enough to use, wrong enough to create quiet technical debt. The failure is subtle, which makes it hard to diagnose and easy to attribute to Claude's general capability rather than to a configuration mismatch. Knowing when not to build a Project matters as much as knowing how to build one.

Where Projects work well

Projects earn their cost when three conditions hold simultaneously: the task recurs, the context is stable, and the same quality bar applies every time.

A PR review Project works because the codebase standards do not change between Monday and Friday, the output shape is consistent (citation, rule, corrected form), and you run it multiple times a week. The Project absorbs the setup cost once and returns value on every subsequent run.

A customer support triage Project works because the product categories are stable, the triage criteria are documented, and the classifier output feeds a consistent downstream workflow. The context (triage criteria) is stable, so attaching it makes sense.

Where Projects fail quietly

The first failure mode: attached files go stale faster than you update them. You attach the current API reference. The API changes. Six weeks later, Claude is giving answers based on the old version, and you're debugging a problem that doesn't exist in the current system. The Project is confidently wrong.

This failure is not obvious in the output. Claude doesn't say "I'm using stale data." It reasons from what it has.

The second failure mode: the system prompt was written for a task that has since evolved. You wrote the prompt when the team was two people and review criteria were simple. The team is now eight people and the criteria have bifurcated. The Project still runs — it just applies last year's standards to this year's work.

The third failure mode: the Project constrains creative or exploratory work. Projects encode a format and a stance. If you're using a Project for drafting and the Project has a strong format constraint, you will find yourself fighting the constraint when the work needs to go somewhere unexpected. Exploratory work benefits from a blank slate.

Three situations where a Project is the wrong tool

One-off questions. The overhead of loading a system prompt and attached files is pure waste when you only need Claude once. Ad-hoc chat.

Rapidly changing material. If the document you're referencing updates daily or weekly, attaching it to a Project means you are always operating on a version behind. Fetch the current version at query time instead.

Exploratory or divergent work. Projects encode a format and a stance. Exploration benefits from no prior stance. If the task is "figure out what approach to take," the Project's defined output format is the wrong frame.

The cost of an abandoned Project

A Project you stop maintaining is not neutral. If you or a teammate return to it weeks later, the system prompt describes a workflow that no longer exists, the attached files may be outdated, and the output will be wrong in ways that are not immediately visible. An abandoned Project is a source of confident misinformation. Delete it or archive it explicitly.

The maintenance question

Every time you build a Project, ask: what would make this Project wrong to use? Name the condition. Write it down somewhere you will find it — in the README that lives alongside the Project files, or in the system prompt itself as a dated comment.

If you cannot name the condition under which the Project should be retired, you have not thought clearly enough about what it is for.

If you get stuck

Outputs feel generic despite the system prompt. The system prompt describes a disposition, not a procedure. A disposition ("be rigorous") gives Claude no decision rules when it encounters ambiguity. A procedure ("if the PR touches authentication code, check against the security checklist in the attached file before suggesting approval") gives it a concrete next step. Rewrite the system prompt as a procedure.

The Project works for simple tasks but breaks on complex ones. The attached files are not detailed enough to handle the edge cases the complex tasks expose. Either extend the attached files or accept that the Project is only valid for the simple variant of the task.

Cross-reference

l2 covers the setup steps for a Project that holds its shape. l7 covers the Project-plus-Skills stack that handles complex team workflows — the pattern for when a Project alone is not enough.

Deliverable

Write two sentences for the Project you built in l2: what would make this Project wrong to use, and what is the condition under which you would retire it. If you cannot write both sentences, the Project's scope is not yet clear.

There is a laminated card on the factory floor. It does not explain the philosophy of the assembly process. It says: Step 1. Step 2. If this condition holds, do this instead. Step 3. Check this criterion before moving on. A new worker picks up the card and executes the procedure correctly the first time. The card is not documentation — it is executable instruction.

A "Skill" (the Claude artifact) works the same way. A Skill file is a markdown document that Claude reads at invocation time and acts on — not documentation Claude might reference, but instructions Claude executes.

Why the distinction matters before you write one

If you think of a Skill as documentation, you write it at the wrong level of abstraction. Documentation explains what something does and why. A Skill specifies what to do, in what order, what to check at each step, and what to do when the expected condition does not hold. The specificity is the point.

Here is a documentation sentence: "Pull requests should be reviewed for correctness, style, and security."

Here is a Skill step: "Run git diff main -- '*.py' and list every function whose signature changed. For each changed signature, check whether the corresponding test file in tests/ was also modified. If not, flag it."

The documentation sentence gives Claude a disposition. The Skill step gives Claude an action with an observable completion state. Claude can execute a Skill step. Claude can only approximate a documentation sentence.

How a Skill differs from a system prompt

A system prompt lives in Project settings. It is always active for every conversation in that Project, in the background, before your first message. It shapes Claude's general behavior in that context.

A Skill lives in a .md file — on disk, in a repository, or in a registry. It has these properties a system prompt does not:

• It must be invoked explicitly when the task starts. Claude does not run it automatically.
• It is portable across Projects and across agents. The same Skill file can be installed in any Claude Desktop session, used by any agent that has access to the file.
• It carries a version field in its frontmatter. When the procedure changes, the version increments, and teammates who installed the prior version can see that an update is available.
• It is composable. A Project can invoke multiple Skills. A Skill can reference another Skill.

Think of the system prompt as the standing orders that define the role. Think of a Skill as the procedure card for a specific task within that role. The system prompt says "you are a code reviewer." The Skill says "here is how to execute a security audit of an authentication change."

The sensitive period for writing Skills

There is a moment when a Skill writes itself easily, and you will miss it if you are not watching for it. The moment is: right after you have done a task manually that you expect to do again, while the steps are still fresh, while you can still feel the places where you made a judgment call. That judgment call — the moment where you thought "hmm, it depends on whether X" — is the gotchas section of the Skill. It belongs in the file, not in your head.

If you wait until you have done the task five more times, you will have internalized the procedure and will struggle to articulate the steps explicitly. Write the Skill immediately after the first time you do a task you expect to repeat.

What a Skill file looks like before you open it

A Skill file in a repository looks like this on disk:

# skills/draft-pr-description.md
---
name: draft-pr-description
description: Draft a pull request description from a git diff and a ticket reference
author: Seth Shoultes
version: 1.0.0
---

## Procedure
1. Run `git diff main` and identify the files changed.
...

## Gotchas
- If the diff exceeds 400 lines, ask which files are load-bearing before summarizing.
...

You do not need the Claude UI to read or edit this. It is a text file. You can version it, diff it, review it in a PR, and roll it back. This is what makes Skills shareable in a way that system prompts are not.

If you get stuck

You wrote a Skill and Claude keeps asking clarifying questions when it runs. Every clarifying question is a missing step or an implicit assumption you have not made explicit. After each clarifying question Claude asks, add a step or a gotcha that resolves it. The Skill is done when Claude runs it start-to-finish without stopping.

You wrote a Skill and the output is inconsistent across runs. The procedure has a step with no observable completion state — something like "understand the context" or "review the approach." Replace it with a step that has a concrete action and a concrete check. "Inconsistency" in a Skill is always a procedure problem, not a Claude capability problem.

Deliverable

Before the next lesson: pick one task you do at least twice a month. Write the steps as if you were explaining them to a competent colleague who has never done this exact task but who is not new to the domain. That write-up is the procedure section of your first Skill.

Here is a complete Skill file — a real one, not a toy example — for drafting a pull request description:

# skills/draft-pr-description.md
---
name: draft-pr-description
description: Draft a pull request description from a git diff and ticket number
author: Seth Shoultes
version: 1.0.0
---

## Procedure

1. Run `git diff main` and collect the output.
2. Identify every file changed. Group by: new files, deleted files, modified files.
3. For modified files, identify the nature of each change: logic change, refactor,
   config change, test addition, dependency update.
4. Ask for the ticket number if not provided. Format: PROJECT-1234.
5. Draft the PR description using this structure:
   - ## Summary (2-3 sentences: what changed and why)
   - ## Changes (bulleted list by file group from step 2)
   - ## Testing (what the reviewer should run to verify)
   - ## Ticket (link to the ticket: https://yourtracker.com/PROJECT-1234)
6. Output the draft in a fenced markdown block.

## Gotchas

- If the diff is longer than 400 lines, ask which files are load-bearing before
  summarizing. Do not attempt to summarize a large diff without this anchor.
- If the diff touches authentication or payment code, add a ## Security section
  naming the specific functions that changed.
- If the ticket number contains a hyphen that is not PROJECT-NUMBER format
  (e.g. a branch name), ask for the actual ticket reference.

Read that file. Now you know what a Skill file contains. The three sections — frontmatter, procedure, gotchas — are not arbitrary. Each one does a specific job.

Frontmatter: machine-readable identity

---
name: draft-pr-description
description: Draft a pull request description from a git diff and ticket number
author: Seth Shoultes
version: 1.0.0
---

The name field is how the Skill is invoked. Keep it lowercase, hyphen-separated, specific enough to distinguish from other Skills in the same registry.

The description field is the most important field for teammates. It should be one sentence that tells a colleague exactly when to invoke this Skill and what it produces. "Draft a pull request description from a git diff and ticket number" — concrete inputs, concrete output. "Help with pull requests" — too vague to be useful.

The version field is not decoration. It is the mechanism by which teammates know the Skill has changed. When you update the procedure or the gotchas, increment the version. A Skill at version 1.3.0 that a teammate installed at version 1.0.0 surfaces as an available update in their installation.

Procedure: numbered steps with observable completion

Each step in the procedure has one action and one observable completion state. "Collect the output" is an action. "Group by new files, deleted files, modified files" is the completion state — you know the step is done when you have three groups.

Steps that do not have observable completion states are the source of most Skill failures. "Understand the changes" is not a step. Claude cannot know when it has understood something to a sufficient degree. "List every file changed and identify whether each change is a logic change, refactor, config change, test addition, or dependency update" is a step — Claude can produce a list, you can verify it.

Write each step as if you were explaining it to a colleague who is competent but has never done this exact task. Do not assume they know the output format; specify it. Do not assume they know which edge cases matter; put those in gotchas.

Gotchas: named failure modes with named recoveries

Every Skill has at least two things that go wrong predictably. The gotchas section names them and names the recovery. This is the section that saves time.

"If the diff is longer than 400 lines, ask which files are load-bearing before summarizing." That sentence saves ten minutes every time a large diff arrives, because Claude does not attempt to summarize 400 lines and produce a confident but wrong PR description. It stops, asks, and gets an anchor.

The gotchas section is written from experience — from the first few times you ran the procedure and hit an unexpected condition. If you are writing a Skill before you have run the procedure, your gotchas section will be thin. That is fine. Run the Skill once on a real task, note every place it stumbled, and add those to gotchas before version 1.0.0 ships to teammates.

Testing the Skill you just wrote

Give the file to Claude with the instruction: "Follow this Skill." Watch where it hesitates or asks a clarifying question. Every hesitation is a missing step. Every clarifying question is an implicit assumption you have not made explicit.

Fix those and run it again. The Skill is ready when Claude runs it start-to-finish without stopping, and the output matches what you would have produced manually.

Do not run this test on a toy example. Run it on a real instance of the task. Toy examples do not surface the edge cases that the gotchas section needs to address.

If you get stuck

The output format is inconsistent between runs. The format specification is not in the procedure — it is either vague or absent. Add an explicit output structure to the relevant step. Show the exact section headers, the exact nesting, the exact format for each component.

Claude follows the procedure but skips a step. The step's completion state is implicit. Claude completed what it thought was the intent of the step and moved on. Add an explicit check at the end of the step: "Verify that the output contains X before proceeding."

You added a gotcha but Claude still hits the same failure mode. The gotcha is written as a passive observation rather than an active instruction. "Large diffs can be hard to summarize" is not a gotcha. "If the diff is longer than 400 lines, stop and ask which files are load-bearing before summarizing" is a gotcha — it has a trigger condition and an action.

Cross-reference

l4 covers the mental model that makes Skill writing easier — specifically, the distinction between documentation and executable instruction. If the procedure steps you are writing feel like documentation, return to l4.

Deliverable

A Skill file for one task you actually do, with all three sections complete, tested at least once against a real instance of the task. The test run should be logged: what did Claude do, where did it hesitate, what did you fix.

Further reading

• "The Recipe That Wrote Itself" — what happens when you let the agent write the Skill from a worked example, and why the resulting file holds up better than one you wrote from scratch.

A Skill stored only in your local Claude Desktop installation helps only you. When a teammate needs the same procedure, they rebuild it from scratch — introducing drift, inconsistency, and the quiet cost of every engineer re-solving the same problem. Multiply that cost by the number of recurring tasks your team has. The Skills registry is where that cost is recovered.

The install pattern

Skills are installed into a Claude Desktop session via the Skills panel. A teammate can install a Skill you have published with one command:

npx skills add github:yourorg/skills-repo/draft-pr-description

That command pulls the markdown file, registers it in their local Claude installation, and makes it invocable by name. The Skill runs in their context with their credentials — you are not running anything for them. Their invocation of the Skill uses their git access, their file system, their open conversations. The Skill is the procedure; the execution is theirs.

A real example of this pattern: the Skills published at sethshoultes.com/skills/ (source repo: github.com/sethshoultes/building-with-ai-skills) — install any of them with the same npx skills add command and see the install loop end-to-end.

This separation is important. A Skill is not a shared service. It is a shared procedure. The distinction matters when you think about what belongs in the Skill file versus what belongs in the caller's environment.

Structuring the repository

A Skills repository for a team typically looks like this:

# yourorg/skills-repo
README.md
skills/
  draft-pr-description.md
  incident-report.md
  sprint-retro-prep.md
  triage-support-ticket.md

Each Skill file is a standalone document. No shared dependencies between Skills. No shared configuration files that Skills import. Each Skill must be self-contained, because it will be installed individually and run in isolation.

The README at the root is the entry point for a new teammate. It lists every Skill, its description (copied from the frontmatter), and the install command. A teammate should be able to read the README and know which Skills exist and which one they need without opening any individual Skill file.

Versioning

The version field in the frontmatter is not decoration. The install command registers not just the file but the version. When you update a Skill and increment the version, teammates who installed the previous version see an update available in their Skills panel.

When you change a Skill, consider whether the change is backward-compatible. A change to the gotchas section — adding a new failure mode — is backward-compatible. A change to the procedure that alters the output format is not. Version your changes accordingly:

• Patch version (1.0.0 → 1.0.1): gotchas additions, documentation improvements, typo fixes
• Minor version (1.0.0 → 1.1.0): new optional steps, new optional output sections
• Major version (1.0.0 → 2.0.0): changed output format, changed required inputs, removed steps

This is not pedantry. A teammate running a Skill at 1.0.0 whose downstream workflow depends on the output format will break silently if you change the format without incrementing the major version. The version number is your contract with your teammates.

Three patterns that work in practice

A shared GitHub repository (public or private) where the org's Skills live in one place. This is the default pattern. Low overhead, familiar tooling, free access control via org membership.

A private registry with explicit access control for Skills that contain proprietary procedure — specific to an industry, a client, or a security tier that not all teammates should have. The registry enforces the access control; the install command fails cleanly for unauthorized users.

Direct file share for small teams or for Skills in development. Share the markdown file in Slack or a shared folder, install manually. No install command overhead. Use this during the draft phase of a Skill; move to the repository once the Skill is stable.

If you get stuck

The install command fails with a 404. The path in the install command must match the exact file path in the repository, including the directory. github:yourorg/skills-repo/draft-pr-description resolves to skills/draft-pr-description.md by convention — verify your repository structure matches the convention.

A teammate installed the Skill but it behaves differently for them than for you. The Skill's procedure references something in your environment that is not in theirs — a file path, a configuration variable, a tool that is installed on your machine but not theirs. Add that dependency to the gotchas section: "Requires X to be installed. Verify with which X before running."

A teammate updated their local copy of a Skill to make it work. Pull their changes into the canonical version immediately. Their local change identified a gap in the canonical procedure. If you do not pull it in, the next teammate who installs the Skill will hit the same gap.

Cross-reference

l8 covers the maintenance cadence for a Skills registry — what to audit, how often, and the three signals that say a Skill needs to be updated or retired.

Deliverable

Publish the Skill from l5 to a GitHub repository (public or private) and test the install command from a second machine or a fresh shell. Verify that the installed Skill produces identical output to the local version on the same input.

Further reading

• "One Registry, Seven Surfaces" — what changes when a Skills repo has to serve seven different consumption surfaces (Claude Code, Desktop, MCP clients, the registry website, the install CLI, the auto-update job, the team's CI). The discoverability constraints work backwards from that.

Build a Project-plus-Skills bundle for a workflow that exists in your team right now — not a hypothetical. The deliverable is a bundle your teammate can adopt without asking you a single question. That constraint is the real design brief.

Choosing the workflow

Good candidates are workflows that recur weekly, involve stable criteria, and currently require a new person to spend 20-40 minutes getting context before they can do productive work. Common examples: new-hire onboarding, incident response, weekly customer support triage, sprint retrospective preparation.

A workflow is a poor candidate if the criteria change faster than you can update the Skill files, or if the work requires so much local context that no written procedure can substitute for experience. A Skill stack does not replace judgment; it removes the overhead of re-establishing context that is stable.

What the bundle contains

A complete stack has three layers. Do not skip any of them.

Layer one: a Project with a system prompt that defines the role and output standards for this workflow. The system prompt should not be a general description of the domain — it should specify the output format and the quality bar, and reference the Skills that exist for specific sub-tasks. Attach only the documents a teammate would need: a template, a style guide, a checklist. Not your personal notes. Not reference material a teammate could find themselves.

Layer two: at least two Skills that the Project invokes for discrete sub-tasks inside the workflow. The sub-tasks are the parts of the workflow that recur identically — the parts where the procedure is fixed and the judgment calls are documented. For incident response: one Skill for writing the initial incident report, one for the timeline reconstruction, one for the post-mortem template. Each Skill is a standalone file that can be installed and used independently of the Project — this is important for teams where some members only need part of the workflow.

Layer three: a README — one page, in the repository — that tells a new user: what the workflow is, which Project to open, which Skills to install, and what the first five minutes look like. The README assumes the reader is competent but unfamiliar with your specific workflow. No acronyms without expansion. No references to internal tools without naming the tool.

The test

Hand the bundle to a teammate without explaining it. Do not walk them through it. Watch what they ask.

Every question they ask is a gap in either the system prompt, a Skill, or the README. Write down each question. After the session, trace each question to its source and fix the source — not the teammate's understanding, the document. A system prompt that requires a 15-minute walkthrough to use is not a system prompt; it is an interview.

If your teammate gets through the README, installs the Skills, opens the Project, and runs the first task without asking a question, the bundle is ready.

A note on scope

It is better to ship a bundle that covers 80% of the workflow reliably than a bundle that attempts 100% and covers none of it well. The first version of the bundle should cover the most common, most structured part of the workflow. Edge cases go in the gotchas sections of the Skills. Genuinely novel situations go outside the bundle entirely — they require human judgment, and a Skill that tries to handle everything handles nothing well.

If you get stuck

The system prompt is long and the teammate still asks questions about basic procedure. The procedure does not belong in the system prompt — it belongs in a Skill. The system prompt should describe the role and the output standard. The Skill should describe the steps. Separate them.

The Skills work correctly but the teammate does not know which one to invoke for which situation. The README is missing the decision logic. Add a section to the README: "When you are doing X, invoke Skill A. When you are doing Y, invoke Skill B." This decision logic is often the most valuable part of the README.

The bundle worked well for simple cases but failed on a complex one during the handoff test. The complex case exposed an implicit assumption in one of the Skills. Add that assumption to the gotchas section. If the assumption is load-bearing enough that the Skill cannot handle its absence, add a step early in the procedure that checks for the assumption and surfaces the failure early.

Cross-reference

l2 covers Project setup. l5 covers Skill writing. l6 covers publishing Skills to a shared repository. l8 covers the maintenance cadence for keeping the bundle accurate over time.

Deliverable

A GitHub repository containing: at least two Skill files, the system prompt as a text file, and the README. The teammate install path — clone the repository, install the Skills, open the Project — must work end-to-end without your intervention.

A Skill that worked six months ago can quietly stop working. The API it referenced changed. The team's terminology shifted. The output format it produced no longer matches the downstream tool that consumes it. The Skill still runs — it just produces output that is subtly wrong. Nobody notices until someone ships the wrong thing based on confident but incorrect output.

This is the failure mode that makes a Skills registry worse than no registry. A registry with stale entries creates false confidence. A team that would have asked a question if no Skill existed instead invokes the Skill and trusts the output. The Skill is wrong. The work is wrong. The Skill is blamed last because it ran without error.

The three signals that say a Skill needs updating

First signal: a step in the procedure produces a clarifying question more than once across different teammates or different runs. Claude is hitting an implicit assumption that the procedure no longer resolves. The assumption was once obvious — the team had a shared understanding of what "the current format" meant, for example — and it is no longer obvious because something changed. Either make the assumption explicit in the step or update the step to accommodate the change.

Second signal: the output format no longer matches the downstream tool. Your incident report Skill writes in a format your ticketing system changed six months ago. The Skill is producing valid markdown, but the ticketing system's import parser expects a different structure. Update the output step in the procedure and increment the minor version.

Third signal: a teammate modified their local copy of the Skill to make it work. This is the most important signal and the easiest to miss. If one person had to adapt the Skill to use it, the canonical version is wrong. The adaptation they made is the correct procedure. Pull their changes into the shared version, increment the version, publish the update. Do not let the canonical version remain behind the in-use version.

The three signals that say a Skill needs deleting

The workflow the Skill describes no longer exists in the team's practice. The tool it invokes has been replaced. The process it encodes was deprecated. A Skill for a defunct workflow is not neutral — it will be found by a new teammate, invoked, and produce output for a process that no longer applies.

A newer Skill covers the same procedure with less friction. This happens when a Skill is rewritten as part of a larger project and the original remains in the registry. Delete the original. One procedure, one Skill.

The Skill has not been invoked in 90 days and nobody can explain why it exists. Either nobody knows what workflow it serves, or the workflow has been abandoned, or the Skill has been silently superseded by a different approach. In any of these cases, delete it. If it is needed again, it can be recovered from git history.

The maintenance cadence

Treat Skills like tests. Schedule a quarterly audit: list every installed Skill in the registry, and for each one ask two questions. Is this still the procedure we follow? If yes, is it still accurate?

A Skills audit for a registry of ten Skills takes about an hour. Run each Skill on one real instance of the task. Note any step that produced a clarifying question or a subtly wrong output. Update or delete before the audit session ends. A Skills registry that is audited quarterly and updated immediately on each audit will stay accurate. A registry that is updated "when we have time" will drift.

The quarterly cadence is a minimum. Update a Skill immediately when you encounter any of the three update signals above — do not defer to the next audit. The audit is for the Skills you have not touched since the last audit.

Versioning as a maintenance tool

The version number in the frontmatter is your primary tool for communicating that a Skill has changed. Use it deliberately:

When you fix a gotcha or add clarifying language to a step that did not change the output: patch increment (1.2.3 → 1.2.4). Teammates who have 1.2.3 installed can upgrade; their existing workflows will not break.

When you add new capability — a new optional output section, a new optional step — without changing existing output for current inputs: minor increment (1.2.4 → 1.3.0). Safe to upgrade; new capability available.

When you change the output format, remove a step, or change the required inputs: major increment (1.3.0 → 2.0.0). Teammates need to review the change before upgrading. Downstream workflows may break if they upgrade without reading the changelog.

Write a one-line changelog entry in the README every time you increment the version. "1.3.0: Added optional ## Security section for authentication changes." A teammate reading the changelog can decide whether to upgrade without reading the entire Skill file.

If you get stuck

You want to update a Skill but teammates are currently using it and a breaking change would disrupt active work. Publish the new version as a separate Skill with a -v2 suffix in the name. Announce the transition, give teammates a window to migrate, then deprecate and delete the old version. Never silently break a running workflow.

You run the quarterly audit and find that half the Skills in the registry are stale. Do not attempt to update all of them in one session. Prioritize by frequency of use: update the Skills that are invoked weekly first. Skills that are invoked rarely are less likely to cause damage when stale — fix them second, or delete them if the use frequency has dropped because the workflow is no longer active.

You cannot find the teammate who made a local modification to a Skill. Check the team's git history if the modification was committed; check Slack or your communications archive if the modification was not shared. The modification represents discovered procedure — it exists because the canonical version was incomplete. Recover it.

Cross-reference

l6 covers the repository structure and versioning conventions that make maintenance tractable. l7 covers the full bundle — the maintenance of Projects and Skills together is different from maintaining Skills alone, because the system prompt in the Project may also drift.

Deliverable

Audit the Skills you built in this course. Classify each one: current and accurate, needs update, or retire. Update or delete at least one before the session ends. Write the version number and a one-line changelog entry for any Skill you update.