machine-claude-context

Shared context for bootstrapping effective Claude usage on the Machine team.

The idea

Working effectively with Claude comes down to one recursive loop: ask Claude to help you figure out how to use Claude. Give it context about your work, connect it to your tools, and then just keep asking. "What should I be paying attention to?" "How can you help me prep for this?" "What am I not asking you that I should be?"

Every file in this repo exists because someone asked Claude a question and the answer was useful enough to share. The repo gives you a running start — but you can always ask Claude "what should I be asking you?" and it'll figure it out from your actual work.

Quick start

1. Upload these files into Claude Code desktop (or paste into a Claude.ai project):
   • getting-started-with-claude.md
   • machine-directory-for-claude.md
2. Connect your integrations (Slack, Jira, Google Calendar)
3. Say: "Help me get set up"
4. Claude reads your activity, drafts your profile, and walks you through the rest

What's in here

File	Purpose
getting-started-with-claude.md	Playbook for using Claude effectively — principles, MCP integrations, what to try first. Claude will draft your profile from your integrations.
machine-directory-for-claude.md	Machine ecosystem map — Slack channels, GitHub repos, Jira project structure, key people. Designed to be personalized as you use it.
machine-architecture-context.md	How the system fits together — services, gateway, data pipeline, deploy process. Summary with pointers to source repos for deep dives.
machine-glossary.md	Product vocabulary, team names, technical shorthand, process terms, acronyms, and legacy terminology. What things mean when you encounter them in Slack and Jira.
ways-of-working.md	Patterns that make Claude genuinely useful — how to ask, how to prep, how to correct, how to cross-reference. The habits, not the prompts.
advanced-use-cases.md	Beyond text chat — visual QA via Playwright, meeting memory via Granola, live doc review, Figma reference, calendar-aware workflows, cross-tool verification.
growing-your-context.md	How context compounds over time — the one habit that matters, what it looks like at each level (claude.ai → Claude Code → contributing back), and what not to do.
guide-machine-ai-skills.md	Hand-holding guide to the machine-ai-skills repo — what skills are, how to install them, which ones matter for your role, and what to try first.
query-library.md	30+ copy-paste queries for real Machine workflows — morning catchup, sprint management, code awareness, meeting prep, and more.

How to contribute

This repo gets better when people use Claude and feed back what they learn. Even small things are valuable — a missing channel, a query that works better than what's here, a gotcha you hit that others will hit too.

Easiest wins:

• Missing or outdated channel/repo? Update machine-directory-for-claude.md — these go stale fastest
• Found a good query? Add it to query-library.md — the more real-world queries, the more useful this is for everyone
• Learned a Claude pattern that works? Add it to getting-started-with-claude.md under "what to try first" or the tips section
• Noticed something wrong? Fix it. A one-line correction is a perfectly good PR.

Bigger contributions:

• New context files for domains not yet covered (brand voice, QA process, client onboarding, etc.)
• Domain-specific query collections for your area of the product

Open a PR. Keep files focused on shared context, not personal preferences — the whole point is that everyone customizes on top of the shared layer.

What doesn't belong here

• Personal instructions or preferences (those go in your own project instructions)
• Product-facing AI skills (those go in machine-ai-skills)
• Sensitive information (credentials, API keys, private channel IDs)

Maintainer

Sam Billetdeaux (@SamBilletdeaux)