# Learn to work with Claude, n8n and Astro. # Install Claude > Get Claude running in your browser, on your computer and on your phone, sign in with one account and start your first useful chat. Source: https://viralistic.nl/help/claude/install-claude This article is for anyone who is new to Claude. You will set it up in the places you work (browser, computer and phone), sign in once, and have your first useful conversation. It takes about five minutes. ## Where you can use Claude Claude is one account with several ways in. Your chats, projects and settings follow you across all of them. | Where | What it is | Best for | | ----------- | ----------------------------------------------- | ------------------------------------------- | | Web | claude.ai in any modern browser | Quick start, shared or borrowed computers | | Desktop app | Claude for macOS and Windows (Linux is in beta) | Daily work, keyboard shortcuts, local tools | | Mobile app | Claude for iOS and Android | Voice, photos, questions on the go | You do not need all three. Most people start on the web and add the desktop app once Claude becomes part of their day. ## Use Claude in your browser 1. Go to [claude.ai](https://claude.ai). 2. Choose to sign up or log in. 3. Pick a sign-in method: your Google account or your email address. 4. If you use email, open the message Claude sends you and follow the link or enter the code. 5. Answer the short welcome questions. You can change these later in Settings. That is it. The chat box is ready. > **Tip:** Use the same sign-in method every time. If you sign up with Google once and with an email link the next time, you can end up with two separate accounts. ## Install the desktop app The desktop app gives you the same Claude with a few extras, such as a global shortcut and access to tools on your own computer. 1. Go to the official download page: [claude.com/download](https://claude.com/download). 2. Download the version for your system (macOS, or Windows on x64 or ARM). 3. Open the downloaded file and follow the installer. 4. Start Claude from your Applications folder (Mac) or the Start menu (Windows). 5. Sign in with the same account you use on the web. > **Note:** On a paid plan the desktop app also contains Claude Code, the coding assistant. See [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) if you want to work with files and folders on your computer. ## Install the mobile app 1. Open the App Store (iPhone, iPad) or Google Play (Android). 2. Search for "Claude by Anthropic" and check that the publisher is Anthropic. 3. Install the app and open it. 4. Sign in with the same account. The mobile app is handy for voice input, for snapping a photo of a document or whiteboard and asking about it, and for picking up a chat you started at your desk. > **Warning:** Only install Claude from claude.ai, claude.com or the official app stores. Look-alike apps exist and some ask for payment or personal data. ## Have your first chat A good first chat is a real task, not a test question. Try something from your own work. 1. Click **New chat** (or the pencil icon). 2. Type what you need in plain language, with enough context for a stranger to understand it. 3. Optional: attach a file with the paperclip or plus button, such as a PDF, spreadsheet or screenshot. 4. Press Enter and read the answer. 5. Reply to refine it: "shorter", "more formal", "turn this into a table". An example first message: ```text I run a small design studio in Amsterdam. Below is an email from a client asking to move a deadline. Draft a friendly reply that agrees to one extra week, but not two. Keep it under 120 words. [paste the email here] ``` ### Get more from the first week - Keep each chat about one topic. Start a new chat when you switch subjects. - Ask Claude to ask you questions first when a task is complex: "Before you start, ask me what you need to know." - Check facts, figures and names before you send anything. Claude is good, not infallible. ## Troubleshooting | Problem | What to try | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | No sign-in email arrives | Check spam, wait a minute, then request a new link | | Logged in but chats are missing | You may be in a different account; log out and use your original sign-in method | | Desktop app will not open | Download it again from the official page and reinstall | | "Usage limit reached" message | You hit your plan's limit; wait for it to reset or read [Choose the right Claude plan](https://viralistic.nl/help/claude/choose-a-plan) | ## Next steps - [Choose the right Claude plan](https://viralistic.nl/help/claude/choose-a-plan) - [Brief Claude like a colleague](https://viralistic.nl/help/claude/write-better-prompts) - [Give Claude lasting context with Projects](https://viralistic.nl/help/claude/projects) --- # Choose the right Claude plan > Understand the differences between Claude's Free, Pro, Max, Team and Enterprise plans so you can pick the one that fits how you and your team work. Source: https://viralistic.nl/help/claude/choose-a-plan Claude has plans for individuals and for organisations. This article explains what changes between them in plain terms, so you can choose without reading a long comparison table. Prices and exact limits change regularly, so for current numbers always check the official [Claude pricing page](https://claude.com/pricing). ## The short answer - **Trying Claude out:** start on Free. - **Using Claude for your own work every day:** Pro. - **Hitting Pro limits often, or running long coding sessions:** Max. - **A company or team of people who share work:** Team. - **A larger organisation with security, compliance or identity requirements:** Enterprise. ## Plans for individuals ### Free Free lets you chat with Claude on the web, desktop and mobile, upload files, and use features such as web search, artifacts and skills. Usage is limited, so you will hit a pause on busy days. It is a good way to learn how Claude thinks before you pay. ### Pro Pro is the plan most professionals start with. Compared to Free you get: - More usage per session. - Access to more Claude models. - Claude Code, the coding and file assistant (terminal, desktop app and web). - Research and extra tools such as the browser and Microsoft 365 extensions. ### Max Max includes everything in Pro with a much higher usage allowance. It comes in two levels, each with more headroom than Pro. People who run Claude Code for hours a day, or who hit the Pro limit before lunch, usually move here. Max also gets priority access when demand is high and early access to some new features. > **Tip:** Not sure whether you need Max? Stay on Pro for two weeks and note how often you hit the limit. If it happens several times a week and blocks real work, upgrade. If it happens once in a while, it is usually cheaper to wait for the reset. ## Plans for organisations ### Team Team is built for groups that work together. On top of Claude's features it adds: - Central billing and one admin place for all members. - Single sign-on (SSO). - Admin control over which connectors and features people can use. - Shared projects and organisation-wide skills. - Seat types you can mix, so heavy users can have more capacity than occasional users. ### Enterprise Enterprise adds what larger organisations need: role-based permissions, user provisioning (SCIM), audit logs, custom data retention and compliance options. It is usually arranged with Anthropic's sales team. ## How your data is treated This is often the deciding factor for businesses, so check it before you choose. | Plan type | Terms that apply | Your chats and model training | | ---------------- | ---------------- | ------------------------------------------------------------------------------- | | Free, Pro, Max | Consumer terms | You choose in your privacy settings whether chats may be used to improve Claude | | Team, Enterprise | Commercial terms | Covered by the organisation's commercial agreement, not the consumer setting | > **Warning:** If you handle client data, personal data or anything under an NDA, read [Memory, privacy and your data](https://viralistic.nl/help/claude/memory-and-privacy) before you pick a personal plan for work use. For a team, a Team or Enterprise plan is usually the right home for client work. ## Usage limits in practice Every plan has a usage limit. It is not a fixed number of messages: long chats, large files and heavy tools use more of your allowance than short questions. When you reach the limit, Claude shows when it resets. To stretch your allowance: 1. Start a new chat when you change topic, instead of continuing a very long one. 2. Put recurring background material in a [Project](https://viralistic.nl/help/claude/projects) rather than pasting it every time. 3. Only attach the files Claude actually needs. 4. Turn off connectors and tools you are not using in that chat. ## Changing or cancelling your plan You can upgrade, downgrade or cancel from your account settings in Claude (look for the billing or subscription section). An upgrade usually applies straight away. A downgrade or cancellation normally takes effect at the end of the current billing period. If you subscribed through the iOS or Android app, you manage the subscription in that app store instead. ## Next steps - [Install Claude](https://viralistic.nl/help/claude/install-claude) - [Memory, privacy and your data](https://viralistic.nl/help/claude/memory-and-privacy) - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) --- # Brief Claude like a colleague > Write prompts that get a usable first draft by giving Claude the same context, goal and constraints you would give a smart new colleague. Source: https://viralistic.nl/help/claude/write-better-prompts Most disappointing answers from Claude come from thin briefs, not from a weak model. This article shows a simple way to brief Claude the way you would brief a capable new colleague who knows nothing about your company yet. You do not need special tricks or magic words. ## The colleague test Before you send a prompt, ask yourself: if I sent this message to a smart freelancer who started today, could they do a good job? If they would need to come back with five questions, Claude needs those answers too. Compare these two briefs. ```text Write a LinkedIn post about our new website. ``` ```text We are a four-person bakery in Utrecht. We just launched a new website where people can pre-order bread for Saturday pickup. Write a LinkedIn post for our company page announcing it. Audience: local customers and neighbouring businesses, not other bakers. Tone: warm and plain, no hype, no emojis. Length: under 120 words. Must include: pre-order closes Thursday 20:00, link at the end. Avoid: the words "excited" and "thrilled". ``` The second one takes a minute longer to write and saves you three rounds of edits. ## The five parts of a good brief You do not need all five every time, but check them for anything that matters. 1. **Context:** who you are, what the situation is, what has already happened. 2. **Goal:** what the result is for and what a good outcome looks like. 3. **Audience:** who will read or use it, and what they already know. 4. **Constraints:** length, tone, format, words or claims to avoid, deadlines. 5. **Examples:** a sample of what good looks like, such as a previous email you liked. > **Tip:** Explain why, not just what. "Keep it short because it will be read on a phone" works better than "keep it short", because Claude can then make sensible choices you did not spell out. ## Give Claude the material Claude can only use what it can see. Paste or attach the source material instead of describing it. - Attach the PDF, spreadsheet or screenshot. - Paste the email thread you are replying to. - Share last year's version of the document you want updated. When a prompt mixes instructions and material, separate them clearly so Claude knows which is which: ```text Summarise the meeting notes below for the client. Use three headings: Decisions, Open questions, Next steps. [paste the notes here] ``` The tags are not special code. They are simply a clear way to say "this part is the material". ## Let Claude ask first For bigger tasks, start with a short brief and ask Claude to interview you: ```text I need a one-page proposal for a website redesign for a client. Before you write anything, ask me the questions you need answered. Ask them all at once, numbered. ``` Answer the questions in one reply, then ask for the draft. This is often faster than writing the perfect brief yourself. ## Iterate like you would with a person The first answer is a draft. Give feedback that is specific and actionable. | Instead of | Try | | ---------------- | ------------------------------------------------------------------------------ | | "Make it better" | "The second paragraph repeats the first. Cut it and add one concrete example." | | "Too formal" | "Write it the way you would say it to a client you have known for years." | | "Wrong" | "The deadline is the 14th, not the 12th. Fix that and keep the rest." | If a chat goes in circles, start a new chat with an improved brief that includes what you learned. A fresh start is often better than ten corrections. ## Common mistakes - **Asking for everything at once.** Split a big job into steps: outline first, then sections, then a final edit. - **Hiding the real goal.** If the email is meant to get a late invoice paid, say so. - **No format.** If you want a table, bullet list or a specific heading structure, say it. - **Trusting facts blindly.** Ask Claude to mark anything it is unsure about, and check names, numbers and dates yourself. ## Make good briefs reusable When you notice you are typing the same background into every chat, stop repeating yourself: - Put background and standing instructions in a [Project](https://viralistic.nl/help/claude/projects). - Turn a repeatable way of working (house style, report format, checklist) into a [skill](https://viralistic.nl/help/claude/what-is-a-skill). ## Next steps - [Give Claude lasting context with Projects](https://viralistic.nl/help/claude/projects) - [What a skill is and when to make one](https://viralistic.nl/help/claude/what-is-a-skill) - [Connect Claude to your tools](https://viralistic.nl/help/claude/connectors) --- # Give Claude lasting context with Projects > Set up a Claude Project with files and instructions so every chat about a client, product or topic starts with the right background. Source: https://viralistic.nl/help/claude/projects A Project is a workspace in Claude that holds background files, standing instructions and all chats about one subject. Instead of pasting the same brief into every new chat, you set it up once. This article shows how to create a Project, what to put in it and how to keep it useful. ## When a Project helps Use a Project when you keep coming back to the same subject with the same background. Good examples: - One client: their brand guide, tone of voice, product list and contacts. - One product or website: specs, sitemap, FAQs and past decisions. - One recurring job: monthly reporting, newsletter writing, sales proposals. A one-off question does not need a Project. A normal chat is fine. ## What a Project contains | Part | What it does | | ------------ | ------------------------------------------------------------------------------------------------- | | Instructions | Rules Claude follows in every chat in the Project, such as tone, language and format | | Knowledge | Files and text Claude can use as background in every chat | | Chats | All conversations you start inside the Project, kept together | | Memory | On plans with memory turned on, each Project keeps its own memory, separate from your other chats | ## Create a Project 1. Open Claude and go to **Projects** in the sidebar (or visit claude.ai/projects). 2. Click to create a new Project. 3. Give it a clear name, such as "Client: [client name]" or "Monthly newsletter". 4. Add a short description so you and your colleagues know what it is for. 5. On Team and Enterprise plans, choose whether to keep it private or share it with your organisation. > **Note:** Projects are available on every plan, including Free. Free accounts can create a small number of Projects; paid plans have room for more. ## Write the instructions Instructions are the standing brief. Keep them short and concrete. Write them as you would brief a colleague on day one. 1. In the Project, find the option to set project instructions. 2. Paste or write your instructions. 3. Save. An example: ```text You help me write content for [client name], a family bakery in Utrecht. - Write in Dutch unless I ask otherwise. Use "je", not "u". - Tone: warm, plain, a little playful. No hype words. - Never invent prices or opening hours. Use the price list in the knowledge files, or ask me. - For social posts: max 120 words, no hashtags in the body. - When something is unclear, ask one question before you start. ``` > **Tip:** If you notice yourself correcting Claude on the same thing twice, add it to the instructions. ## Add knowledge Knowledge is the reference material Claude can draw on in every chat in the Project. 1. In the Project, find the knowledge panel (usually on the right). 2. Upload files such as PDFs, Word documents, text files or spreadsheets, or paste text directly. 3. Give files clear names, such as `brand-guide-2026.pdf` instead of `final-v3.pdf`. What works well as knowledge: - Brand and tone of voice guides. - Product and price lists. - Approved texts you want Claude to learn from. - Background documents about the client or market. What to leave out: - Old versions of documents that contradict the current ones. - Huge archives "just in case". More is not better if most of it is irrelevant. - Passwords, API keys or anything you would not email to a colleague. On paid plans, when a Project's knowledge gets large, Claude automatically switches to searching through it instead of reading everything at once. You do not need to do anything for this. ## Work inside the Project Start every chat about this subject from inside the Project, not from the general chat screen. You can tell you are in a Project because its name shows above the chat. You can also move an existing chat into a Project later. ## Share a Project with your team On Team and Enterprise plans you can invite colleagues to a Project. You choose per person whether they can only view and chat, or also edit the instructions and knowledge. Give edit rights to one or two owners per Project so the instructions stay consistent. ## Keep it tidy - Review instructions and files every few months and remove what is outdated. - Archive Projects for finished work. Archived Projects keep their content but no longer clutter your list. - Delete a Project only when you are sure you no longer need its chats and files. ## Next steps - [Brief Claude like a colleague](https://viralistic.nl/help/claude/write-better-prompts) - [Connect Claude to your tools](https://viralistic.nl/help/claude/connectors) - [Memory, privacy and your data](https://viralistic.nl/help/claude/memory-and-privacy) - [What a skill is and when to make one](https://viralistic.nl/help/claude/what-is-a-skill) --- # Connect Claude to your tools > Use connectors and MCP servers so Claude can read from and work in tools like Google Drive, Gmail, Notion and n8n, with permissions you control. Source: https://viralistic.nl/help/claude/connectors Connectors let Claude look things up and take actions in the tools you already use, such as finding a file in Google Drive, drafting a Gmail reply or updating a Notion page. This article explains how they work, how to add them and how to stay in control. ## How connectors work Connectors are built on the Model Context Protocol (MCP), an open standard for linking AI assistants to other software. A tool that supports MCP runs an "MCP server". The server tells Claude which actions are available (for example "search files" or "create draft"), and Claude calls those actions when your request needs them. Claude always works with your permissions. If your Google account cannot open a folder, Claude cannot open it either. ## Types of connectors | Type | Where it runs | How you add it | Typical examples | | ------------------- | --------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------- | | Directory connector | Online, hosted by the tool's maker | Pick it from Claude's connector directory and sign in | Google Drive, Gmail, Google Calendar, Notion, Slack | | Custom connector | Online, at a URL you provide | Paste the remote MCP server URL | Your own n8n instance, an internal company tool | | Local MCP server | On your own computer, through the desktop app | Install a desktop extension | File system access, tools that only run locally | Remote connectors (the first two) work on the web, desktop and mobile. Local MCP servers only work in the desktop app on the computer where they are installed. ## Add a connector from the directory 1. Open Claude's settings and find **Connectors** (in some versions this sits under Customize). 2. Browse the directory, or search for the tool you want. 3. Click the connector and choose to connect. 4. Sign in to the tool in the window that opens, and review which access Claude asks for. 5. Approve. The connector now shows as connected. > **Note:** On Team and Enterprise plans, an Owner decides which connectors are available. If you cannot find or enable one, ask your Claude admin. ## Use a connector in a chat Connectors can be switched on and off per chat, which keeps Claude focused and saves usage. 1. In the chat box, click the **+** button. 2. Open the connectors or tools menu. 3. Switch on the connectors this chat needs and switch off the rest. 4. Ask in plain language, for example: "Find the latest signed proposal for this client in Drive and summarise the scope." ## Add a custom connector Use this when a tool gives you an MCP server URL that is not in the directory. A common case is n8n: an n8n instance can expose an MCP server so Claude can find and run your workflows. See [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp) for that setup. 1. Open the Connectors settings. 2. Choose to add a custom connector. 3. Give it a name and paste the remote MCP server URL. 4. If the provider gave you an OAuth client ID and secret, enter them under the advanced settings. 5. Add the connector, then connect and sign in if asked. On Team and Enterprise plans, an Owner adds custom connectors for the organisation in the admin settings, and members then connect their own account. Free accounts can add only a limited number of custom connectors. > **Warning:** Custom connectors are not reviewed by Anthropic. Only add servers from providers you trust, and never paste a URL from an unknown source. ## Local MCP servers in the desktop app Some tools run on your own computer instead of online. The desktop app installs these as extensions. 1. In the Claude desktop app, open Settings and find **Extensions**. 2. Browse the extensions directory and choose one. 3. Install it and fill in any settings it needs, such as a folder path or API key. 4. The extension's tools are now available in your chats on that computer. If you are not sure what a local server does, do not install it: it runs on your machine with your access. ## Stay in control of permissions Claude asks for approval before it uses a connector tool, especially for actions that change something. You usually see options to allow it once or to always allow it. - **Allow once** for anything that sends, deletes, publishes or pays. - **Always allow** only for read-only tools from providers you trust, such as searching your own files. - **Disconnect** connectors you no longer use from the Connectors settings. Be careful with outside content. A web page, email or document can contain hidden instructions meant to trick an AI. This is called prompt injection. Read approval requests before you click, and stop the chat if Claude tries something you did not ask for. > **Tip:** Connect with the narrowest access that works. A shared Drive folder for one client is safer than your whole company Drive. If you want help choosing and setting up connectors and n8n workflows for your team, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp) - [Memory, privacy and your data](https://viralistic.nl/help/claude/memory-and-privacy) - [Give Claude lasting context with Projects](https://viralistic.nl/help/claude/projects) - [Build workflows with Claude](https://viralistic.nl/help/n8n/build-workflows-with-claude) --- # Memory, privacy and your data > Learn what Claude remembers between chats, how to view or switch off memory, and which privacy settings to check before you use Claude for client work. Source: https://viralistic.nl/help/claude/memory-and-privacy Claude can remember useful details across chats, and you decide how much it keeps. This article explains how memory works, how to review or turn it off, and which privacy settings matter if you use Claude for work. It is written for everyday users, not lawyers: for the binding details, read Anthropic's privacy policy and your plan's terms. ## What memory does With memory on, Claude picks up useful facts from your chats as you go, such as your role, the projects you work on and how you like answers formatted. Later chats can use that knowledge, so you repeat yourself less. Memory is organised in topics you can read and edit. Each [Project](https://viralistic.nl/help/claude/projects) has its own separate memory, so details from one client's Project do not leak into another's. | Plan | Memory by default | | ---------------- | --------------------------------------------------------- | | Free, Pro, Max | On | | Team, Enterprise | Off until the organisation allows it and you switch it on | ## View, edit or turn off memory 1. Open **Settings** and go to **Memory**. 2. Browse the topics Claude has saved. 3. Open a topic to read it, then edit or delete it if it is wrong or too personal. 4. To stop Claude from remembering anything new, switch memory off on the same page. > **Tip:** Every few months, read through your memory topics. Remove old jobs, finished projects and anything you would not want in a fresh chat. ## Search past chats On paid plans Claude can also search your earlier conversations when you ask, for example "What did we decide about the homepage last week?". You can switch this off in the Memory settings with the option to search and reference chats. ## Use an incognito chat For a one-off conversation you do not want saved, start an incognito chat (look for the ghost icon when you start a new chat). - It does not appear in your chat history. - Claude does not add it to memory or find it in later chat searches. - On Team and Enterprise plans, your organisation's retention policy can still apply. Incognito is useful for a quick personal question on a work account, or for testing a prompt without it shaping Claude's memory. ## Model training and your chats This is the setting most people miss. ### Free, Pro and Max These plans run under Anthropic's consumer terms. In **Settings**, under **Privacy**, there is an option that controls whether your chats and coding sessions may be used to improve Claude (train future models). You can switch it on or off at any time. How long Anthropic keeps your data also depends on this choice; the privacy policy lists the current periods. 1. Open **Settings** and go to **Privacy**. 2. Find the option about helping to improve Claude. 3. Set it the way you want. ### Team and Enterprise These plans run under Anthropic's commercial terms. The consumer training setting does not apply; your organisation's agreement covers how data is handled. Owners on Enterprise can also set custom data retention. > **Warning:** Before you paste client material, check two things: which plan you are on, and what your contract with the client allows. A personal Free or Pro account is rarely the right place for confidential client data. ## What not to share Whatever your plan, keep these out of chats: - Passwords, API keys, recovery codes and bank details. - Other people's sensitive personal data (health, ID numbers, financial records) unless you have a clear legal basis and a business plan that covers it. - Anything under NDA that your agreement does not let you process with an AI tool. When you only need help with structure or wording, replace names and numbers with placeholders such as `[client]` or `[amount]`. ## Connectors and privacy [Connectors](https://viralistic.nl/help/claude/connectors) let Claude read from tools such as Gmail or Google Drive. Claude only reads what a request needs, but it can see whatever your account can see. Connect the narrowest access that works, and disconnect tools you no longer use. ## Delete or export your data - Delete a single chat from the chat menu. - Delete a Project, with its chats and files, from the Project menu. - In the privacy settings you can request an export of your data. - Closing your account removes your access; see Anthropic's help centre for what happens to stored data. ## Next steps - [Choose the right Claude plan](https://viralistic.nl/help/claude/choose-a-plan) - [Give Claude lasting context with Projects](https://viralistic.nl/help/claude/projects) - [Connect Claude to your tools](https://viralistic.nl/help/claude/connectors) - [Share logins and access safely](https://viralistic.nl/help/account/share-access-safely) --- # What a skill is and when to make one > Understand what Claude skills are, how they differ from Projects and prompts, and how to recognise work that is worth turning into a skill. Source: https://viralistic.nl/help/claude/what-is-a-skill A skill is a packaged way of working that Claude can pick up whenever it is relevant. Think of it as a short training manual you write once, after which Claude follows it in any chat that needs it. This article explains what a skill is made of, how it differs from Projects and prompts, and when it is worth making one. ## What a skill is A skill is a folder with at least one file, `SKILL.md`. That file has two parts: 1. A short header with a **name** and a **description**. The description tells Claude what the skill does and when to use it. 2. The **instructions**: plain text Claude follows when the skill is active, such as steps, rules, examples and checklists. The folder can also hold extra files: templates, reference documents, examples or small scripts. ```text house-style/ ├── SKILL.md (required: name, description, instructions) ├── tone-of-voice.md (optional reference) ├── examples.md (optional good and bad examples) └── scripts/ └── check_length.py (optional helper script) ``` ## How Claude uses a skill Claude does not read every skill in full all the time. At the start it only sees each skill's name and description. When your request matches a description, Claude opens that skill and follows the instructions, and only reads the extra files when it needs them. That has two practical effects: - You can install many skills without cluttering every chat. - The description decides everything. If it is vague, Claude will not know when to use the skill. > **Note:** Anthropic ships some skills already, for example the ones that let Claude create Word, Excel, PowerPoint and PDF files. Skills need code execution and file creation to be switched on in your Claude settings. ## Skills, Projects and prompts compared | Tool | Best for | Scope | | ------------------------------------------- | ---------------------------------------------------------- | ----------------------------- | | Prompt | A one-off task | One message or chat | | [Project](https://viralistic.nl/help/claude/projects) | Background about one subject: a client, product or topic | Chats inside that Project | | Skill | A repeatable way of working: a process, format or standard | Any chat where it is relevant | | [CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) | Rules for one code or website folder in Claude Code | One project folder | A simple rule: **Projects hold knowledge about a thing, skills hold know-how about a task.** A client's price list belongs in a Project. "How we write a proposal" belongs in a skill, because it applies to every client. ## Where skills work The same skill format works across Claude: - In the Claude apps (web and desktop), where you upload a skill in your settings. - In Claude Code, where skills are folders on your computer or in a project. - Through the Claude API, for developers. Skills are available on every plan, including Free. On Team and Enterprise plans, an admin can also share skills with the whole organisation. ## When to make a skill Make a skill when you notice one of these: - You paste the same instructions into chats again and again. - A task has fixed steps and people keep forgetting one. - Output must follow a standard: house style, report layout, naming rules, legal wording. - You want colleagues to get the same quality as your best person on the job. - The work needs a template or a small script every time. ## When not to - **One-off tasks.** Just write a good prompt. - **Background on one client.** Use a Project. - **Information that changes daily**, such as stock levels or calendars. Use a [connector](https://viralistic.nl/help/claude/connectors) so Claude reads the live source. ## Real-world examples - **Agency house style.** How the agency writes: tone, banned words, spelling choices, heading rules, and before-and-after examples. Every writer and every chat gets the same voice. - **Astro site architecture.** For teams that build websites with Astro: the folder structure, how pages and content collections are set up, naming conventions and a checklist for new sections. Claude Code uses it whenever someone adds a page or component. - **Proposal writer.** The sections a proposal must have, how to estimate, which disclaimers to include, and a template file. - **Monthly report.** Which numbers to pull, how to compare months and the fixed layout the client expects. ## Next steps - [Create a skill](https://viralistic.nl/help/claude/create-a-skill) - [Install and share skills](https://viralistic.nl/help/claude/share-skills-with-your-team) - [Give Claude lasting context with Projects](https://viralistic.nl/help/claude/projects) --- # Create a skill > Write a SKILL.md file, add reference files, test it, and install the skill in the Claude apps or in Claude Code. Source: https://viralistic.nl/help/claude/create-a-skill This article walks you through building a skill from scratch, using an agency house-style skill as the example. You will write `SKILL.md`, add supporting files, install the skill in the Claude apps and Claude Code, and test it. New to skills? Read [What a skill is and when to make one](https://viralistic.nl/help/claude/what-is-a-skill) first. ## Before you start 1. Pick one job for the skill. "Write in our house style" is good. "Everything about marketing" is too broad. 2. Collect what you have: style guides, checklists, good examples, templates. 3. In the Claude apps, make sure code execution and file creation is switched on in your settings (look under **Settings** and then **Capabilities**). Skills need it. ## Step 1: Create the folder Create a folder named after the skill, in lowercase with hyphens: ```text house-style/ ├── SKILL.md ├── examples.md └── checklist.md ``` Only `SKILL.md` is required. The other files are optional. ## Step 2: Write SKILL.md `SKILL.md` starts with a header (YAML frontmatter) between two `---` lines, followed by the instructions in plain Markdown. ```md --- name: house-style description: Applies our agency house style to texts for clients or our website. Use when writing or editing blog posts, web copy, emails, proposals or social posts. --- # House style Follow these rules for every text you write or edit. ## Voice - Write like a smart colleague explaining something over coffee: clear, direct, friendly. - Address the reader as "you". Refer to the agency as "we". - Short sentences. One idea per sentence. ## Words - Never use: "unlock", "leverage", "seamless", "game-changer". - Say "website", not "web presence". Say "customers", not "end users". ## Format - Headings in sentence case. - Write numbers one to nine in words, 10 and up in digits. ## Process 1. Identify the audience and the channel before writing. 2. Write the draft using the rules above. 3. Check the draft against checklist.md and fix anything that fails. 4. Return only the final text, unless the user asks for notes. ## Reference files - examples.md: before-and-after examples of our voice. Read it when unsure about tone. - checklist.md: the final check. Always use it before returning text. ``` ### Write a description that triggers The description is what Claude reads to decide whether to use the skill. Make it do two things: - Say **what** the skill does. - Say **when** to use it, with the words people actually type ("blog post", "proposal", "web copy"). Keep the `name` short (lowercase letters, numbers and hyphens) and the description to one or two sentences. The Claude apps limit how long both can be, so short is safer. > **Tip:** Write the instructions as if for a new colleague: concrete rules, the reason behind unusual ones, and an example or two. Vague advice like "be engaging" helps nobody. ## Step 3: Add reference files Put longer material in separate files and point to them from `SKILL.md`, as in the example above. Claude only opens them when needed. Good candidates are example texts, templates, checklists and glossaries. A skill can also include small scripts (for example one that checks word counts), which Claude can run. ## Step 4: Let Claude help (optional) You do not have to write everything yourself. Claude has a built-in skill for building skills, often called skill-creator. Start a chat and say something like: ```text Help me create a skill for our house style. I will paste our style guide and three example texts. Ask me questions first, then produce the skill folder as a zip I can upload. ``` Review the result before you use it. You know your process best. ## Step 5: Install it in the Claude apps First zip the folder. On Mac or Windows, right-click the folder and choose the compress option, or use a terminal: ```bash zip -r house-style.zip house-style ``` 1. Check that the zip contains the `house-style` folder at the top, not loose files and not a folder inside another folder. 2. In Claude, open the Skills section of your settings (currently under **Customize**, then **Skills**). 3. Use the add or upload option and choose your zip file. 4. Make sure the skill is switched on. ## Step 6: Install it in Claude Code Claude Code reads skills straight from folders, no zip needed. | Scope | Location | | ---------------------------------------------------------- | --------------------------------------- | | One project (shared with everyone who uses the repository) | `.claude/skills/house-style/SKILL.md` | | Just you, in every project | `~/.claude/skills/house-style/SKILL.md` | Claude Code uses the skill when a request matches the description, or you can run it directly by typing `/house-style`. > **Note:** A project skill is a good fit for code standards. For example, an Astro architecture skill in `.claude/skills/` can describe the folder structure, how pages and content collections are set up, and the checklist for adding a new section, so every session builds things the same way. ## Step 7: Test it 1. Start a new chat and ask for something the skill should handle: "Write a short blog intro about our new service." 2. Check that Claude uses the skill (the chat shows when a skill is used) and follows the rules. 3. Ask for something unrelated and check that the skill stays out of it. 4. If results are off, improve the description or instructions, upload again and retest. ## Next steps - [Install and share skills](https://viralistic.nl/help/claude/share-skills-with-your-team) - [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) --- # Install and share skills > Install skills you receive, roll skills out to your whole team, and keep one up-to-date version in the Claude apps and in Claude Code. Source: https://viralistic.nl/help/claude/share-skills-with-your-team A skill becomes really valuable when the whole team uses the same version. This article covers installing a skill you received, sharing skills inside a Team or Enterprise organisation, sharing them through a code repository for Claude Code, and keeping everything up to date. To build a skill first, see [Create a skill](https://viralistic.nl/help/claude/create-a-skill). ## Before you install any skill A skill is a set of instructions, and it can include scripts that Claude runs. Treat it like software. 1. Only install skills from people or sources you trust. 2. Open the zip and read `SKILL.md` before you upload it. It is plain text. 3. If the skill contains scripts, check what they do or ask someone technical to look. 4. Be extra careful with skills that tell Claude to send data somewhere or use connectors. > **Warning:** A skill from an unknown website can contain instructions you would never approve, such as copying data to an outside address. If you cannot read and understand it, do not install it. ## Install a skill in the Claude apps Skills need code execution and file creation to be switched on (under **Settings**, then **Capabilities**). 1. Open the Skills section of your settings (currently under **Customize**, then **Skills**). 2. Use the add or upload option and choose the `.zip` file. 3. Check that the skill shows in your list and is switched on. 4. Start a new chat and test it with a request that matches its description. Anthropic's own example skills are listed on the same page. You can switch them on or off like your own. ## Share skills in a Team or Enterprise organisation On Team and Enterprise plans, sharing is managed inside Claude. ### For Owners 1. Open the organisation settings and check that both code execution and Skills are enabled for the organisation. 2. Upload the skills everyone should have. Owners can provision a skill for all members; it then appears in each member's skill list, marked as a team skill. 3. Tell the team what the skill is for and what kind of request triggers it. ### For members - You can share a skill you created with specific colleagues from the skill's menu. Shared skills are view-only for the people you share with. - Depending on your organisation's settings, you can also submit a skill to the organisation's library so anyone can install it. > **Note:** The exact labels in the admin settings change from time to time. If you cannot find an option, look for "Skills" or "Capabilities" in the organisation settings, or check Anthropic's help centre. ## Share skills through a repository (Claude Code) For Claude Code, the simplest way to share is to keep skills inside the project. 1. Put each skill folder in `.claude/skills/` in the repository (see the layout below). 2. Commit and push the folder like any other file. 3. Everyone who opens the project in Claude Code now has the same skills, in the terminal, the desktop app and cloud sessions. ```text your-project/ └── .claude/ └── skills/ ├── house-style/ │ └── SKILL.md └── astro-architecture/ └── SKILL.md ``` Skills that should follow you across all projects go in your personal folder, `~/.claude/skills/`. Those are not shared with anyone. For many repositories or a larger team, skills can be bundled in a Claude Code plugin, which people install once and update centrally. That is mostly worth it once you maintain several skills. ## Keep one source of truth Teams get into trouble when five slightly different copies of the same skill are in use. A few habits prevent that: - **Store the master copy in one place**, ideally a Git repository, even for skills used only in the Claude apps. - **Give each skill an owner** who approves changes. - **Note changes** at the bottom of `SKILL.md` or in a changelog file, with a date. - **Re-upload after every change** in the Claude apps. Uploaded skills do not update themselves. - **Remove skills nobody uses.** Fewer, better skills trigger more reliably. ## Roll out a skill in four steps 1. Test the skill yourself on five real tasks. 2. Let two colleagues use it for a week and collect feedback. 3. Fix the description and instructions based on what went wrong. 4. Share it with everyone and explain in one paragraph when to use it. If you would like help designing and rolling out a skill library for your team, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [Create a skill](https://viralistic.nl/help/claude/create-a-skill) - [What a skill is and when to make one](https://viralistic.nl/help/claude/what-is-a-skill) - [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) --- # Install Claude Code > Install Claude Code in the desktop app, the terminal or VS Code, sign in, and run your first session on a project folder. Source: https://viralistic.nl/help/claude/install-claude-code Claude Code is Anthropic's agentic coding tool. Unlike a normal chat, it works directly in a folder on your computer: it reads files, edits them, runs commands and checks its own work, with your approval. This article helps you pick the right way to run it, install it and start your first session. ## What you need - A paid Claude plan (Pro, Max, Team or Enterprise) or an Anthropic Console account. The Free plan does not include Claude Code. - A supported computer: a recent macOS, Windows 10 or 11, or a common Linux distribution. The [official setup page](https://code.claude.com/docs/en/setup) lists the exact versions. - An internet connection. - A project folder to work in, such as a website repository. On a Team or Enterprise plan, your admin may need to give you a seat that includes Claude Code. ## Choose how you want to use it All versions use the same engine, so your project settings, skills and `CLAUDE.md` work everywhere. | Option | Good for | Needs a terminal | | ---------------------- | -------------------------------------------------------------- | ---------------- | | Desktop app (Code tab) | Non-developers and anyone who prefers buttons and visual diffs | No | | Terminal (CLI) | Developers, automation, the full feature set | Yes | | VS Code or JetBrains | Working inside your code editor | Partly | | Web (claude.ai/code) | Running tasks in the cloud on a GitHub repository | No | If you are unsure, start with the desktop app. For the web version, see [Run Claude Code in the cloud](https://viralistic.nl/help/claude/claude-code-on-the-web). ## Option 1: Desktop app 1. Download the Claude desktop app from [claude.com/download](https://claude.com/download) and install it. 2. Open the app and sign in. 3. Click the **Code** tab at the top. 4. Choose **Local** to work with files on your computer. 5. Click **Select folder** and choose your project folder. 6. Type a first request and press Enter. The desktop app already contains Claude Code. You do not need to install anything else. ## Option 2: Terminal ### Install Open a terminal and run the command for your system. These are the official native installers. macOS, Linux or WSL: ```bash curl -fsSL https://claude.ai/install.sh | bash ``` Windows PowerShell: ```text irm https://claude.ai/install.ps1 | iex ``` Windows Command Prompt (CMD): ```text curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ``` If you use Homebrew on a Mac, `brew install --cask claude-code` works too. Other options (WinGet, Linux package managers, npm) are on the official setup page. > **Note:** On Windows, installing Git for Windows is recommended so Claude Code can use Bash. Without it, Claude Code uses PowerShell instead. ### Check the installation Open a **new** terminal window and run: ```bash claude --version ``` You should see a version number. If the terminal says `claude` is not found, close and reopen the terminal first. If that does not help, run `claude doctor` or follow the PATH fix in the official troubleshooting guide. ### Start and sign in Go to your project folder and start Claude Code: ```bash cd path/to/your-project claude ``` 1. The first time, Claude Code asks you to log in and opens a browser window. 2. Sign in with your Claude account and approve. 3. Back in the terminal, you see the Claude Code prompt. You stay signed in from now on. ## Option 3: VS Code 1. Open the Extensions view in VS Code. 2. Search for "Claude Code" and install the extension published by Anthropic. 3. Open the Command Palette, type "Claude Code" and open it in a new tab. 4. Sign in when asked. For JetBrains IDEs, install the Claude Code plugin from the JetBrains Marketplace. It also needs the terminal version installed. ## Your first session Start by letting Claude look around before it changes anything: ```text What does this project do? Explain the folder structure in plain language. ``` Then try a small, safe change, and review it before you accept it. Useful commands and keys: | Command or key | What it does | | -------------- | ------------------------------------------------------------------------ | | `/help` | Lists available commands | | `/init` | Creates a starter `CLAUDE.md` for the project | | `Shift+Tab` | Switches permission mode (for example to plan first, or to accept edits) | | `Esc` | Stops Claude mid-task so you can redirect it | | `/rewind` | Rolls back the conversation and Claude's file edits to an earlier point | | `/clear` | Starts a fresh conversation | > **Warning:** Rewind only undoes edits Claude made with its own editing tools, not everything a command did. Use Git (or at least a backup copy) for any project you care about. ## Keep it up to date The native installer updates itself in the background. Homebrew and WinGet installs do not: run `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` from time to time. You can always update manually with `claude update`. ## Next steps - [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) - [Claude Code for non-developers](https://viralistic.nl/help/claude/claude-code-for-non-developers) - [Run Claude Code in the cloud](https://viralistic.nl/help/claude/claude-code-on-the-web) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) --- # Claude Code for non-developers > Use Claude Code in the desktop app to edit website text, tidy files and process data safely, without writing code or opening a terminal. Source: https://viralistic.nl/help/claude/claude-code-for-non-developers Claude Code sounds like a tool for programmers, but at its core it is Claude working directly in a folder on your computer. That makes it useful for marketers, founders, content editors and project managers too. This article shows what you can do with it, how to set it up without a terminal and how to work safely. ## What it is good for If the work lives in files, Claude Code can probably help. Some examples: - **Website text.** Update copy, prices or team bios on a site built with a framework such as Astro, without hunting through folders yourself. - **Files and folders.** Rename 200 photos by date, sort documents into folders, find duplicates. - **Spreadsheets and data.** Clean a messy CSV export, merge two lists, compare this month's numbers with last month's. - **Documents.** Turn a folder of meeting notes into one summary, or convert Markdown files to another format. - **Small tools.** A script that resizes images or checks a list of links, built and explained by Claude. The difference with a normal chat: you do not copy and paste. Claude opens the files, makes the changes and shows you exactly what it changed. ## Set it up without a terminal You need a paid Claude plan (Pro, Max, Team or Enterprise). 1. Install the Claude desktop app from [claude.com/download](https://claude.com/download) and sign in. 2. Click the **Code** tab. 3. Choose **Local**. 4. Click **Select folder** and choose the folder you want to work in. 5. Pick a permission mode next to the send button (see below). > **Tip:** Only open the folder you need, not your whole Documents folder. Claude can only work in what you give it, and a smaller folder keeps things safe and fast. ## Choose how much control you want The permission mode decides when Claude asks before acting. | Mode | What happens | Use it when | | ------------ | ---------------------------------------------------------------------- | ----------------------------------------------- | | Manual | Claude asks before every file change or command | You are starting out or the folder is important | | Plan | Claude only reads and proposes a plan, no changes | You want to agree on the approach first | | Accept edits | Claude changes files without asking each time; you review afterwards | You trust the task and want speed | | Auto | A safety check reviews actions in the background and blocks risky ones | You are experienced and the task is routine | Start with **Plan** for anything bigger, switch to **Manual** to carry it out, and only move on to faster modes once you are comfortable. ## A safe first workflow 1. **Make a backup.** Copy the folder, or ask Claude: "Set up Git version control for this folder so every change can be undone, and explain in two sentences what that means." 2. **Ask Claude to look first.** "Look through this folder and tell me in plain language what is in it. Do not change anything." 3. **Describe the outcome you want.** Be as specific as you would be with a colleague. 4. **Review the plan.** Ask questions until it makes sense. 5. **Let Claude do it** and review each change in the diff view (red is removed, green is added). 6. **Check the result** yourself: open the file, view the page, look at the spreadsheet. ## Example requests Website text: ```text On the About page, change the opening paragraph to the text below. Keep the layout the same. Show me the change before you save it. [new text] ``` Data clean-up: ```text The file leads-export.csv has duplicate rows and inconsistent country names (NL, Netherlands, Nederland). Make a cleaned copy called leads-clean.csv: one row per email address, country names in English. Do not change the original file. Tell me how many duplicates you removed. ``` File tidying: ```text Rename all photos in the "event-2026" folder to the format 2026-05-14-001.jpg, based on the date each photo was taken. First list ten examples of old and new names so I can check. ``` > **Tip:** Type `@` followed by a file name to point Claude at a specific file. You can also drag files into the prompt box. ## When something goes wrong - **Claude is going the wrong way:** click stop and type a correction. You do not have to start over. - **You do not like a change:** reject it in Manual mode, or ask Claude to undo it. With Git set up, you can always go back to an earlier version. - **You do not understand what Claude did:** ask "Explain what you just changed and why, without jargon." > **Warning:** Be careful with anything that publishes, sends or deletes: pushing a website live, emailing a list, removing files. Ask Claude to stop before those steps so you can check first. ## Make it remember your preferences If you work in the same folder often, ask Claude to create a `CLAUDE.md` file with notes about the project and how you like to work. Claude reads it at the start of every session. See [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md). Want a hands-on session where we set this up together for your own website or files? Book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) - [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) --- # Write a CLAUDE.md > Create a CLAUDE.md file so Claude Code knows your project's commands, structure and rules at the start of every session. Source: https://viralistic.nl/help/claude/write-a-claude-md Every Claude Code session starts with a blank slate. `CLAUDE.md` is a plain Markdown file in your project that Claude Code reads at the start of each session, so it knows how the project works without you explaining it again. This article covers where the file goes, what to put in it and how to keep it useful. ## Where CLAUDE.md files live You can have more than one. Claude Code loads them all and combines them. | File | Scope | Shared with | | -------------------------------------------------------- | --------------------------------- | --------------------------------- | | `CLAUDE.md` or `.claude/CLAUDE.md` in the project folder | This project | Everyone, through Git | | `CLAUDE.local.md` in the project folder | This project, your personal notes | Only you (add it to `.gitignore`) | | `~/.claude/CLAUDE.md` in your home folder | All your projects | Only you | Most teams start with one `CLAUDE.md` in the root of the repository and commit it. ## Create a starter file The quickest start is to let Claude write the first version. 1. Open the project in Claude Code (terminal, desktop app or VS Code). 2. Run `/init`. 3. Claude scans the project and writes a `CLAUDE.md` with the commands, structure and conventions it finds. 4. Read it, delete what is wrong or obvious, and add what Claude could not know. If a `CLAUDE.md` already exists, `/init` suggests improvements instead of overwriting it. ## What to put in it Write down what you would otherwise repeat in every session, or what a new teammate would need on day one. - **What the project is**, in two or three sentences. - **Commands**: how to install, start the dev server, build and test. - **Structure**: where the important things live. - **Conventions**: naming, styling, language, formatting. - **Rules**: things Claude must always or never do. - **How to check work**: which command proves a change is correct. ## An example Here is a compact `CLAUDE.md` for an Astro website: ```md # Project: company website Marketing site built with Astro and Tailwind. Content is Markdown in src/content/. Deployed on Netlify from the main branch. ## Commands - Install: npm install - Dev server: npm run dev (http://localhost:4321) - Build: npm run build (must pass before you say a task is done) ## Structure - src/content/pages/: one Markdown file per page - src/components/: reusable UI components - src/layouts/: page layouts - public/images/: images, referenced as /images/... ## Conventions - Write UI text in Dutch unless the file is under src/content/pages/en/. - Use existing components before creating new ones. - Tailwind classes only, no new CSS files. - File names in kebab-case. ## Rules - Never edit files in dist/ or node_modules/. - Never commit .env files or API keys. - Ask before adding a new npm package. - Do not push to main. Work on a branch and tell me when it is ready. ``` ## Write instructions Claude can follow Claude treats `CLAUDE.md` as guidance, so clear wording matters. | Vague | Concrete | | ------------------------------ | -------------------------------------------------------------------- | | "Keep the code clean" | "Use 2-space indentation and run `npm run lint` before finishing" | | "Test your changes" | "Run `npm run build` and fix all errors before you say you are done" | | "Put files in the right place" | "Page content goes in `src/content/pages/`" | > **Tip:** Explain the reason behind a surprising rule. "Do not rename files in src/content/pages/, because the file name is the page URL" works better than "do not rename files". ## Keep it short Aim for under about 200 lines. A long file uses more of Claude's working memory and makes each rule less likely to be followed. - Leave out things Claude can see for itself, such as every dependency in `package.json`. - Move long procedures (for example "how to add a new page type") into a [skill](https://viralistic.nl/help/claude/what-is-a-skill). Skills only load when needed. - Point to longer documents instead of copying them. You can import a file by writing `@` and its path, for example `@docs/brand-guidelines.md`. Imported files still load at the start of every session, so use this sparingly. > **Warning:** Never put passwords, API keys or customer data in `CLAUDE.md`. The project file is usually committed to Git and visible to everyone with access to the repository. ## Maintain it `CLAUDE.md` gets better through use. 1. When Claude makes the same mistake twice, add a rule. 2. When you correct Claude in chat with something that will always be true, ask: "Add that to CLAUDE.md." 3. Every month or so, remove rules that are outdated or contradict each other. 4. To check which memory files a session loaded, run `/context`. Changes to `CLAUDE.md` go through Git like any other file, so the whole team benefits from each improvement. ## Next steps - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) - [Create a skill](https://viralistic.nl/help/claude/create-a-skill) - [How a Viralistic Astro site is organised](https://viralistic.nl/help/astro/project-structure) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) --- # Run Claude Code in the cloud > Start Claude Code tasks from your browser or phone at claude.ai/code, let them run in the cloud on a GitHub repository, and review the result as a pull request. Source: https://viralistic.nl/help/claude/claude-code-on-the-web Claude Code can also run in the cloud instead of on your computer. You start a task from your browser or phone, Claude works on a copy of your GitHub repository in a secure virtual machine, and you review the result when it is done, even if you closed your laptop in the meantime. This article covers setup, your first task and when the cloud is the better choice. ## What you need - A Claude plan with cloud sessions: Pro, Max or Team, or an Enterprise seat that includes Claude Code. - A GitHub account and a repository. Cloud sessions clone and push through GitHub. - On Team and Enterprise plans, an Owner may first need to turn on the GitHub connector for the organisation. ## Cloud or local? | | Cloud session | Local session | | ---------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------- | | Runs on | A virtual machine managed by Anthropic | Your computer | | Start from | claude.ai/code, the mobile app, the desktop app (Cloud), or `claude --cloud` | Terminal, editor or desktop app (Local) | | Keeps going when you disconnect | Yes | No | | Uses your local files and settings | No, only what is in the repository | Yes | | Needs GitHub | Yes | No | Cloud sessions shine for well-defined tasks you do not need to steer constantly, for running several tasks in parallel, and for working on repositories you do not have on your computer. For work that depends on local tools or files, run Claude Code locally. ## Connect GitHub You only do this once. 1. Go to [claude.ai/code](https://claude.ai/code) and sign in with your Claude account. 2. Follow the prompt to connect GitHub and approve the authorisation on GitHub. 3. For private repositories, install the Claude GitHub App on the GitHub account or organisation that owns them. A GitHub organisation owner may need to approve this. 4. Let onboarding create your **Default** environment (on Team and Enterprise you may see a short form; the prefilled values are fine). > **Note:** If your repository does not show up after connecting, the Claude GitHub App is usually not installed on that account or does not have access to that repository. Check the app's repository access settings on GitHub. ## Understand environments An environment is the saved setup every cloud session runs in. You can edit it or create more from the environment selector. | Setting | What it controls | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Network access | Which websites the session can reach. **Trusted** (the default) allows package registries, GitHub and other common developer domains. **None**, **Full** and **Custom** are the other options. | | Environment variables | Values the project needs, in `.env` format | | Setup script | A Bash script that runs before Claude starts, for example to install dependencies | A simple setup script for a Node.js project: ```bash #!/bin/bash npm install ``` > **Warning:** Environment variables are visible to anyone who can use that environment. Do not put production passwords or secret keys there. Use test credentials, or keep tasks that need real secrets local. ## Start your first task 1. At claude.ai/code, pick the repository and, if needed, a branch. 2. Choose a permission mode. **Plan** proposes an approach and waits for your approval. **Accept edits** works through the task without stopping. Some accounts also see **Auto**. 3. Describe the task specifically, as you would to a colleague. Name files, paste error messages and describe the expected result. 4. Submit. Each task gets its own session and its own branch, so you can start another task straight away. A good cloud task: ```text In src/content/pages/, find all pages without a meta description and add one of 140 to 155 characters based on the page content. Run npm run build to confirm nothing breaks. Do not change any other files. ``` ## Review and create a pull request 1. When Claude is done, open the diff (shown as something like `+42 -18`). 2. Read the changes file by file. Click a line to leave a comment, then send your next message; Claude gets the comments with it. 3. When the diff looks right, choose **Create PR**. 4. The session stays open after the PR. Paste reviewer comments or failing checks into the chat and ask Claude to fix them. If the Claude GitHub App is installed, you can also turn on auto-fix so Claude responds to failing checks and review comments by itself. ## Work across devices - Check on running sessions from the Claude mobile app and answer Claude's questions there. - From the terminal, start a cloud task with `claude --cloud "your task"`. - Pull a cloud session into your terminal with `claude --teleport` to continue locally. This needs a clean Git state and the same Claude account. ## Limits to keep in mind - Cloud sessions use the same usage allowance as the rest of your Claude account. Parallel tasks use it faster. - Repository cloning and pull requests need GitHub. - Sessions go idle after a period of inactivity. Reopening one restores the conversation, but not background work that was still running. ## Next steps - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) - [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md) - [Deploy to Netlify](https://viralistic.nl/help/astro/deploy-to-netlify) --- # Get n8n: cloud or self-hosted > Decide between n8n Cloud and self-hosting, and get a working n8n instance with Docker, the one-line installer or npm. Source: https://viralistic.nl/help/n8n/get-n8n n8n comes in two flavours: n8n Cloud, which n8n hosts for you, and self-hosted n8n, which you run on your own server. Both run the same product. This article helps you pick one and get it running, so you can start building workflows today. ## The short answer - **Pick n8n Cloud** if you want to start right now, have no one to look after a server, or simply prefer that updates, backups and uptime are someone else's job. - **Pick self-hosting** if you need full control over where your data lives, want to install custom or community nodes freely, or have someone technical who can maintain a server. You can always move later. Workflows are JSON files, so you can export them from one instance and import them into another. ## Cloud versus self-hosted | | n8n Cloud | Self-hosted | | ------------------- | ----------------------------- | ---------------------------------------------------- | | Setup | Sign up and start | Install and configure a server | | Updates and backups | Handled by n8n | Your responsibility | | Cost | Paid plans after a free trial | Free Community edition, paid plans for team features | | Control | Limited to what n8n offers | Full control over configuration and data location | | Webhooks and MCP | Public URL out of the box | You need a domain and HTTPS | Plans and limits change regularly, so check the [n8n pricing page](https://n8n.io/pricing/) for current tiers, execution limits and prices. In short: Cloud plans differ in limits and team features, and self-hosted n8n has a free Community edition plus paid Business and Enterprise plans for features such as SSO, projects and environments. > **Tip:** On a self-hosted Community edition you can unlock a few extra features for free by registering your email. Look for Usage and plan in the settings. ## Option 1: n8n Cloud 1. Go to [n8n.io](https://n8n.io/) and start a free trial. 2. Choose a name for your instance. It becomes part of your address, for example `yourcompany.app.n8n.cloud`. 3. In your n8n Cloud dashboard, select Manage and set the Timezone, so schedules run at your local time. 4. Open your instance and build your [first workflow](https://viralistic.nl/help/n8n/first-workflow). ## Option 2: Self-host with Docker Docker is the method n8n recommends for self-hosting. You need a machine with Docker installed: your own computer for testing, or a small cloud server (VPS) for real use. ### Quick start with the one-line installer n8n now offers an installer that checks Docker, writes the configuration files and starts n8n for you: ```bash curl -fsSL https://get.n8n.io | sh ``` It creates an `n8n` folder with a `compose.yml` and a `.env` file, and stores your data in a Docker volume. Read the [official install guide](https://docs.n8n.io/) before you run it on a server. ### Plain Docker with a persistent volume If you prefer to see every setting, run n8n with a single `docker run` command. The volume is the important part: it keeps your workflows, credentials and encryption key when the container is replaced. ```bash docker volume create n8n_data docker run -d \ --name n8n \ --restart unless-stopped \ -p 5678:5678 \ -e GENERIC_TIMEZONE="Europe/Amsterdam" \ -e TZ="Europe/Amsterdam" \ -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \ -v n8n_data:/home/node/.n8n \ n8nio/n8n ``` Open `http://localhost:5678` and create the owner account. > **Warning:** Without the `-v n8n_data:/home/node/.n8n` line, everything you build disappears when the container is removed. Never skip the volume. ### Before you go live A test install on your laptop is fine as it is. For production, also: 1. Put n8n on its own subdomain, such as `n8n.yourcompany.com`, behind a reverse proxy with HTTPS. 2. Set the `WEBHOOK_URL` environment variable to that public address, so webhook URLs are correct. 3. Use PostgreSQL instead of the built-in SQLite database once several people or busy workflows depend on it. 4. Set up backups and an update routine. See [Update and back up a self-hosted n8n](https://viralistic.nl/help/n8n/self-hosting-maintenance). ## Option 3: npm (for local testing) If you already use Node.js, you can try n8n without Docker: ```bash npx n8n ``` Or install it globally with `npm install n8n -g` and start it with `n8n start`. > **Note:** n8n has deprecated npm installs from version 3.0 and now distributes new installs through Docker. Use npm only for a quick local test, not for a server you depend on. ## Which one do we recommend? For most small teams, n8n Cloud is the fastest way to get value. Self-host when data location, custom nodes or cost at high volume really matter, and when someone owns maintenance. If you would rather have a self-hosted instance set up and maintained for you, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [n8n basics: nodes, triggers and executions](https://viralistic.nl/help/n8n/n8n-basics) - [Build your first workflow](https://viralistic.nl/help/n8n/first-workflow) - [Update and back up a self-hosted n8n](https://viralistic.nl/help/n8n/self-hosting-maintenance) --- # n8n basics: nodes, triggers and executions > Learn the handful of n8n concepts you need to read, build and debug any workflow, from triggers and nodes to items, expressions and executions. Source: https://viralistic.nl/help/n8n/n8n-basics n8n looks busy the first time you open it, but almost everything comes down to a few ideas. This article explains them in plain language. Once these click, any workflow you open, including ones Claude builds for you, becomes readable. ## Workflows A workflow is one automated process, drawn on a canvas as boxes connected by lines. Read it from left to right: something happens, then a series of steps runs. Good workflows do one job. "Process new invoices" is a good workflow. "Everything finance" is not. Small workflows are easier to test, debug and hand over. ## Nodes Each box on the canvas is a node. A node does one thing: read a spreadsheet, send an email, filter data. There are four kinds you will meet: | Kind | What it does | Examples | | ------------- | ------------------------------- | ----------------------------------------------------------------- | | Trigger nodes | Start the workflow | Schedule Trigger, Webhook, n8n Form Trigger, Email Trigger (IMAP) | | App nodes | Talk to a service | Gmail, Google Sheets, Slack, HubSpot | | Core nodes | Shape data and control the flow | Edit Fields (Set), IF, Switch, Merge, Code, HTTP Request | | AI nodes | Add a language model | AI Agent, Basic LLM Chain, Guardrails | The HTTP Request node deserves a special mention: it can call almost any API, even for apps without their own node. ## Triggers Every workflow that runs on its own starts with a trigger. Common ones: - **Schedule Trigger:** run every hour, every Monday at 9:00, and so on. See [Run workflows on a schedule](https://viralistic.nl/help/n8n/schedules). - **Webhook:** run when another system sends data to a URL. See [Receive data with webhooks](https://viralistic.nl/help/n8n/webhooks). - **App triggers:** run when something happens in an app, such as a new email or a new form entry. - **Manual Trigger:** run only when you click the button. Handy while building. ## Connections and items Data flows along the connections as a list of **items**. Each item is one record, for example one email or one spreadsheet row. If a node receives ten items, it normally runs ten times, once per item. You rarely need a loop. Click any node after a run to see its input and output. You can switch between Table, JSON and Schema views. This is the fastest way to understand what a workflow is doing. ## Expressions Expressions let a node use data from earlier steps. They sit between double curly braces: ```text Hello {{ $json.firstName }}, thanks for your order {{ $json.orderId }}. ``` `$json` means "the current item". The easiest way to build an expression is to drag a field from the input panel into a parameter. n8n writes the expression for you. ## Credentials Credentials are the saved logins and API keys nodes use to reach your apps. You create them once and reuse them across workflows. n8n stores them encrypted. See [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials). ## Executions An execution is one run of a workflow. There are two types: - **Manual executions** happen when you click Execute workflow or Execute step while building. You see the data on the canvas. - **Production executions** happen automatically after you publish the workflow and its trigger fires. You review them in the Executions tab of the workflow, or in the overview of all executions. When something fails, open the failed execution. It shows the exact node that broke and the data it received. > **Tip:** Pin the output of a trigger node while building. n8n then reuses that test data on every run, so you do not have to send a new email or form entry each time. ## Saving and publishing n8n saves your work automatically while you edit. Your changes stay a draft until you click **Publish**. Publishing makes the workflow live: schedules start, webhook and form triggers switch to their production URLs, and app triggers start listening. Later edits only go live when you publish again. > **Note:** Older n8n versions used an Active toggle instead of a Publish button. If you follow an older tutorial, "activate" means the same as "publish". ## Next steps - [Build your first workflow](https://viralistic.nl/help/n8n/first-workflow) - [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Build your first workflow > Build a small, useful workflow from scratch, a contact form that stores every request in a table, and learn to test and publish it. Source: https://viralistic.nl/help/n8n/first-workflow This walkthrough is for anyone who has n8n open for the first time. You build a contact form that saves every submission in an n8n Data Table. It needs no outside accounts or API keys, and it teaches the full cycle: trigger, transform, store, test and publish. ## What you will build ```text n8n Form Trigger → Edit Fields → Data Table (insert row) ``` A visitor fills in a form. n8n tidies the answers and adds a timestamp. The result lands as a new row in a table you can view, filter and download. ## Before you start - A running n8n instance. See [Get n8n: cloud or self-hosted](https://viralistic.nl/help/n8n/get-n8n). - Ten minutes of quiet. No coding needed. ## Step 1: Create the workflow 1. Select the create button (the plus) in the top left of the side menu and choose Workflow. 2. Click the title at the top and rename it to `Contact form to table`. ## Step 2: Add the form trigger 1. Select **Add first step** and search for `form`. 2. Choose **n8n Form Trigger** (listed as "On form submission"). 3. Set **Form Title** to `Contact us`. 4. Add three form elements: `Name` (text), `Email` (email) and `Message` (textarea). Make all three required. 5. Select **Execute step**. n8n opens the test form in a new tab. 6. Fill it in with test data, including an email with a capital letter such as `Jane@Example.com`, and submit. Back in n8n, the node now shows your answers as output. > **Tip:** Click the pin icon on the output panel to pin this data. From now on, n8n reuses it on every test run, so you do not have to fill in the form again. ## Step 3: Tidy the data 1. Click the plus to the right of the form node and add **Edit Fields (Set)**. 2. Add four fields of type String, and set their values with expressions. You can drag fields from the input panel on the left, then adjust: | Field name | Value | | ------------ | ---------------------------------------- | | `name` | `{{ $json.Name.trim() }}` | | `email` | `{{ $json.Email.trim().toLowerCase() }}` | | `message` | `{{ $json.Message }}` | | `receivedAt` | `{{ $now.toISO() }}` | 3. Select **Execute step** and check the output. The email should now be in lower case. ## Step 4: Create the table 1. Open your project overview in a new tab and go to the **Data tables** tab. 2. Create a data table called `Contact requests`, starting from scratch. 3. Add four columns of type String: `name`, `email`, `message` and `receivedAt`. ## Step 5: Store each request 1. Back in the workflow, add a **Data Table** node after Edit Fields. 2. Set the resource to **Row** and the operation to **Insert**. 3. Pick `Contact requests` from the list. 4. Set the mapping mode to **Map Automatically**. This works because your field names match the column names exactly. 5. Select **Execute workflow**. Open the data table and confirm your test row is there. ## Step 6: Publish 1. Unpin the test data on the form node if you pinned it. Production runs ignore pinned data, but unpinning keeps things clear. 2. Click **Publish** in the top right and confirm. 3. Open the form node and switch to the **Production URL**. This is the address to share or link from your website. 4. Submit the form once through that URL. 5. Open the **Executions** tab of the workflow. You should see one successful run, and a new row in your table. > **Note:** The test URL only works while you are testing in the editor. Always share the production URL. ## Make it your own Some easy next additions: - Add a **Gmail** or **Send Email** node to notify you of each new request. This needs a credential, see [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials). - Add an **IF** node to flag messages that contain words like "urgent" or "quote". - Add an AI step that drafts a reply for you to review. See [The AI Agent node explained](https://viralistic.nl/help/n8n/ai-agent-node). > **Warning:** A public form can attract spam. Before you link it from a live site, consider adding a check for empty or suspicious messages, and keep an eye on the table for the first few days. ## Next steps - [Store data with Data Tables](https://viralistic.nl/help/n8n/data-tables) - [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) - [Build workflows with Claude](https://viralistic.nl/help/n8n/build-workflows-with-claude) --- # Connect your apps with credentials > Create, name, test and share n8n credentials safely, for API keys, OAuth sign-ins and email accounts. Source: https://viralistic.nl/help/n8n/credentials Before n8n can read your inbox or post to Slack, it needs permission. That permission lives in a credential: a saved login, API key or OAuth connection that nodes reuse. This article shows how to create credentials, the three types you will meet, and how to keep them safe. ## How credentials work You create a credential once, give it a clear name, and pick it in any node that talks to that app. n8n stores credentials encrypted in its database. People who use a workflow do not see the secret itself, only the credential name. If the password or key changes, you update the credential in one place and every workflow that uses it keeps working. ## Create a credential There are two ways to start: ### From a node (easiest) 1. Open the node, for example Gmail or Google Sheets. 2. In the **Credential to connect with** dropdown, choose to create a new credential. 3. Fill in the fields or sign in (see the types below). 4. Save. n8n tests the credential and shows whether it works. ### From the overview 1. Select the create button (the plus) in the side menu and choose Credential. 2. If your instance uses projects, choose the project the credential belongs to. 3. Search for the app, fill in the details and save. ## The three types you will meet | Type | What you enter | Typical apps | | --------------------- | ----------------------------------------- | -------------------------------------------- | | API key or token | A key you copy from the app's settings | OpenAI, Anthropic, Airtable, many SaaS tools | | OAuth2 | You click a button and sign in to the app | Google, Microsoft, Slack, HubSpot | | Username and password | Server, port, user and password | IMAP and SMTP email, databases, FTP | ### API keys Create the key in the other app, usually under Settings, Developer or API. Give it the smallest permissions that still work, and paste it into n8n. Many apps show the key only once, so paste it straight away. ### OAuth2 On n8n Cloud, many popular apps offer a one-click sign-in from the credential screen. On a self-hosted instance you often need to create your own OAuth app with the provider first (for example in Google Cloud Console), then paste its client ID and client secret into n8n. The credential screen shows the **OAuth Redirect URL** that you must register with the provider. > **Note:** For Google, make sure the right APIs are enabled in your Google Cloud project (such as the Gmail API or Google Sheets API). A missing API is the most common reason a Google credential connects but the node still fails. ### Email accounts For IMAP and SMTP you enter the server, port, username and password. Many providers require an app password instead of your normal password. See [Process incoming email with the IMAP trigger](https://viralistic.nl/help/n8n/imap-trigger). ## Name credentials so you can find them n8n names a new credential "app name account" by default. Rename it right away. A good pattern is app, account and purpose: ```text Gmail / info@yourcompany.com / support inbox Slack / Viralistic workspace / alerts bot ``` Clear names prevent the classic mistake of sending customer emails from a personal account. ## Share credentials with your team Depending on your plan, you can share a credential with colleagues or keep it inside a shared project. Teammates can then use it in their workflows without ever seeing the password or key. This is safer than sending keys over chat. See [Share logins and access safely](https://viralistic.nl/help/account/share-access-safely) for the general rules we follow. ## Keep credentials safe 1. Use a dedicated account or bot user for automations where possible, not your personal login. 2. Give each key the minimum scope it needs. 3. On credentials for web APIs, use **Allowed HTTP Request Domains** to limit which domains the credential may be sent to from an HTTP Request node. 4. Never paste keys into a Code node, a sticky note or a chat with an AI assistant. Always use a credential. 5. Rotate keys when someone leaves the team, and delete credentials you no longer use. > **Warning:** On a self-hosted instance, credentials are encrypted with a key stored in the n8n data folder (or in the `N8N_ENCRYPTION_KEY` variable). If you lose that key, you lose every credential. Include it in your backups, see [Update and back up a self-hosted n8n](https://viralistic.nl/help/n8n/self-hosting-maintenance). ## When a credential stops working - **Expired OAuth connection:** open the credential and reconnect. - **Changed password or revoked key:** update the value and save to retest. - **Permission errors:** the account works but lacks access to that file, channel or mailbox. Fix it in the app, not in n8n. ## Next steps - [Build your first workflow](https://viralistic.nl/help/n8n/first-workflow) - [Process incoming email with the IMAP trigger](https://viralistic.nl/help/n8n/imap-trigger) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Use the n8n MCP server > Connect Claude to your n8n instance through MCP so it can find, run and build workflows, and learn the MCP Server Trigger and MCP Client Tool nodes. Source: https://viralistic.nl/help/n8n/n8n-mcp MCP (Model Context Protocol) is the standard way for AI assistants like Claude to use outside tools. n8n speaks MCP in three different ways, and they are easy to mix up. This article explains all three and walks you through the one most people want first: letting Claude work directly with your n8n instance. ## Three ways n8n and MCP meet | Feature | Direction | Use it to | | ------------------------- | --------------------------- | ------------------------------------------------------- | | Instance-level MCP server | Claude uses your n8n | Let Claude search, run, test and build workflows | | MCP Server Trigger node | Claude uses one workflow | Offer a hand-picked set of tools from a single workflow | | MCP Client Tool node | n8n uses another MCP server | Give an n8n AI Agent tools from an external service | ## The instance-level MCP server This is built into n8n, on Cloud and self-hosted. Once you connect Claude, it can: - Search your workflows and read the ones you expose. - Run exposed workflows and check their executions. - Test workflows with sample (pinned) data. - Create and edit workflows and data tables, and publish workflows. > **Note:** Building and editing workflows over MCP needs a recent n8n version (2.13 or later, according to the n8n docs). Older instances can only search and run workflows. Menu names below match current versions and may differ slightly on older ones. ### Turn it on 1. In n8n, open **Settings** and go to **Instance-level MCP**. You need to be the instance owner or an admin. 2. Select **Enable MCP access**. 3. In **Connection details**, select **Connect**. A dialog shows the **Server URL**, which ends in `/mcp-server/http`. The dialog offers two ways to authenticate: **OAuth** (recommended, you approve each client in n8n) or an **API key** (a personal access token sent as a bearer header). n8n shows the token only once, so copy it straight into your client. ### Connect Claude (desktop app or claude.ai) 1. In the n8n **Connect** dialog, choose your client. For claude.ai there is a one-click setup. 2. Or add it yourself: in Claude, open **Settings**, then **Connectors**, and add a custom connector. 3. Paste the **Server URL**. This is not the address of your n8n editor, so do not copy it from the browser bar. 4. Save, then approve the access request that n8n shows you. See [Connect Claude to your tools](https://viralistic.nl/help/claude/connectors) for more on connectors. ### Connect Claude Code Run this in your terminal, with your own domain: ```bash claude mcp add --transport http n8n https://your-n8n-domain/mcp-server/http ``` Then run `/mcp` inside Claude Code, select **n8n** and complete the sign-in. To use an API key instead, add `--header "Authorization: Bearer YOUR_TOKEN"` to the command. ### Choose which workflows Claude can use Claude can see short previews of every workflow you have access to, but it can only open, run or change workflows you expose. To expose one: 1. Open the workflow, open the workflow menu (the three dots) and choose **Settings**. 2. Turn on **Available in MCP**. You can also do this from the workflow list, or in bulk from the Instance-level MCP settings page. Add a clear description to each exposed workflow so Claude knows when to use it. To be exposed, a workflow must be published and start with a webhook, form, schedule or chat trigger. Workflows that Claude creates over MCP are exposed automatically. > **Warning:** Every client you connect sees every workflow you exposed. You cannot limit a workflow to one client. Expose only what you are comfortable letting an AI run, and revoke clients you no longer use under **Connected clients**. If you self-host, Claude.ai and the Claude apps need to reach your instance over the internet with HTTPS. A local `localhost` install only works with Claude Code on the same machine. ## MCP Server Trigger node Use this node when you want to offer a small, controlled set of tools rather than your whole instance. You add the MCP Server Trigger to a workflow and attach tool nodes to it, for example a **Call n8n Workflow Tool** that runs a sub-workflow to look up a customer. The node gets its own MCP URL (test and production), with optional bearer or header authentication. Publish the workflow, then add the production URL to Claude as a connector. ## MCP Client Tool node This works the other way round. Attach an **MCP Client Tool** to an n8n **AI Agent** node and the agent can use the tools of any external MCP server, such as your CRM or a documentation server. Enter the server endpoint, choose an authentication method, and under **Tools to Include** pick All, Selected or All Except. Exposing only the tools the agent needs keeps it focused and safer. For a fixed, non-AI step, the regular **MCP Client** node calls one chosen tool. ## A community alternative The open source project [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) by Romuald Czlonkowski gives Claude detailed documentation for n8n's nodes, plus optional workflow management through the n8n API. It is maintained independently of n8n. For most teams, the official instance-level server is the simpler and better supported choice. ## Next steps - [Build workflows with Claude](https://viralistic.nl/help/n8n/build-workflows-with-claude) - [The AI Agent node explained](https://viralistic.nl/help/n8n/ai-agent-node) - [Connect Claude to your tools](https://viralistic.nl/help/claude/connectors) - [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code) --- # Build workflows with Claude > A practical method to let Claude draft n8n workflows for you, then review, test with pinned data and publish them with confidence. Source: https://viralistic.nl/help/n8n/build-workflows-with-claude Claude can draft a complete n8n workflow from a plain description of your process. The draft is rarely perfect, but it gets you to a working version much faster than starting from an empty canvas. This article gives you a repeatable method: describe, draft, review, test, publish. ## Two ways to work | Route | How it works | Best for | | -------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | | Through the n8n MCP server | Claude looks up the nodes on your instance, writes the workflow, validates it and saves it in n8n | Regular building, bigger workflows | | Workflow JSON | Claude writes the workflow as JSON, you paste or import it | A quick one-off, or when MCP is not set up | The MCP route is more reliable, because Claude checks node names and settings against your actual n8n version. Set it up first with [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp). If you use Claude Code, the official [n8n Skills](https://github.com/n8n-io/skills) add n8n best practices on top. ## Step 1: Prepare credentials Create the credentials the workflow will need in n8n first, for example your Gmail and Slack accounts. See [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials). When Claude creates a workflow over MCP, n8n assigns matching credentials it finds. Claude never sees the secrets themselves. ## Step 2: Describe the process Brief Claude like a new colleague. Cover: 1. **Trigger:** what starts it (a new email, a form, every Monday at 9:00). 2. **Input:** what the data looks like, ideally with one real example. 3. **Steps:** what should happen, in order, including decisions. 4. **Output:** where the result goes and what it looks like. 5. **Edge cases:** what to do when data is missing or something fails. For more on briefing, see [Brief Claude like a colleague](https://viralistic.nl/help/claude/write-better-prompts). ## Step 3: Let Claude draft it Example prompts: ```text Build an n8n workflow that runs every weekday at 8:30 Amsterdam time. It reads yesterday's new rows from the Google Sheet "Leads 2026", skips rows without an email address, and posts a short summary to the Slack channel #sales: number of new leads and the top 3 by budget. Use my existing Google Sheets and Slack credentials. Do not publish yet. ``` ```text Create a workflow with an n8n Form Trigger for event registrations (name, email, company, dietary needs). Store each registration in a data table called "Event registrations" and stop duplicates by email. Add a sticky note that explains each step in plain language. ``` ```text Open the workflow "Invoice intake" and add error handling: retry the Google Drive upload 3 times, and set my "Error alerts" workflow as its error workflow. Show me what you changed. ``` Without MCP, end your prompt with: "Return the workflow as n8n workflow JSON that I can paste into the canvas." Then copy the JSON, click an empty spot on the n8n canvas and paste (Ctrl+V or Cmd+V). Or save it as a `.json` file and use **Import from File** in the workflow menu. > **Tip:** Ask Claude to explain its plan before it builds. Correcting a plan costs one message. Correcting a finished workflow costs many. ## Step 4: Review every node Open the workflow in n8n and go through it from left to right: 1. Check each node does what you asked, with the right operation and fields. 2. Check every node that talks to an app has the right credential selected. HTTP Request nodes usually need you to pick the credential yourself. 3. Check expressions point to real fields. The expression preview shows the actual value, or an error when a field does not exist. 4. Check the trigger settings: schedule times, timezone, mailbox, form fields. 5. Look for anything Claude assumed. Ask it to list its assumptions if unsure. > **Warning:** Pasted JSON can contain node versions or settings that do not match your n8n version. If a node shows a warning, ask Claude to fix it, or rebuild that node by hand. ## Step 5: Test with pinned data Never test a new workflow against live customers. 1. Run the trigger once with realistic test data, or paste sample data into its output. 2. Pin the trigger output so every test reuses it. 3. Select **Execute workflow** and inspect each node's output. 4. Replace actions with side effects (sending emails, updating a CRM) with a test address or a test record while you iterate. Over MCP, you can also ask: "Test this workflow with realistic pinned data and tell me which nodes fail." Claude can generate sample data for the trigger and for nodes that call outside services, then run the logic in between. ## Step 6: Publish and watch 1. Click **Publish**, or ask Claude to publish it. 2. Watch the **Executions** tab for the first real runs. 3. Add an error workflow so failures reach you. See [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling). When you need changes later, ask Claude to update the existing workflow rather than build a new one. n8n keeps a version history, so you can always restore an earlier version. ## Next steps - [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp) - [Turn a business process into an agentic workflow](https://viralistic.nl/help/n8n/business-process-to-agentic-workflow) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) - [Brief Claude like a colleague](https://viralistic.nl/help/claude/write-better-prompts) --- # The AI Agent node explained > Understand how n8n's AI Agent node works, what its chat model, memory and tools do, and how to configure an agent that stays reliable. Source: https://viralistic.nl/help/n8n/ai-agent-node The AI Agent node puts a language model, such as Claude, inside your workflow and lets it decide which tools to use to finish a task. It is the heart of most AI automations in n8n. This article explains its parts, the settings that matter, and how to keep an agent predictable. ## Agent or regular nodes? A regular workflow follows fixed rules: if this, then that. An agent reads the situation and chooses its own steps. That is powerful for messy input, like free-text emails or customer questions, but it is slower, costs model usage and is less predictable. Use an agent only for the parts that need judgement. Keep everything else in regular nodes. [Turn a business process into an agentic workflow](https://viralistic.nl/help/n8n/business-process-to-agentic-workflow) explains how to draw that line. ## The parts of an agent The AI Agent node is a root node with connectors underneath for sub-nodes: | Connector | What it is | Required | | ---------- | ------------------------------------------------------------------------------------------ | ----------------- | | Chat Model | The language model that does the thinking, for example the Anthropic Chat Model for Claude | Yes | | Memory | Remembers earlier messages in a conversation | Only for chat | | Tools | Actions the agent may take: app nodes, HTTP requests, sub-workflows, MCP servers | Yes, at least one | ### Chat model Pick a model and a credential for it. For Claude, add the **Anthropic Chat Model** sub-node with an Anthropic API key. On n8n Cloud, some models can also run on n8n's own prepaid credits instead of your key. Faster, cheaper models are often good enough for sorting and extraction. Use stronger models for reasoning and writing. ### Memory Memory matters for chatbots that hold a conversation. **Simple Memory** is fine for testing. For production, use a memory backed by a database, such as Postgres or Redis, so conversations survive restarts. One-off tasks, like classifying a single email, need no memory. ### Tools Tools are where the agent gets its power. Common choices: - **App nodes as tools:** Gmail, Google Sheets, Slack and hundreds more. - **HTTP Request tool:** call any API. - **Call n8n Workflow Tool:** run one of your own workflows as a tool. Good for complex, tested logic. - **MCP Client Tool:** use tools from an external MCP server. See [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp). Give every tool a clear name and description. The agent chooses tools based on those descriptions, so "Look up a customer by email in HubSpot" works far better than "HubSpot1". > **Tip:** Inside a tool, you can let the model fill a field with `$fromAI()`, for example `{{ $fromAI('email', 'The customer email address') }}`. Fields you fill yourself stay fixed, which is safer. ## Key settings ### Prompt The prompt is the task for this run. With **Take from previous node automatically**, the agent expects a `chatInput` field, as a Chat Trigger provides. With **Define below**, you write the prompt yourself and pull in data with expressions: ```text Classify this email and draft a reply. From: {{ $json.from }} Subject: {{ $json.subject }} Body: {{ $json.text }} ``` ### System message Found under options. This is the agent's job description: role, rules, tone and limits. Be specific: ```text You are the intake assistant for Viralistic support. Only answer questions about website hosting and email. Never promise refunds or deadlines. If unsure, hand over to a human. Reply in the language of the customer. ``` ### Output format Turn on **Require Specific Output Format** and connect an output parser when the next node needs structured data, such as `category`, `priority` and `draftReply`. Structured output is much easier to route with an IF or Switch node than free text. ### Other options - **Max Iterations** limits how many steps the agent may take (10 by default). This stops runaway loops. - **Return Intermediate Steps** includes the agent's tool calls in the output. Useful for debugging and logging. ## Human review for risky tools You can require a person to approve specific tool calls before they run, for example sending an email or deleting a record. Open the tools connector on the agent and add a human review step with a channel such as Slack, Telegram or n8n Chat. The workflow pauses until someone approves or denies. > **Warning:** Do not give an agent tools it does not need. Every extra tool is something it can misuse. Start with read-only tools, and add write actions behind human review. ## Test your agent 1. Add a **Chat Trigger** while building and use the chat panel to talk to the agent. 2. Open the agent's output and logs to see which tools it called and why. 3. Try awkward input: empty messages, other languages, attempts to make it break its rules. ## Next steps - [Turn a business process into an agentic workflow](https://viralistic.nl/help/n8n/business-process-to-agentic-workflow) - [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Turn a business process into an agentic workflow > A step-by-step method to map a real business process, decide what AI should and should not do, and build a safe agentic workflow in n8n. Source: https://viralistic.nl/help/n8n/business-process-to-agentic-workflow Most AI automation projects fail for the same reason: they start with the tool instead of the process. This article gives you a method to go from "we spend hours on this every week" to a reliable workflow, where AI handles the judgement and plain automation handles the rest. It is for business owners and team leads. No coding needed for the thinking part. Marrallisa covered this method in the DataCamp webinar [How to turn a business process into an agentic workflow](https://www.datacamp.com/webinars/how-to-turn-a-business-process-into-an-agentic-workflow). ## Step 1: Pick the right process Good first candidates are: - **Frequent:** it happens daily or weekly. - **Bounded:** it has a clear start and a clear end result. - **Annoying but low risk:** a mistake is easy to spot and fix. Examples: sorting incoming requests, processing invoices, qualifying leads, preparing weekly reports. Avoid processes where one wrong action is costly, such as payments, until you have experience. ## Step 2: Map the process as it is today Sit down with the person who does the work and write every step down, in order. For each step, note: 1. What starts it. 2. What information they look at. 3. Which systems they use. 4. What they decide, and on what basis. 5. What the output is, and who receives it. 6. What goes wrong regularly. A numbered list or a simple flowchart is enough. Write down the exceptions too. They are where automations break. ## Step 3: Find the decision points Go through your map and mark each step as one of two types: | Type | Recognise it by | Build it with | | ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------- | | Rule-based | The same input always gives the same output. You can write the rule down. | Regular n8n nodes: IF, Switch, Edit Fields, app nodes | | Judgement | Reading free text, recognising intent, summarising, writing a draft | An AI Agent or LLM node | Here is a quote request process, mapped this way: | Step | Type | Built with | | ------------------------------------------ | --------------- | ------------------------- | | New email arrives in quotes@ | Rule | Email trigger | | Is it a quote request, a question or spam? | Judgement | AI classification | | Extract company, service and budget | Judgement | AI with structured output | | Is the company already a customer? | Rule | CRM lookup | | Draft a reply with the right package | Judgement | AI Agent | | Send the reply | Rule, high risk | Human approval, then send | | Log the request | Rule | Data Table or CRM | ## Step 4: Keep as much as possible deterministic Rule-based steps are fast, free and always behave the same way. Each judgement step adds cost, delay and uncertainty. So: 1. Use AI only where you marked judgement. 2. Give each AI step one clear job, with a structured output (fields, not prose). 3. Route on that output with normal nodes, such as a Switch on `category`. 4. Give an agent only the tools it needs for its job. See [The AI Agent node explained](https://viralistic.nl/help/n8n/ai-agent-node). > **Tip:** If you find yourself writing a very long system message full of rules, some of those rules probably belong in IF and Switch nodes instead. ## Step 5: Put a human in the loop Decide in advance where a person must check the work. Typical places: - Before anything leaves the company: emails to customers, published content. - Before anything is changed or deleted in a core system. - When the AI is unsure. Ask it for a confidence field and route low scores to a person. In n8n you can add human review to specific agent tools, or use a send-and-wait message in Slack, email or Telegram that pauses the workflow until someone approves. ## Step 6: Add guardrails 1. **Input and output checks:** the Guardrails node can catch jailbreak attempts, personal data and keywords before text reaches the model or leaves the workflow. 2. **Limits:** set Max Iterations on agents and a timeout on long workflows. 3. **Logging:** store each AI decision and its input in a Data Table, so you can review mistakes. 4. **Alerts:** add an error workflow. See [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling). ## Step 7: Roll out in stages 1. **Shadow mode:** the workflow runs alongside the person and only produces drafts. Compare results for a week or two. 2. **Assisted:** the person approves every action with one click. 3. **Automated:** remove approval for the cases that proved reliable. Keep it for the risky ones. Measure time saved and error rate at each stage. That tells you when to move on, and gives you the numbers to justify the next process. If you would like help mapping your first process, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [The AI Agent node explained](https://viralistic.nl/help/n8n/ai-agent-node) - [Build workflows with Claude](https://viralistic.nl/help/n8n/build-workflows-with-claude) - [Process incoming email with the IMAP trigger](https://viralistic.nl/help/n8n/imap-trigger) - [Store data with Data Tables](https://viralistic.nl/help/n8n/data-tables) --- # Process incoming email with the IMAP trigger > Start an n8n workflow for every new email in any IMAP mailbox, with the right credentials, read status and attachment settings. Source: https://viralistic.nl/help/n8n/imap-trigger Many processes start with an email: an invoice, an order, a request from a form. The **Email Trigger (IMAP)** node starts a workflow each time a new message arrives in a mailbox. It works with almost any email provider, including business mailboxes hosted by Viralistic. ## When to use it Use the IMAP trigger for any mailbox that supports IMAP. For Gmail you can also use the dedicated Gmail Trigger. > **Note:** IMAP no longer works for Outlook.com and Microsoft 365 mailboxes, because Microsoft switched off password-based access. Use the **Microsoft Outlook Trigger** node for those. > **Tip:** Use a dedicated mailbox or folder for automation, such as `invoices@yourcompany.com`. Then the workflow only sees mail meant for it, and nobody accidentally marks messages as read before n8n gets them. ## Step 1: Create the IMAP credential 1. Add an **Email Trigger (IMAP)** node to a new workflow. 2. In **Credential to connect with**, create a new credential. 3. Fill in the fields: | Field | Value | | ------------------------------ | ----------------------------------------------------- | | User | The full email address | | Password | The mailbox password, or an app password | | Host | Your provider's IMAP server, such as `imap.gmail.com` | | Port | `993` | | SSL/TLS | On | | Allow Self-Signed Certificates | Off, unless your administrator says otherwise | 4. Save. n8n tests the connection. For a Viralistic mailbox, use the server from your welcome email. The full settings are in [Log in to your email with IMAP](https://viralistic.nl/help/account/imap-email-login). ### App passwords Many providers block normal passwords for apps like n8n, especially when two-step verification is on. Gmail, for example, requires 2-step Verification and an app password. Create one in your account's security settings, give it a name like "n8n", and paste it as the password. Some providers revoke app passwords when you change your main password, so update the credential if the trigger suddenly fails to log in. ## Step 2: Configure the trigger | Setting | What it does | Recommended | | -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Mailbox Name | The folder to watch | `INBOX`, or a dedicated folder | | Action | What happens to the email after n8n reads it | **Mark as Read** | | Download Attachments | Fetches attachments as files | On only if you need them | | Format | How the email is returned | **Simple** for most uses. **Resolved** returns every part of the email, with attachments as files | **Mark as Read** is the safest choice. By default the node fetches unread messages, so marking them read prevents the same email from being processed twice. ### Filter which emails start the workflow Under **Options**, **Custom Email Rules** lets you narrow the search with IMAP search criteria, written as a JSON array. For example, only unread mail from one sender: ```json ["UNSEEN", ["FROM", "billing@supplier.com"]] ``` You can also filter later in the workflow with an IF node, which is easier to read and test. **Force Reconnect Every Minutes** is useful if your mail server drops long connections. Set it to something like 30 if the trigger stops picking up mail after a while. ## Step 3: Test with a real email 1. Select **Execute step** on the trigger node. 2. Send an email to the mailbox, ideally with an attachment if you need those. 3. Wait for the node to show the message. Check the fields: sender, subject, text, HTML and date. 4. Pin the output so you can build the rest of the workflow without sending more emails. ## Working with attachments With **Download Attachments** on, each attachment arrives as binary data on the item, usually named `attachment_0`, `attachment_1` and so on. You can pass these straight to nodes that accept files, such as Google Drive (upload), Extract from File (read a PDF or spreadsheet), or an AI node that reads documents. > **Warning:** Downloading attachments uses memory, especially with large files or busy mailboxes. Only turn it on when the workflow needs the files, and filter out emails you do not need early. ## Step 4: Publish Click **Publish**. From now on, n8n stays connected to the mailbox and starts the workflow for each new email. Check the **Executions** tab after the first real emails arrive. ## Example: invoice intake ```text Email Trigger (IMAP) → IF has attachment → Google Drive upload → Data Table log ``` 1. Trigger on `invoices@yourcompany.com` with Mark as Read and attachments on. 2. Keep only emails with a PDF attachment. 3. Upload the PDF to a Drive folder. 4. Log sender, subject, date and file link in a data table. Add an AI step later to read the invoice amount and due date. ## Troubleshooting - **Authentication failed:** check the username is the full address, and use an app password. - **Connection timed out:** check host and port. On self-hosted n8n, make sure your server can reach port 993 outbound. - **Nothing triggers:** confirm the workflow is published, the folder name is right, and messages are still unread. - More email issues: [Fix common email problems](https://viralistic.nl/help/account/email-troubleshooting). ## Next steps - [Log in to your email with IMAP](https://viralistic.nl/help/account/imap-email-login) - [Turn a business process into an agentic workflow](https://viralistic.nl/help/n8n/business-process-to-agentic-workflow) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Receive data with webhooks > Use the Webhook node to start n8n workflows from websites, forms and other apps, test safely, secure the URL and send a response back. Source: https://viralistic.nl/help/n8n/webhooks A webhook is a URL that another system calls when something happens: a form is submitted, a payment succeeds, a deal changes stage. The Webhook node gives your workflow such a URL. It is the most flexible trigger in n8n, because almost every app and website can send data to a URL. ## How it works 1. You add a Webhook node and n8n generates a URL. 2. You paste that URL into the other app, often in a section called Webhooks or Integrations. 3. The app sends an HTTP request with data (usually JSON) whenever the event happens. 4. n8n starts the workflow with that data as the first item. ## Test URL and production URL Every Webhook node has two URLs. You switch between them at the top of the node. | | Test URL | Production URL | | -------------------- | ----------------------------------------------------------- | ---------------------------- | | Path contains | `/webhook-test/` | `/webhook/` | | Works when | You select **Listen for test event**, for about two minutes | The workflow is published | | Data shown on canvas | Yes | No, check the Executions tab | | Use for | Building and debugging | The real integration | > **Warning:** The most common webhook problem is a live app still pointing at the test URL. When you go live, copy the production URL into the other app. ## Step 1: Add and configure the node 1. Create a workflow and add the **Webhook** node as the trigger. 2. Set **HTTP Method** to what the sender uses. Most apps send `POST`. 3. Change **Path** to something readable, such as `new-lead`. The default is a random string, which is fine too. 4. Choose how to **Respond** (see below). ## Step 2: Send a test request 1. Select **Listen for test event**. 2. Trigger the event in the other app, or send a request yourself: ```bash curl -X POST "https://your-n8n-domain/webhook-test/new-lead" \ -H "Content-Type: application/json" \ -d '{"name": "Jane", "email": "jane@example.com", "source": "website"}' ``` 3. The node shows the received data. You find the JSON body under `body`, and also `headers` and `query`. 4. Pin the output and build the rest of the workflow. ## Step 3: Choose a response The sender usually waits for an answer. Under **Respond** you choose: - **Immediately:** n8n answers right away that the workflow started. Best for most integrations, because senders often time out after a few seconds. - **When Last Node Finishes:** n8n answers with the output of the last node. Useful for simple APIs. - **Using 'Respond to Webhook' Node:** you decide exactly what to send back, and when, with a separate node. Good for redirects after a form, or custom status codes. - **Streaming:** sends the answer piece by piece, for example from an AI Agent. ## Step 4: Secure the webhook Anyone who knows the URL can call it. Protect it: 1. Set **Authentication** to **Header Auth** and choose a long random secret. Configure the sender to include that header. Basic Auth and JWT are also available. 2. Use **IP(s) Allowlist** under options if the sender has fixed IP addresses. 3. Turn on **Ignore Bots** for URLs that might get shared, so link previews do not trigger runs. 4. Validate the data early in the workflow. Stop when required fields are missing. > **Note:** Some apps sign their webhooks instead of sending a fixed header. Check the app's documentation. You can verify a signature with a Code node or the Crypto node. ## Step 5: Publish and connect 1. Click **Publish**. 2. Copy the **Production URL** into the other app. 3. Trigger one real event and check the **Executions** tab. ## Webhooks from your website Static sites, such as our Astro sites, can post form submissions straight to an n8n webhook. Then n8n can store the lead, notify you and send a confirmation email. See [Add forms to a static site](https://viralistic.nl/help/astro/forms). For a simple form without a website, the **n8n Form Trigger** is easier: it hosts the form for you. See [Build your first workflow](https://viralistic.nl/help/n8n/first-workflow). ## Self-hosted tips - The URL must be reachable from the internet. A workflow on `localhost` cannot receive webhooks from online apps. - Behind a reverse proxy, set the `WEBHOOK_URL` environment variable to your public address. Otherwise n8n shows the wrong URL in the node. - The maximum payload is 16 MB by default. Self-hosted instances can change this. ## Next steps - [Run workflows on a schedule](https://viralistic.nl/help/n8n/schedules) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) - [Add forms to a static site](https://viralistic.nl/help/astro/forms) --- # Run workflows on a schedule > Use the Schedule Trigger to run n8n workflows every few minutes, daily or weekly, with the right timezone and without surprises. Source: https://viralistic.nl/help/n8n/schedules Reports, reminders, syncs and clean-up jobs all run on a timer. In n8n you do this with the **Schedule Trigger** node. This article shows how to set it up, how to use cron for unusual schedules, and how to avoid the classic timezone mistake. ## Set up a schedule 1. Create a workflow and add **Schedule Trigger** as the first step. 2. Under **Trigger Rules**, choose a **Trigger Interval**: seconds, minutes, hours, days, weeks, months or custom (cron). 3. Fill in the details for that interval. 4. Build the rest of the workflow and test it with **Execute workflow**. A manual run starts immediately, whatever the schedule says. 5. Click **Publish**. The schedule only runs once the workflow is published. ### Common examples | You want | Interval | Settings | | -------------------------- | -------- | ---------------------------------------------------------------- | | Every 15 minutes | Minutes | Minutes Between Triggers: 15 | | Every day at 7:30 | Days | Days Between Triggers: 1, Hour: 7am, Minute: 30 | | Every Monday at 9:00 | Weeks | Weeks Between Triggers: 1, Weekday: Monday, Hour: 9am, Minute: 0 | | First of the month at 8:00 | Months | Day of Month: 1, Hour: 8am, Minute: 0 | You can add several trigger rules to one node, for example Monday at 9:00 and Thursday at 14:00. ## Custom schedules with cron For anything the standard intervals cannot express, choose **Custom (Cron)** and enter an expression. The five fields are minute, hour, day of month, month and day of week: ```text 0 9 * * 1-5 Weekdays at 9:00 */30 8-18 * * 1-5 Every 30 minutes during office hours on weekdays 0 0 1 1,4,7,10 * Midnight on the first day of each quarter ``` n8n also accepts an optional sixth field at the start for seconds. If you do not write cron every day, use a helper such as [crontab.guru](https://crontab.guru) to check your expression. ## Get the timezone right A schedule that runs an hour early or late is almost always a timezone issue. - **n8n Cloud:** set the instance timezone in your Cloud dashboard under Manage. - **Self-hosted:** set the `GENERIC_TIMEZONE` environment variable, for example `Europe/Amsterdam`. - **One workflow:** open the workflow menu (the three dots), choose **Settings** and change **Timezone**. With a proper timezone such as `Europe/Amsterdam`, daylight saving time is handled for you. ## Things to know - **Missed runs:** if n8n is offline when a run is due, that run is skipped by default. Recent versions add a setting for missed executions in the node's settings. Do not rely on a schedule for anything that must never be missed. Add a check, such as comparing with a "last run" date stored in a data table. - **Overlapping runs:** if a run takes longer than the interval, the next one starts anyway. Keep heavy jobs on longer intervals, or process data in batches. - **Busy minutes:** many workflows on the exact hour all start at once. Spread them out, for example 7:05, 7:10 and 7:15. - **Quotas:** on paid Cloud plans, every scheduled run counts as an execution. A workflow every minute adds up to over 40,000 runs a month. Check whether you really need that frequency. > **Tip:** For "only when something changed" jobs, a frequent schedule plus a check against stored data works well. Save what you already processed in a data table and skip it next time. See [Store data with Data Tables](https://viralistic.nl/help/n8n/data-tables). ## Example: weekly summary ```text Schedule Trigger (Monday 8:45) → Google Sheets (read last week) → Summarise → Slack message ``` 1. Trigger every Monday at 8:45. 2. Read last week's rows from a sheet or your CRM. 3. Summarise them, with a Summarize node or an AI step. 4. Post the summary to your team channel before the Monday meeting. ## Next steps - [Receive data with webhooks](https://viralistic.nl/help/n8n/webhooks) - [Store data with Data Tables](https://viralistic.nl/help/n8n/data-tables) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Error handling and alerts > Make n8n workflows recover from small failures by themselves and alert you about the rest, with retries, error outputs and an error workflow. Source: https://viralistic.nl/help/n8n/error-handling Every workflow fails sometimes: an API is down, a password changes, someone sends unexpected data. The goal is not zero errors. The goal is that small hiccups fix themselves and real problems reach you quickly, before a customer notices. This article sets that up in three layers. ## Layer 1: Retry on the node Many errors are temporary, such as a timeout or a rate limit. Let n8n try again. 1. Open the node that calls an outside service. 2. Go to its **Settings** tab. 3. Turn on **Retry On Fail**. 4. Set **Max Tries** (for example 3) and **Wait Between Tries** (for example 5000 ms). Use this on nodes that read data or call APIs. Be careful with nodes that create things, like sending an email or creating an invoice: a retry after a partial success can create duplicates. ## Layer 2: Decide what happens on an error In the same **Settings** tab, **On Error** controls what the node does when it still fails: | Option | What happens | Use when | | ----------------------------- | ---------------------------------------------------- | ------------------------------------------------------ | | Stop Workflow | The run stops and is marked as failed | The default. The rest makes no sense without this step | | Continue | The workflow continues with the last valid data | The step is optional | | Continue (using error output) | The node gets a second, error output you can connect | You want to handle the failure yourself | The error output is the most useful. For example, when one row in a batch of 100 fails, route that row to a "needs attention" data table and let the other 99 continue. ## Layer 3: An error workflow for alerts An error workflow runs automatically whenever a production run of another workflow fails. You build it once and attach it to all your workflows. ### Build the error workflow 1. Create a new workflow called `Error alerts`. 2. Add the **Error Trigger** node as the first step. 3. Add a node that notifies you, such as Slack, Gmail or Telegram. 4. Write a message with expressions from the error data: ```text Workflow failed: {{ $json.workflow.name }} Node: {{ $json.execution.lastNodeExecuted }} Error: {{ $json.execution.error.message }} Open: {{ $json.execution.url }} ``` You do not need to publish this workflow. The Error Trigger works without publishing. ### Attach it to your workflows 1. Open a workflow you want to monitor. 2. Open the workflow menu (the three dots) and choose **Settings**. 3. Under **Error workflow**, choose `Error alerts`. 4. Save. Repeat this for every production workflow. Make it part of your checklist before you publish. > **Note:** The error workflow only fires for automatic, production runs. Clicking Execute workflow in the editor will not trigger it. To test, publish a small workflow that fails on purpose, for example a Schedule Trigger followed by a **Stop and Error** node. ## Fail on purpose with Stop and Error Not every problem throws an error. An empty search result or a missing email address can be just as bad. Use an IF node to detect the situation, then a **Stop and Error** node with a clear message, such as "No invoice number found". The run is marked as failed and your error workflow sends the alert. ## Find and retry failed runs 1. Open the **Executions** tab of a workflow, or the overview of all executions. 2. Filter on failed runs. 3. Open one to see exactly which node failed and with what data. 4. Fix the cause, then retry the execution. You can retry with the current workflow or with the original version. > **Tip:** On a failed execution, select **Debug in editor** to load its data into the workflow and fix the problem with the exact same input. This is available on n8n Cloud and on registered or paid self-hosted editions. ## A simple alert policy - **Critical workflows** (orders, customer email): alert immediately, to a channel someone watches. - **Background jobs** (reports, syncs): a daily digest is often enough. Log errors to a data table and send one summary each morning. - **Avoid alert fatigue:** if an alert fires every day and nobody acts, fix the cause or remove the alert. ## Next steps - [Store data with Data Tables](https://viralistic.nl/help/n8n/data-tables) - [Update and back up a self-hosted n8n](https://viralistic.nl/help/n8n/self-hosting-maintenance) - [The AI Agent node explained](https://viralistic.nl/help/n8n/ai-agent-node) --- # Update and back up a self-hosted n8n > Back up everything a self-hosted n8n needs to recover, including the encryption key, and update n8n safely with Docker. Source: https://viralistic.nl/help/n8n/self-hosting-maintenance Running n8n yourself means you own two jobs that n8n Cloud does for you: backups and updates. Both are simple once you have a routine. This article is for whoever looks after a self-hosted instance running in Docker. If that is nobody yet, decide who it is before you put important workflows on it. ## What a complete backup contains | Part | Where it lives | Why it matters | | ------------------- | -------------------------------------------------- | ----------------------------------------------------------------- | | The `.n8n` folder | The Docker volume mounted at `/home/node/.n8n` | Holds the encryption key, and with SQLite also the whole database | | PostgreSQL database | Your database server, if you use one | Workflows, credentials, users, executions | | Configuration | Your `compose.yml`, `.env` or `docker run` command | Database settings, `WEBHOOK_URL`, custom encryption key | | Custom nodes | Folders you configured for custom nodes | Workflows that use them break without them | > **Warning:** Credentials are encrypted with the key in the `.n8n` folder (or in `N8N_ENCRYPTION_KEY`). A database backup without that key is useless for credentials. Store the key safely, separate from the server. ## Back up the Docker volume With the default SQLite database, stop n8n first, so the database file is not copied halfway through a write. 1. Find your volume name: ```bash docker volume ls ``` 2. Stop n8n, archive the volume, and start n8n again: ```bash docker stop n8n docker run --rm -v n8n_data:/data -v "$PWD":/backup alpine \ tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data . docker start n8n ``` With Docker Compose, use `docker compose stop` and `docker compose start` instead, and your own volume name. 3. If you use PostgreSQL, also make a dump with `pg_dump` using your database's own backup tooling. 4. Copy the backup files off the server, for example to object storage. ## Export workflows and credentials as files For an extra, readable copy, export workflows and credentials with the n8n command line. This example writes into the volume, so the files survive container restarts: ```bash docker exec -u node n8n n8n export:workflow --backup --output=/home/node/.n8n/backups/workflows/ docker exec -u node n8n n8n export:credentials --backup --output=/home/node/.n8n/backups/credentials/ ``` These exports are handy to move workflows to another instance. They do not include users, execution history, variables or settings, so they do not replace the full backup above. ## Test your restore A backup you never restored is a hope, not a backup. Once per quarter: 1. Start a fresh n8n container on a test machine. 2. Restore the volume archive (and database dump) into it. 3. Open n8n, check that workflows are there and that a credential still connects. ## Update n8n safely ### Before you update 1. Read the release notes for every version between yours and the target, on the [n8n releases page](https://github.com/n8n-io/n8n/releases). Pay attention to breaking changes in major versions. 2. Make a full backup. 3. Pick a quiet moment. Workflows do not run while n8n restarts. > **Note:** n8n 3.0 requires Docker for self-hosted installs and no longer supports running n8n with npm. Before a major upgrade, read n8n's breaking changes page for that version and check the migration report in your instance settings. ### Pin a version Use a specific version tag instead of `latest`, such as `n8nio/n8n:`. Then you decide when to upgrade, and you know exactly which version to go back to. ### Update with Docker Compose 1. Change the version in your `compose.yml` or `.env`. 2. Pull and restart: ```bash docker compose pull docker compose up -d ``` If you used the one-line installer, rerun it with the upgrade flag: `curl -fsSL https://get.n8n.io | sh -s -- --upgrade`. ### Update a plain docker run setup 1. Pull the new image: `docker pull n8nio/n8n:`. 2. Stop and remove the old container: `docker stop n8n` and `docker rm n8n`. Your data stays in the volume. 3. Start it again with your usual `docker run` command and the new tag. ### After the update 1. Log in and confirm the new version number. 2. Open the Executions overview and watch the next scheduled and webhook runs. 3. Check that triggers are still active, especially email and app triggers. If something is badly wrong, go back to the previous image tag and restore your backup. Updates can migrate the database, so going back to an older version usually means restoring the backup as well. ## A maintenance routine | How often | Task | | --------- | ---------------------------------------------------------------- | | Daily | Automatic backup of volume and database, copied off the server | | Monthly | Update to the latest stable version, after reading release notes | | Quarterly | Test a restore, review users and unused credentials | If you would rather have us host and maintain your instance, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [Get n8n: cloud or self-hosted](https://viralistic.nl/help/n8n/get-n8n) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) - [Connect your apps with credentials](https://viralistic.nl/help/n8n/credentials) --- # Store data with Data Tables > Use n8n Data Tables to keep lists, logs and lookup values inside n8n, and to stop workflows from processing the same item twice. Source: https://viralistic.nl/help/n8n/data-tables Workflows often need to remember something: which emails they already handled, a list of customers, a set of prompts, or a log of AI decisions. Data Tables give you simple tables inside n8n for exactly that, without setting up a spreadsheet or database. This article shows when to use them and the patterns that come up most. ## When to use Data Tables Good uses: - **Remember what you processed**, so a workflow never handles the same item twice. - **Lookup lists**, such as product codes, team members or routing rules. - **Logs**, such as every AI classification with its input, for later review. - **Shared settings or prompt texts** that several workflows read. - **Small datasets** collected by forms or webhooks. Use something else when people outside n8n need to edit the data every day (a spreadsheet or CRM is friendlier), or when you store large volumes (use a real database). > **Note:** Data Tables are for light to moderate storage. By default, all data tables in an instance share a total limit of 200 MiB. n8n warns you as you approach it, and writes fail once you reach it. Self-hosted instances can raise the limit. ## Create a table 1. Open your project overview and go to the **Data tables** tab. 2. Create a data table and give it a clear name, such as `Processed emails`. 3. Start **from scratch**, or **import a CSV** to create the columns and rows in one go. 4. Add columns. Each column has a type: String, Number, Boolean or Date. You can add, edit and delete rows by hand in this view, and download the table as CSV from its menu. ## Use a table in a workflow Add the **Data Table** node. With the resource set to **Row**, the main operations are: | Operation | What it does | | --------------------- | --------------------------------------------------------- | | Insert | Adds a new row | | Get | Finds rows that match your conditions | | Update | Changes rows that match your conditions | | Upsert | Updates a matching row, or inserts one if none exists | | Delete | Removes matching rows | | If Row Exists | Passes on only the items that already have a matching row | | If Row Does Not Exist | Passes on only the items that have no matching row yet | When you insert, you can **Map Automatically** if your field names match the column names exactly, or **Map Each Column Manually**. ## Pattern: never process the same item twice This is the most common use. Say a schedule checks an inbox or API every 10 minutes and may see the same message again. ```text Trigger → Data Table: If Row Does Not Exist → Process → Data Table: Insert ``` 1. Create a table `Processed items` with a String column `itemId` and a Date column `processedAt`. 2. After the trigger, add a Data Table node with **If Row Does Not Exist**. Match the column `itemId` against the ID of the incoming item, such as an email message ID or order number. 3. Do the real work on the items that pass. 4. At the end, **Insert** a row with the `itemId` and `processedAt` set to `{{ $now.toISO() }}`. Put the insert at the very end. If the processing fails halfway, the item is not marked as done and will be tried again next time. ## Pattern: lookup table Keep routing rules out of your workflow logic. For example, a table `Routing` with columns `category` and `slackChannel`. After an AI step classifies a request, a **Get** on `category` returns the right channel. To change the routing, you edit a row instead of the workflow. ## Pattern: AI decision log Insert one row per AI decision with the input, the output and a timestamp. Review it weekly. It shows where the model gets things wrong and gives you real examples to improve your prompt. ## Good to know - Data tables belong to a project. Everyone in that project can use them. - You cannot read data tables directly from a Code node. Use the Data Table node. - Claude can create data tables and add rows through the n8n MCP server. See [Use the n8n MCP server](https://viralistic.nl/help/n8n/n8n-mcp). - Self-hosted backups include data tables, because they live in the n8n database. See [Update and back up a self-hosted n8n](https://viralistic.nl/help/n8n/self-hosting-maintenance). > **Tip:** Add a Date column to every table you write to from a workflow. It makes debugging and clean-up much easier later. ## Next steps - [Build your first workflow](https://viralistic.nl/help/n8n/first-workflow) - [Run workflows on a schedule](https://viralistic.nl/help/n8n/schedules) - [Error handling and alerts](https://viralistic.nl/help/n8n/error-handling) --- # Make an Astro site > Create a new Astro project with pnpm, give it the Viralistic structure, and run the dev server, checks and build on your own machine. Source: https://viralistic.nl/help/astro/make-an-astro-site This guide is for developers, or anyone working alongside Claude Code, who wants to start a new website the way Viralistic builds them. You go from an empty folder to an Astro project where every page is a markdown file, schemas are strict and one route renders everything. You also learn the four commands you will use every day. ## What you need - **Node.js**, an even-numbered LTS release. Viralistic projects pin the exact version in a `.nvmrc` file (currently Node 24). - **pnpm**, the package manager we use for every project. Install it with the instructions on pnpm.io. - **Git** and a GitHub account, so the site can be deployed later. - **A code editor**, for example VS Code with the official Astro extension. ## Create the project 1. Open a terminal in the folder where you keep your projects. 2. Run the Astro setup wizard: ```bash pnpm create astro@latest ``` 3. Give the project a folder name. 4. Choose the smallest starter the wizard offers (minimal or empty). You will replace most of it. 5. Say yes to installing dependencies and to creating a git repository. 6. Move into the new folder with `cd your-folder-name`. > **Tip:** The wizard's questions change between Astro versions. If an option looks different from this guide, pick the option that gives you the least starter code. ## Add the Viralistic structure A fresh Astro project has a `src/pages/index.astro` file with markup inside it. Viralistic sites never put content in routes. Instead, content lives in `src/content`, and a `type` field in each page decides which layout renders it. The fastest way to get there is to copy the foundation files from an existing Viralistic project. Here is what they add and why. ### One content route Delete `src/pages/index.astro` and create `src/pages/[...page].astro`. This is the only route on the site. It turns every file in the `pages` collection into a URL: ```astro --- import { getCollection } from "astro:content" import LayoutRenderer from "@/components/layout-renderer.astro" export async function getStaticPaths() { const pages = await getCollection("pages") return pages.map((page) => ({ params: { page: page.id === "index" ? undefined : page.id }, props: page, })) } --- ``` ### Collections and schemas `src/content.config.ts` defines two collections: `pages` (markdown files) and `globals` (one YAML file per language with the site name, navigation, call to action and footer). Each collection is validated by a schema in `src/schemas/`: - `layouts/base.ts` holds the fields every page has: `title`, `description`, an optional `image` and an optional `seo` block. - `layouts/.ts` holds one schema per page type, always ending in `.strict()` so unknown fields fail the build. - `page.ts` combines them into one union keyed on `type`. ### Layouts, blocks and UI `src/components/layout-renderer.astro` reads the page's `type` and loads `src/layouts/.astro`. Layouts only pick blocks (`src/components/blocks/hero-1.astro`, `features-1.astro` and so on) and pass data to them. Small building blocks such as buttons come from the Fulldev UI registry: ```bash pnpm dlx shadcn@latest add @fulldev/button ``` ### Your first content Create a globals file named after the default locale in `astro.config.ts` (Viralistic's own site uses `src/content/globals/nl.yaml`), and a home page at `src/content/pages/index.md`: ```md --- type: home title: We build calm, fast websites description: A short description for search engines and social previews. eyebrow: Welcome buttons: - label: Get in touch href: /contact --- Body text in markdown goes here. ``` Every field must match the `home` schema. Add a field to the schema first, then to the page. Site URL, name, favicon and languages go into `fulldevIntegration()` in `astro.config.ts`. That one integration also wires Tailwind, the sitemap, `robots.txt` and favicons, so you do not configure them anywhere else. ## Run the site Add these scripts to `package.json` if they are not there yet: ```json { "scripts": { "dev": "astro dev --host 127.0.0.1", "build": "astro build", "preview": "astro preview", "typecheck": "astro check", "check": "pnpm format:check && pnpm typecheck", "format:write": "prettier --write .", "format:check": "prettier --check ." } } ``` Then use them: | Command | What it does | | -------------- | ------------------------------------------------------------------------- | | `pnpm dev` | Starts a local server at `http://127.0.0.1:4321` that reloads as you edit | | `pnpm check` | Checks formatting with Prettier and types with `astro check` | | `pnpm build` | Builds the static site into the `dist` folder | | `pnpm preview` | Serves the `dist` folder locally, exactly as it will go live | > **Note:** If `pnpm build` fails with a message about an unexpected key, that is the strict schema doing its job. A page has a field its layout does not know. Fix the field or add it to the schema. ## Commit your work 1. Run `pnpm format:write` so the code follows the shared Prettier settings. 2. Run `pnpm check` and `pnpm build`. Both must pass. 3. Commit with a conventional prefix, for example `chore: initialize Astro project foundation`. 4. Create an empty repository on GitHub and push to it. ## Next steps - [How a Viralistic Astro site is organised](https://viralistic.nl/help/astro/project-structure) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) - [Deploy to Netlify](https://viralistic.nl/help/astro/deploy-to-netlify) --- # How a Viralistic Astro site is organised > Understand where content, layouts, sections and styling live in a Viralistic Astro site, so you know which file to open for any change. Source: https://viralistic.nl/help/astro/project-structure Every website Viralistic builds in Astro follows the same structure. Once you know it, you can find your way around any of our sites in minutes. This article explains the folders, the few rules that hold them together, and which file to open for the most common changes. No coding knowledge needed. ## The big idea Content, structure and styling are kept strictly apart: - **Content** (text, images, links) lives in markdown and YAML files in `src/content`. - **Schemas** in `src/schemas` describe exactly which fields each kind of page may have. - **Layouts** in `src/layouts` decide which sections a kind of page shows. - **Blocks and UI components** in `src/components` draw those sections on screen. Because of this split, you can rewrite every sentence on a page without touching code, and a developer can redesign a section without touching your text. ## The folders ```text astro.config.ts site URL, name, favicon, languages, fonts netlify.toml build settings and redirects src/ assets/ images that Astro optimises content/ globals/nl.yaml site name, navigation, call to action, footer pages/ one markdown file per URL schemas/ the allowed fields per page type layouts/ one layout per page type components/ blocks/ page sections: hero-1, features-1, footer-2 ui/ small building blocks: button, card, accordion pages/[...page].astro the single route that renders every page styles/global.css colours, fonts and spacing as design tokens public/ files that need a fixed URL, such as PDFs ``` ## How a file becomes a page 1. You create a markdown file in `src/content/pages`. Its path is its URL: `pages/webdesign/hosting.md` becomes `/webdesign/hosting`, and `pages/index.md` becomes the home page. 2. The first line of its frontmatter is `type`, for example `type: service`. 3. The single route reads every file and hands it to the layout renderer. 4. The renderer loads `src/layouts/service.astro`, the layout that matches the `type`. 5. The layout passes the frontmatter fields to its blocks, and puts the markdown body where the long text belongs. 6. The base layout wraps it all with the header, footer, SEO tags and structured data. > **Tip:** A file whose name starts with an underscore, such as `_draft.md`, is skipped by the build. Use this to keep a draft page in the project without publishing it. ## The rules that keep it tidy - **One route.** There is only one file in `src/pages`. New pages are new markdown files, never new route files. - **Strict schemas.** If a page contains a field its schema does not know, the build stops with an error. This catches typos before they reach your visitors. - **Global data in one place.** Navigation, footer links, company details and the main call to action live in `src/content/globals/nl.yaml`. Components never hard-code them. - **Tokens for styling.** Colours, radius and fonts are variables in `src/styles/global.css`. A rebrand changes the tokens, not hundreds of components. - **Numbered blocks.** A different design for a section becomes a new block (`hero-2`) instead of a switch inside an existing one. ## Where to change what | You want to change | Open this | | --------------------------- | -------------------------------------------------------------------- | | Text on a page | The page's file in `src/content/pages` | | Menu, footer or main button | `src/content/globals/nl.yaml` | | Page title in Google | `title`, `description` or the `seo` block in the page's frontmatter | | An image | Add it to `src/assets` and point the page's frontmatter at it | | A downloadable PDF | `public/downloads` | | Brand colours or font | `src/styles/global.css` and the `fonts` setting in `astro.config.ts` | | A redirect from an old URL | `netlify.toml` | | A new kind of page | Schema, layout, registration and a content file (a developer task) | ## Adding a new page type Most changes are content changes. When a site needs a genuinely new kind of page, such as a job vacancy, a developer always does four things together: 1. Writes a schema in `src/schemas/layouts/` with the fields the page needs. 2. Registers it in `src/schemas/page.ts` under its `type` name. 3. Builds a layout in `src/layouts/` that composes existing or new blocks. 4. Adds the first markdown file with that `type`. After that, every new vacancy is just another markdown file. ## Next steps - [Edit text and pages](https://viralistic.nl/help/astro/edit-content) - [Images and media](https://viralistic.nl/help/astro/images-and-media) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) --- # Edit text and pages > Change text, add pages and update the menu of your Viralistic Astro site safely, with a preview before anything goes live. Source: https://viralistic.nl/help/astro/edit-content This article is for site owners and editors who want to change their own website without waiting for a developer. On a Viralistic Astro site, all text lives in plain files, so editing a page means editing a file. You will learn how a page file is built, how to edit it in the browser on GitHub, and how to check your change before it goes live. ## How a page file is built Every page is a markdown file in `src/content/pages`. It has two parts: ```md --- type: page title: Privacy policy description: How we handle personal data and the rights you have. eyebrow: Privacy intro: We keep personal data to the minimum needed to run this website. seo: title: "Privacy policy | Your Company" description: "How we handle personal data and your rights under the GDPR." --- ## Who is responsible Your Company, Example Street 1, Amsterdam, is responsible for the data on this page. ``` - **Frontmatter** is everything between the two `---` lines. It holds structured data in YAML: the page type, title, description, buttons, images. The layout decides where each field appears. - **Body** is everything below. It is long-form text in markdown: headings, paragraphs, lists and links. The fields you may use depend on the `type`. Copy an existing page of the same type when in doubt. ## Edit a page on GitHub You do not need to install anything for small text changes. 1. Open the website's repository on GitHub and go to `src/content/pages`. 2. Open the file for the page you want to change. The file path matches the URL: `/webdesign/hosting` lives in `webdesign/hosting.md`. 3. Click the pencil icon to edit the file. 4. Make your change. 5. Click the button to commit your changes, and choose to create a new branch and start a pull request. 6. Open the pull request. After a minute or two, Netlify adds a link to a deploy preview. 7. Open the preview and check the page. 8. When it looks right, merge the pull request. The live site updates automatically. > **Tip:** Working through a pull request means nothing reaches your visitors until you have seen the preview. If the build fails, the live site stays as it was. ## YAML rules that prevent errors Most failed builds after a content edit come from one of these: - **Indentation uses spaces, never tabs.** Nested fields (such as `title` under `seo`) are indented two spaces. - **Quote text that contains a colon.** `title: "SilverDrive: a premium chauffeur brand"` works. Without quotes, YAML gets confused. - **List items start with a dash and a space.** Each button or feature is one `- ` item with its fields indented below it. - **Do not invent fields.** The schemas are strict, so an unknown field (or a typo such as `tilte`) stops the build with an error naming the file and the field. - **Do not remove required fields.** Every page needs at least `type`, `title` and `description`. ## Write the body text The body uses ordinary markdown: ```md ## A section heading A paragraph of text with a [link to the contact page](https://viralistic.nl/contact) and **bold words**. - A list item - Another list item ``` Start sections with `##`. The page title is already shown at the top of the page, so do not add a `#` heading yourself. ## Change the menu and footer The navigation, the main call to action and the footer links are shared by every page. They live in one file: `src/content/globals/nl.yaml`. ```yaml navigation: - label: About href: /about - label: Contact href: /contact cta: label: Strategic call href: https://calendly.com/marrallisa/30min ``` Add, remove or reorder items here, and every page updates. ## Add a new page 1. Find an existing page that looks like the one you want, for example another service page. 2. Copy its file and give the copy a new name. The name becomes the URL, so use lowercase words separated by hyphens: `brand-photography.md`. 3. Change the `title`, `description` and the rest of the content. 4. Link to the new page from the menu or from another page, so visitors and search engines can find it. 5. Commit through a pull request and check the deploy preview. > **Note:** Renaming or deleting a page changes or removes its URL. Add a redirect from the old address so you keep its visitors and rankings. See [Keep your rankings when you relaunch](https://viralistic.nl/help/astro/redirects). ## Next steps - [Images and media](https://viralistic.nl/help/astro/images-and-media) - [Edit your site with Claude Code](https://viralistic.nl/help/astro/edit-your-site-with-claude-code) - [Make your Astro site rank well](https://viralistic.nl/help/astro/astro-seo) --- # Edit your site with Claude Code > Use Claude Code to add pages, sections and fixes to your Viralistic Astro site, check the result and publish it through a pull request. Source: https://viralistic.nl/help/astro/edit-your-site-with-claude-code Claude Code can read your whole website project, make changes across several files and check that the site still builds. This article is for site owners and marketers who want to make bigger changes than a text edit, such as a new page type or a new section, without writing the code themselves. You will learn how to set Claude up in your project, how to ask for changes and how to check them before they go live. ## Before you start You need: - Claude Code installed and signed in. See [Install Claude Code](https://viralistic.nl/help/claude/install-claude-code). - A copy of your website's repository on your computer, with `pnpm install` run once. Or use [Claude Code in the cloud](https://viralistic.nl/help/claude/claude-code-on-the-web), which works on the repository directly. - Permission to push branches to the repository on GitHub. ## Why Claude already knows the structure Viralistic projects include a skill at `.claude/skills/astro-site-architecture/SKILL.md`. It describes how every Viralistic site is built: content in `src/content`, strict schemas, a `type` per page that picks the layout, one route, blocks for sections and tokens for styling. Claude Code loads it automatically when you work on the site, so it follows the same rules a Viralistic developer would. For facts about your own business (tone of voice, which pages matter most, what never to change), add a `CLAUDE.md` file to the project root. See [Write a CLAUDE.md](https://viralistic.nl/help/claude/write-a-claude-md). ## Start a session 1. Open a terminal in your project folder. 2. Start Claude Code: ```bash claude ``` 3. Ask Claude to create a new branch for your change, so your work stays separate from the live site. ## Ask for a change Describe the outcome you want, where it belongs and what it should look like. A few examples that work well: ```text Add a new service page for brand photography at /photography/brand-photography. Use the same page type and tone as the other photography pages. ``` ```text The about page needs a section with three team members: name, role, photo. Add it the Viralistic way: schema field, content in the markdown file, a block, wired in the layout. ``` ```text Change the primary brand colour to #2f6f5e everywhere. Only change the tokens. ``` For larger changes, ask Claude to propose a plan first and approve it before any files change. Claude Code also has a dedicated plan mode for this. > **Tip:** Mention files and folders by their path when you know them, for example `src/content/pages/about.md`. Claude finds things faster and makes fewer assumptions. ## Check the result Ask Claude to verify its own work before you look at it: ```text Run pnpm check and pnpm build, fix anything that fails, then start the dev server. ``` 1. Open the address the dev server prints (usually `http://127.0.0.1:4321`). 2. Click through the pages you changed, on a wide screen and a narrow one. 3. Ask Claude to show you a summary of the files it changed and why. If something is wrong, say what you see, in plain words: "the new section has no space above it on mobile" works better than guessing at the code. ## Publish through a pull request 1. Ask Claude to commit the change with a clear message, such as `feat: add brand photography page`. 2. Ask it to push the branch and open a pull request on GitHub. 3. Wait for the Netlify deploy preview link on the pull request and check the change there. 4. Merge the pull request. Netlify builds and publishes the live site. > **Warning:** Do not let Claude push directly to the main branch of a live website. A pull request with a deploy preview is your safety net, and it costs one extra minute. ## Good habits - Keep one change per session and per pull request. Small changes are easier to review and to undo. - Ask Claude to explain anything you do not understand before you merge. - Keep secrets such as API keys out of the chat and out of the repository. They belong in Netlify's environment variables. - If Claude suggests adding a new route file in `src/pages` for normal content, ask it to use a markdown file and a page type instead. That is how Viralistic sites stay maintainable. ## Next steps - [How a Viralistic Astro site is organised](https://viralistic.nl/help/astro/project-structure) - [Claude Code for non-developers](https://viralistic.nl/help/claude/claude-code-for-non-developers) - [Deploy to Netlify](https://viralistic.nl/help/astro/deploy-to-netlify) --- # Use Sanity with Astro > Decide when Sanity beats markdown, connect it to your Astro site with the official integration, and rebuild the site automatically when editors publish. Source: https://viralistic.nl/help/astro/sanity-for-astro Sanity is a hosted content platform with an editing app called Sanity Studio. This guide is for developers who want editors to manage content in a friendly interface while the website stays a fast, static Astro site. You will create a Sanity project, connect it with the official `@sanity/astro` integration, fetch content with GROQ, render images and rebuild the site on every publish. ## Sanity or markdown? Most Viralistic sites keep content as markdown in the repository. Choose Sanity only when it solves a real problem. | Keep markdown in the repo | Choose Sanity | | --------------------------------------------------------------- | ---------------------------------------------------- | | A few people edit, and they are fine with GitHub or Claude Code | Many editors who need a visual editor and roles | | Content changes weekly or less | Content changes daily, such as news or listings | | Pages follow fixed layouts | Content is reused across sites, apps or newsletters | | No extra service to pay for or maintain | Editors need drafts, scheduling and media management | ## Create a Sanity project and Studio 1. In a separate folder or repository, run: ```bash pnpm create sanity@latest ``` 2. Log in, create a new project and keep the default `production` dataset. 3. Pick a clean template, then describe your content types (for example `post` with `title`, `slug`, `description`, `mainImage` and `body`) in the Studio's schema files. 4. Start the Studio locally with `pnpm dev` and add a test document. 5. Deploy the Studio so editors can reach it on a `sanity.studio` address: ```bash pnpm dlx sanity@latest deploy ``` ### Standalone or embedded Studio Sanity recommends deploying the Studio on its own, as above. You can also embed it in the Astro site at a path like `/admin` with the `studioBasePath` option. That requires `@astrojs/react`, a `sanity.config.ts` file, your site's addresses in the project's CORS origins (with credentials allowed) and a rewrite so Studio sub-pages do not return a 404 on a static host: ```toml [[redirects]] from = "/admin/*" to = "/admin" status = 200 ``` > **Tip:** Viralistic sites ship no React. A standalone Studio keeps it that way and keeps editor traffic away from your website. ## Connect Astro to Sanity 1. In the Astro project, add the integration: ```bash pnpm astro add @sanity/astro ``` 2. Configure it in `astro.config.ts`, next to `fulldevIntegration()`: ```ts import sanity from "@sanity/astro" export default defineConfig({ integrations: [ fulldevIntegration({/* site, name, favicon, i18n */}), sanity({ projectId: "your-project-id", dataset: "production", apiVersion: "2026-03-01", useCdn: false, }), ], }) ``` 3. Add the type reference to `src/env.d.ts`: ```ts /// /// ``` Use `useCdn: false` for static builds: queries run once at build time, and you want the freshest content. > **Warning:** If you need a token (for drafts or private datasets), store it in an environment variable without the `PUBLIC_` prefix. Anything prefixed `PUBLIC_` can end up in the browser. ## Fetch content with GROQ The integration exposes a ready-made client: ```astro --- import { sanityClient } from "sanity:client" const posts = await sanityClient.fetch( `*[_type == "post" && defined(slug.current)] | order(publishedAt desc){ title, description, "slug": slug.current, mainImage }` ) --- ``` To keep the Viralistic architecture, do not scatter queries through components. Fetch whole page sets in one place, give each entry a `type` and validate it with a strict schema, so the single catch-all route and the layout renderer handle Sanity pages exactly like markdown pages. ## Render images Use `@sanity/image-url` so Sanity's image CDN resizes and converts images for you: ```ts import { createImageUrlBuilder } from "@sanity/image-url" import { sanityClient } from "sanity:client" const builder = createImageUrlBuilder(sanityClient) export const urlFor = (source: Parameters[0]) => builder.image(source) ``` In a block, request the size you display: `urlFor(image).width(1280).auto("format").url()`. Add a required `alt` field to every image type in your Sanity schema, because every image on a Viralistic site needs alt text. Do not pass Sanity image URLs through Astro's `` component; that processes them twice. ## Rebuild the site when editors publish A static site only shows new content after a new build. Connect the two with a build hook: 1. In Netlify, open the project configuration, find **Build hooks** under the continuous deployment settings and add a hook for your main branch. 2. Copy the hook URL. 3. At sanity.io/manage, open your project, go to **API**, then **Webhooks**, and create a webhook that posts to the hook URL for the `production` dataset on create, update and delete. 4. Leave any option to fire on drafts switched off, so only published changes trigger a build. 5. Publish a test change and watch a new deploy start in Netlify. > **Note:** Every publish starts a full build, which counts towards your Netlify build usage. For sites with many small edits a day, consider batching or server rendering instead. If you would rather have Sanity set up for you, book a strategic call: https://calendly.com/marrallisa/30min ## Next steps - [Edit text and pages](https://viralistic.nl/help/astro/edit-content) - [Images and media](https://viralistic.nl/help/astro/images-and-media) - [Deploy to Netlify](https://viralistic.nl/help/astro/deploy-to-netlify) --- # Images and media > Add images, video and downloads to your Viralistic Astro site so they look sharp, load fast and are accessible to every visitor. Source: https://viralistic.nl/help/astro/images-and-media Images make or break how a website feels, and they are also the most common reason a site is slow. This article is for anyone who adds images, video or files to a Viralistic Astro site. You will learn where each kind of file belongs, how to add an image to a page, which sizes to export and how to write alt text that helps people and search engines. ## Where files go There are two places for files, and the difference matters. - **`src/assets/`** is for images shown on pages. Astro optimises everything here during the build: it creates smaller versions for small screens, converts to modern formats and adds width and height so the page does not jump while loading. - **`public/`** is for files that must keep an exact, fixed address, such as PDFs in `public/downloads/`. Nothing in `public/` is optimised. > **Tip:** If you are unsure, use `src/assets/`. Only use `public/` when someone needs a stable link to the file itself. ## Add an image to a page 1. Export the image at a sensible size (see the table below) and give the file a descriptive name, such as `new-website-on-laptop.jpg`. 2. Place it in a folder inside `src/assets/`, for example `src/assets/cases/your-client/`. 3. Open the page's markdown file and point the image field to it with a path relative to that markdown file. The field name depends on the page type; a case page uses `heroImage`: ```yaml heroImage: src: ../../../assets/cases/your-client/new-website-on-laptop.jpg alt: The new website for Your Client shown on a laptop and a phone ``` 4. Check the page in the dev server or the deploy preview. The path counts folders up from the markdown file. From `src/content/pages/cases/your-client.md` you go up three folders (`../../../`) to reach `src/`. From `src/content/pages/about.md` you go up two (`../../`). > **Tip:** Every page also accepts an optional `image` field. That image is used when the page is shared on social media or in chat apps. > **Note:** If the path is wrong or the file is missing, the build stops with an error. That is deliberate: a broken image never reaches the live site. ### Images inside body text You can also place an image in the body of a page with markdown. The path works the same way as in the frontmatter, and the image is optimised too. From a post in `src/content/pages/insights/`: ```md ![Diagram of the three phases of a website project](../../../assets/insights/project-phases.png) ``` ## Sizes and formats Astro creates smaller copies automatically (Viralistic sites use widths from 640 to 2560 pixels), so you only supply one large version. | Where the image appears | Export width | Format | | ------------------------- | ----------------------- | ----------- | | Full-width hero or banner | 2560 px | JPG or WebP | | Image in a text column | 1600 px | JPG or WebP | | Card or thumbnail | 1280 px | JPG or WebP | | Logo or icon | Any | SVG | | Graphic with transparency | Double its display size | PNG or SVG | Keep source files reasonably small. A photo of several megabytes makes the repository and every build slower without making the website look better. ## Write useful alt text Every image on a Viralistic site needs an `alt` field; the schema requires it. Alt text is read aloud by screen readers and helps search engines understand the image. - Describe what matters in this context, in one sentence. - Do not start with "Image of" or "Photo of". - Mention the brand, place or product when it is relevant. - For a purely decorative image, use `alt: ""` so screen readers skip it. ## Video - **Longer videos** such as showreels and interviews belong on YouTube or Vimeo. Where a layout has a video field, you can usually paste a YouTube or Vimeo link, or a link to an `.mp4` file. - **Short background loops** work best as a few seconds of muted MP4, compressed before you upload it. Astro does not optimise video, so the file size is up to you. - Add captions to any video with speech. ## PDFs and downloads 1. Put the file in `public/downloads/`, for example `public/downloads/price-list.pdf`. 2. Link to it as `/downloads/price-list.pdf`. 3. For a download button, add `download: true` to the button in the frontmatter: ```yaml buttons: - label: Download the price list href: /downloads/price-list.pdf download: true ``` ## Next steps - [Edit text and pages](https://viralistic.nl/help/astro/edit-content) - [Score high on Lighthouse](https://viralistic.nl/help/astro/performance) - [Make your Astro site rank well](https://viralistic.nl/help/astro/astro-seo) --- # Add forms to a static site > Collect contact requests and sign-ups on a static Astro site with Netlify Forms or an n8n webhook, with spam protection and notifications. Source: https://viralistic.nl/help/astro/forms A static Astro site has no server of its own, so a form needs somewhere to send its data. This article is for developers and site owners who want a working contact or sign-up form without running a backend. You will learn the two routes Viralistic uses, how to set up each one, and how to keep spam and personal data under control. ## Choose a route | Route | Best for | What happens to a submission | | ------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | | Netlify Forms | Contact forms, quote requests, simple sign-ups | Stored in Netlify, emailed to you, optionally forwarded | | n8n webhook | Forms that should start a process | Sent to an n8n workflow that can write to a CRM, send replies or alert a channel | You can also combine them: Netlify Forms catches the submission and filters spam, then forwards it to n8n. ## Set up Netlify Forms Netlify reads the built HTML during each deploy, finds forms marked for Netlify and registers them. No extra code runs on a server. ### Enable form detection 1. Open your project in Netlify. 2. Go to the **Forms** section and enable form detection. 3. Deploy the site again. Detection only happens during a deploy. ### Mark up the form Give the form a `name`, add `data-netlify="true"` and include a hidden `form-name` field with the same name: ```astro
``` The `bot-field` is a honeypot: people never see it, bots fill it in, and Netlify silently drops those submissions. Netlify also filters spam on its side. > **Note:** On a Viralistic site, the form lives in a block (for example `contact-1.astro`) and the labels, placeholders and success message come from the page's frontmatter. Do not hard-code copy in the component. ### Submit without leaving the page By default the browser goes to a Netlify confirmation page after submitting. To show your own success message instead, send the form with JavaScript. This is the pattern the Viralistic contact block uses: ```ts form.addEventListener("submit", async (event) => { event.preventDefault() const body = new URLSearchParams( new FormData(form) as unknown as Record ) const response = await fetch("/", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: body.toString(), }) if (response.ok) form.reset() }) ``` Alternatively, add `action="/thank-you"` to the form and create a thank-you page as a normal markdown file. ### Get notified 1. In Netlify, open the form notification settings. 2. Add an email notification to the address that should receive submissions. 3. Optionally add an outgoing webhook to forward each submission to n8n or another tool. 4. Send a test submission from the live site and check that it arrives. > **Tip:** Netlify only detects forms in the HTML it builds. If a form only appears after JavaScript runs, Netlify will not find it. Astro renders forms as plain HTML, so this rarely bites on a Viralistic site. ## Send forms to n8n When a submission should trigger work (create a lead in your CRM, send a personal reply, book a follow-up), post it to an n8n workflow. 1. In n8n, create a workflow that starts with a Webhook node set to accept `POST`. 2. Copy its production URL and activate the workflow. 3. Either set that URL as the form's `action`, or keep Netlify Forms and add the URL as an outgoing webhook notification. 4. Add the steps you need after the webhook, and end with a clear response for the visitor. See [Receive data with webhooks](https://viralistic.nl/help/n8n/webhooks) for the details of the Webhook node. > **Warning:** A webhook URL that the browser posts to directly is public. Validate the input in the workflow, ignore submissions with a filled honeypot field and never let a form trigger anything expensive without a check. ## Privacy and good practice - Ask only for what you need. Every extra field lowers the number of people who finish the form. - Mention in your privacy policy where submissions are stored (Netlify, n8n, your CRM) and how long you keep them. - Use real `