How to think about Projects

A Project in spaget is a container that holds a group of Agents and the resources they share — Skills, Commands, Hooks, and MCPs. Everything inside a Project sees the same shared context, and when you export, you export the whole Project at once.

The single most useful question to ask before creating a Project is:

“What is the unit of work I want these agents to share context on?”

Get that scope right and your agents stay focused, your skills stay reusable, and your exports drop cleanly into the right repo or workspace.

There’s no single right answer — Projects are flexible by design. Most people land on one of three organizing principles (or a mix).

The most common pattern. One Project per codebase you maintain.

• Why it works: a Project’s exported CLAUDE.md, .cursor/rules/, or .github/copilot-instructions.md is meant to live alongside source code. One repo, one Project keeps that mapping clean.
• What goes in: agents that all need the same architectural context (your stack, conventions, file structure). Skills like “Write TypeScript with strict mode” or “Follow the service-layer pattern” are shared once and inherited by every agent.
• Example: a Project called acme-web containing a Frontend Engineer, Backend Engineer, and QA Reviewer agent — all three understand your repo conventions because the Project’s Skills define them once.

A Project per thing-you’re-trying-to-ship.

• Why it works: ad-hoc work doesn’t always map to a long-lived codebase. A migration, a launch, a research spike, or a one-week prototype each has its own context, success criteria, and lifespan.
• What goes in: agents that exist for the duration of the initiative. Hooks that enforce launch-specific rules. MCPs that connect to the data sources relevant to this piece of work, not your whole stack.
• Example: a Project called Q3 Pricing Migration containing a Migration Planner, Schema Auditor, and Comms Drafter. When the migration ships, the Project archives — no orphan agents cluttering your main workspace.

A Project that mirrors how your org is structured.

• Why it works: a “team of agents” idea — each agent plays a role on a virtual team, and the Project itself represents that team’s domain.
• What goes in: agents that share a functional context rather than a technical one. Skills about brand voice, sales positioning, support tone, or financial models.
• Examples:
  • Marketing — Copywriter, SEO Researcher, Social Scheduler
  • Customer Success — Onboarding Drafter, Health-Check Analyst, Escalation Triager
  • Finance — Burn Reporter, Forecast Modeler, Investor Update Drafter

A few things to avoid:

• One giant “Everything” Project — if every agent and skill lives in one Project, your context gets noisy and exports become unwieldy. Split when scope starts to bleed.
• One Project per agent — defeats the purpose. The whole point of grouping is shared Skills, Hooks, and MCPs. If two agents would never share a single Skill, sure, separate them — but that’s usually a sign they belong to different domains, not different Projects.
• Treating Projects like folders — a Project isn’t just a label. Adding a Skill to a Project means every Agent in it inherits that Skill. If you wouldn’t want all agents to share something, it doesn’t belong at the Project level.

• Name for scope, not for content. acme-web or Q3 Pricing Migration ages well; My Agents does not.
• Start narrow, split later. It’s easier to split a Project than to disentangle a tangled one. When in doubt, make a new Project.
• Let the export target guide you. If two agents would ship to the same CLAUDE.md, they probably belong in the same Project. If they’d ship to different repos, they probably don’t.
• Use the Assistant to bootstrap. Describe the team or codebase you’re working on and the in-app Assistant can scaffold a starter set of agents, skills, and hooks for the Project.

• What are AI agents? — How the agents inside a Project are configured
• Skills explained — The reusable instruction sets you share across a Project
• Getting started — Build your first Project in under 5 minutes