Claude Projects Guide: Build Custom AI Assistants with Instructions and File Uploads
Claude Projects: Create Project-Specific AI Assistants Step by Step
Claude Projects lets you build dedicated AI workspaces with custom instructions and uploaded knowledge files. Instead of repeating context every conversation, Projects remembers your rules, references your documents, and produces consistent output tailored to your exact needs. This guide walks you through setting up, configuring, and optimizing Claude Projects for real-world workflows.
What Are Claude Projects?
A Claude Project is a persistent workspace within Claude (Pro, Team, or Enterprise) that bundles three core elements together:
- Custom Instructions — system-level prompts that shape every response in the project- Knowledge Files — uploaded documents (PDFs, code files, CSVs, text) that Claude can reference- Conversation History — all chats within the project share the same context and rulesThis combination turns a generic chatbot into a specialized assistant that understands your domain, follows your style guide, and works from your actual data.
Step-by-Step Setup Guide
Step 1: Create a New Project
- Open claude.ai and sign in with your Pro, Team, or Enterprise account.- In the left sidebar, click Projects.- Click Create Project.- Give your project a descriptive name (e.g., “Product Launch Copy” or “Codebase QA Assistant”).- Optionally add a description to help team members understand the project purpose.
Step 2: Write Custom Instructions
Custom instructions define how Claude behaves inside your project. Click Set custom instructions in the project settings panel and enter your system prompt.
Here is an example for a technical documentation assistant:
You are a senior technical writer for Acme Corp.
Rules:
- Write in active voice, present tense
- Use American English spelling
- Target audience: intermediate developers
- Always include code examples in Python unless specified otherwise
- Format all API endpoints as: METHOD /path — description
- Never fabricate API endpoints; only reference what exists in the uploaded docs
- When uncertain, say “I don’t have enough information” rather than guessing
Tone: Professional but approachable. Avoid jargon unless the audience expects it.
Output format: Use Markdown with H2/H3 headings, bullet points, and fenced code blocks.
For a customer support assistant, you might write:
You are a Tier 1 support agent for CloudSync.
Knowledge sources: Use ONLY the uploaded product docs and FAQ files.
Escalation: If the issue involves billing, account deletion, or security breaches,
respond with: “I’ll connect you with our specialist team. Reference: [ticket summary]”
Tone: Empathetic, concise, solution-oriented.
Max response length: 150 words unless the user asks for details.
Step 3: Upload Knowledge Files
- In your project settings, find the Knowledge section.- Click Upload files and select your documents.- Supported formats include: PDF, TXT, CSV, MD, Python (.py), JavaScript (.js), JSON, and more.- Each project supports up to 200,000 tokens of project knowledge (approximately 500 pages).
Best practices for file uploads:
| Do | Don't |
|---|---|
| Upload clean, well-structured documents | Upload scanned images without OCR |
| Split large documents into focused sections | Upload a single 300-page monolith |
| Include a README or index file | Assume Claude understands file relationships |
| Use descriptive file names (api-reference-v2.md) | Use generic names (doc1.pdf, notes.txt) |
import anthropic
client = anthropic.Anthropic(api_key=“YOUR_API_KEY”)
Load your knowledge file
with open(“api-reference.md”, “r”) as f:
knowledge = f.read()
system_prompt = f"""You are a technical documentation assistant for Acme Corp.
Use the following reference material to answer questions:
{knowledge}
Rules:
- Only reference endpoints from the provided documentation
- Use Python code examples by default
- Be concise and accurate"""
message = client.messages.create(
model=“claude-sonnet-4-20250514”,
max_tokens=1024,
system=system_prompt,
messages=[
{“role”: “user”, “content”: “How do I create a new user via the API?”}
]
)
print(message.content[0].text)
Install the SDK first:
pip install anthropic
export ANTHROPIC_API_KEY=“YOUR_API_KEY”
Pro Tips for Power Users
- Layer your instructions: Start with role and tone at the top, then rules, then output format. Claude weights earlier instructions slightly more.- Use structured file naming: Prefix files with numbers (01-overview.md, 02-api-auth.md) to signal reading order.- Create a meta-index file: Upload a file called INDEX.md that describes every other uploaded file, its purpose, and when to reference it.- Version your instructions: Keep a local copy of your custom instructions in version control. When you update them, note what changed and why.- Team projects: On Team or Enterprise plans, share projects with colleagues so everyone works with the same context and gets consistent outputs.- Token budget management: Check your project knowledge usage regularly. Remove outdated files and replace them with updated versions rather than stacking duplicates.
Troubleshooting Common Issues
| Problem | Cause | Solution |
|---|---|---|
| Claude ignores custom instructions | Instructions are too vague or buried in long text | Move critical rules to the top. Use imperative phrasing: "Always do X" / "Never do Y" |
| Claude says it can't find uploaded content | File format issues or token limit exceeded | Re-upload as plain text or Markdown. Check total token count in project settings |
| Responses are inconsistent across chats | Conflicting or ambiguous instructions | Audit instructions for contradictions. Add priority ordering for conflicting rules |
| File upload fails | Unsupported format or file too large | Convert to PDF, TXT, or MD. Individual files must be under 30MB |
| API responses differ from web UI | System prompt doesn't match project instructions | Copy exact project instructions into your API system prompt |
How many files can I upload to a single Claude Project?
You can upload multiple files up to a combined limit of approximately 200,000 tokens (roughly 500 pages of text). There is no hard cap on file count, but each file must be under 30MB. For best results, keep files focused and well-organized rather than uploading everything at once. If you hit the token limit, prioritize the most critical reference materials and remove outdated documents.
Can I share a Claude Project with my team members?
Yes, on Claude Team and Enterprise plans, you can share projects with other members of your organization. Shared projects give every team member access to the same custom instructions, knowledge files, and conversation space. This ensures consistent AI behavior across the team. On the Pro plan, projects are personal and cannot be shared, but you can export and distribute your custom instructions manually.
What is the difference between custom instructions and a regular system prompt in the API?
Functionally, custom instructions in Claude Projects and the system parameter in the API serve the same purpose — they set behavioral rules before the conversation begins. The key difference is persistence: project custom instructions automatically apply to every new chat in that project without any code, while API system prompts must be included in every request programmatically. Projects also combine instructions with uploaded knowledge files seamlessly, whereas in the API you must manually inject document content into the system prompt or use document-type content blocks.