Markdown Basics — A Basics to Writing Skill Files and Instructions for Cowork

Why Learn Markdown?

As you start getting more out of Cowork, you'll find yourself writing skill files (SKILL.md) and project instruction files (CLAUDE.md) more often. These files are all written in Markdown — a lightweight markup language that lets you create well-structured documents using simple, readable syntax.

Unlike HTML, there's no need to memorize complex tags. With just a handful of symbols, you can create headings, lists, code blocks, links, and tables. It's the same syntax used across GitHub, Notion, and countless other platforms, so the skills you pick up here will serve you well everywhere.

Headings

Headings give your document structure. Use # symbols to define heading levels — the more # symbols, the deeper the level.

# Heading Level 1 (h1)
## Heading Level 2 (h2)
### Heading Level 3 (h3)
#### Heading Level 4 (h4)

In skill files, here's how headings are typically used:

• # — The document title (use only once per file)
• ## — Major sections like "Step 1: Setup" or "Step 2: Execution"
• ### — Subsections within a step, such as "File Placement" or "Configuration"

Here's what this looks like in a real SKILL.md:

# Content Auto-Update Skill
 
## Step 0: Repository Setup
 
### System Requirements
- Node.js 18 or later
- npm or yarn
 
### Installation
1. Clone the repository
2. Install dependencies

Paragraphs and Line Breaks

In Markdown, plain text becomes a paragraph automatically. To start a new paragraph, leave a blank line between blocks of text.

This is the first paragraph.
This continues as part of the same paragraph.
 
A blank line creates a new paragraph here.

If you want a line break without starting a new paragraph, add two spaces at the end of a line or use a <br> tag. That said, for skill files, separating content with blank lines between paragraphs is the cleaner and recommended approach.

Text Formatting

Use these symbols to emphasize important parts of your text:

**Bold** — for important keywords and warnings
*Italic* — for introducing terms or adding nuance
~~Strikethrough~~ — for deprecated information or bad examples
`Inline code` — for command names, file names, and variables

In skill files, you'll use **bold** and `inline code` most often. For example, in a CLAUDE.md file:

**Important**: Always create articles in both Japanese and English.
Run `npm install` with the `--ignore-scripts` flag.

Lists

Unordered Lists

Start a line with -, *, or + to create a bullet point.

- Item A
- Item B
- Item C

Indent with 2–4 spaces to create nested lists:

- Main item
  - Sub-item 1
  - Sub-item 2
    - Deeper item

Ordered Lists

Start each line with a number followed by a period:

1. First step
2. Second step
3. Third step

A good rule of thumb for skill files: use ordered lists for sequential steps and unordered lists for options or parallel information.

Code Blocks

Code blocks are one of the most important elements in technical documents. Wrap your code in triple backticks (```) and specify the language for syntax highlighting.

```bash
npm install --prefer-offline
node scripts/generate-content.mjs
```

Here are some commonly used language identifiers:

In skill files, commands the user should run go in bash blocks, while configuration content goes in json or yaml blocks.

# Clone the repo and navigate to the working directory
git clone --depth 1 https://github.com/example/repo.git
cd repo
 
# Install dependencies
npm install

Links and Images

Links

[Display text](URL)

For example, linking to a related article:

See Skills & Plugins Guide for details.

Images

![Alt text](path/to/image)

Images aren't commonly used in skill files, but they're handy for README files or operational guides where screenshots help clarify the workflow.

Tables

Create tables using pipe characters (|) and hyphens (-):

| Field | Description | Default |
|-------|-------------|---------|
| title | Article title | None (required) |
| slug | URL-friendly slug | None (required) |
| level | Difficulty level | beginner |

You can control column alignment with colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| text | text | text |

Tables are particularly useful in skill files for listing configuration options, command references, or error handling guides.

Blockquotes and Callouts

Blockquotes

Prefix a line with > to create a blockquote:

> **Note**: This skill runs all steps autonomously without confirmation.

Blockquotes work well in skill files for highlighting important warnings or supplementary notes. You can nest them too:

> Outer quote
> > Nested quote (for additional context)

Callouts (MDX Extension)

In Claude Lab's MDX articles, you can use the <Callout> component to emphasize tips and warnings:

<div class="callout callout-info"><span class="callout-icon">ℹ️</span><div>Supplementary information goes here.</div></div>
 
<div class="callout callout-warning"><span class="callout-icon">⚠️</span><div>Important warnings go here.</div></div>

Horizontal Rules

To add a visual separator between sections, use three or more hyphens (---) surrounded by blank lines:

## Section A
 
Content for Section A.
 
---
 
## Section B
 
Content for Section B.

In skill files, placing --- between steps makes long documents much easier to scan.

Putting It Together — A SKILL.md Template

Let's combine everything you've learned into a practical skill file template:

---
name: my-custom-skill
description: "Describe what your custom skill does"
---
 
# My Custom Skill
 
This skill automates the process of doing X.
 
> **Note**: Always back up your data before running this skill.
 
## Step 1: Setup
 
### Prerequisites
 
- Node.js 18 or later
- npm or yarn
- Git
 
### Installation
 
1. Navigate to the working directory
2. Install dependencies
 
```bash
cd /tmp/work
npm install

Step 2: Execution

| Command | Description | |---------|-------------| | npm run build | Run the build process | | npm run deploy | Deploy to production |

Error Handling

| Problem | Solution | |---------|----------| | npm install fails | Try --legacy-peer-deps | | Build error | Check logs and identify the root cause |

This template demonstrates all the core Markdown elements — headings, lists, code blocks, tables, blockquotes, and horizontal rules — in a real-world context.

## Choosing an Editor

You can edit Markdown files in any text editor. However, when managing skill files and instruction documents, it helps to have an environment that combines file management with editing.

If you'd like to browse, edit, and organize files right from your browser, Google's AI code editor **Antigravity** (formerly Project IDX) is a solid option. It's a cloud-based development environment that lets you preview Markdown and manage Git without installing anything locally. You can find more tips on working with Antigravity at [Antigravity Lab](https://antigravitylab.net).

Of course, local editors like VS Code or Cursor with Markdown preview extensions work just as well. Choose whatever fits your workflow best.

## Wrapping Up

Markdown is a remarkably practical tool for creating structured, readable documents with minimal syntax. For writing Cowork skill files and project instructions, the basics covered in this guide are all you need to get started.

Start with just three things — headings, lists, and code blocks — and you'll be able to write your first skill file right away. As you get comfortable, incorporate tables, links, and other elements to make your documents even clearer.

To learn more about Cowork's skill system, check out Automating Repetitive Tasks with Cowork and [File Management and Desktop Operations](/articles/cowork/file-management).