Markdown & .md Files

Markdown Syntax

Markdown is a lightweight text format that converts to HTML. It’s used everywhere — GitHub, documentation sites, note-taking apps, and most importantly, in files that help Claude understand your project.

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Text Formatting

**bold text**
*italic text*
~~strikethrough~~
`inline code`
> blockquote

Lists

Unordered list:
- Item one
- Item two
  - Nested item
  - Another nested item

Ordered list:
1. First step
2. Second step
3. Third step

Links and Images

[Link text](https://example.com)
![Alt text](image-url.jpg)

Code Blocks

Inline code: `const x = 5`

Fenced code block:
```tsx
function Button({ label }: { label: string }) {
  return <button>{label}</button>
}
```

Tables

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

The SKILL.md File — Claude’s Standing Orders

A SKILL.md file is a markdown file you place in your project root that tells Claude how to behave across every session. It’s like a design brief that’s always active — Claude reads it and follows the rules without you repeating them.

Minimal SKILL.md

# SKILL.md

## Project
- Name: My Portfolio
- Stack: Next.js 14, TypeScript, Tailwind CSS

## Rules
- Use functional components with arrow functions
- Always use TypeScript interfaces for props
- Use Tailwind CSS — no inline styles
- Export components as named exports
- Place components in /components folder

Production-Quality SKILL.md

# SKILL.md — Design System Rules

## Project Overview
- Name: Studio Portfolio
- Stack: Next.js 14 + TypeScript + Tailwind CSS + Framer Motion
- Style: Minimal, editorial, lots of whitespace

## File Structure
- Pages: app/[route]/page.tsx
- Components: components/[ComponentName].tsx
- Styles: Tailwind only — no CSS modules, no styled-components

## Component Rules
- Use `"use client"` only when the component needs interactivity
- Always define a TypeScript interface for props
- Always use named exports: `export function Button() {}`
- Always include a `className` prop for style overrides
- Use Framer Motion for all animations

## Design Tokens
- Font: Inter for body, Space Grotesk for headings
- Colors: gray-900 for text, gray-500 for secondary, white for backgrounds
- Spacing: 4px base unit (Tailwind default)
- Border radius: rounded-lg for cards, rounded-full for avatars
- Shadows: shadow-sm for subtle, shadow-lg for elevated

## Naming Conventions
- Components: PascalCase (Button.tsx, HeroSection.tsx)
- Files: PascalCase for components, kebab-case for pages
- Props: camelCase (onClick, isActive, userName)

## Animation Defaults
- Duration: 0.3s for micro-interactions, 0.6s for transitions
- Easing: [0.25, 0.1, 0.25, 1] for smooth motion
- Always use `initial`, `animate`, and `exit` props

Tip: Reference your SKILL.md at the start of every Claude session: “Read my SKILL.md and follow all rules for this session.” This ensures consistency across every interaction.

Component Documentation Files

For complex components, create a dedicated markdown file that describes the component’s purpose, props, variants, and usage. This helps Claude generate exactly what you need.

# Button Component

## Purpose
Primary interaction element used across the entire application.

## File
`components/Button.tsx`

## Props
| Prop      | Type                            | Default     | Description           |
| --------- | ------------------------------- | ----------- | --------------------- |
| label     | string                          | —           | Button text           |
| variant   | "primary" | "ghost" | "danger"  | "primary"   | Visual style          |
| size      | "sm" | "md" | "lg"              | "md"        | Size variant          |
| disabled  | boolean                         | false       | Disabled state        |
| onClick   | () => void                      | —           | Click handler         |
| className | string                          | ""          | Additional CSS classes|

## Variants
- **primary**: Dark background, white text — used for main CTAs
- **ghost**: Transparent with border — used for secondary actions
- **danger**: Red background — used for destructive actions

## States
- Default → Hover → Focus → Active → Disabled

## Usage
```tsx
<Button label="Save changes" variant="primary" />
<Button label="Cancel" variant="ghost" />
<Button label="Delete" variant="danger" onClick={handleDelete} />
```

The README.md File

Every project should have a README.md in the root. It’s the first thing anyone sees on GitHub and gives Claude essential context about the project.

# Studio Portfolio

A minimal designer portfolio built with Next.js, TypeScript, and Tailwind CSS.

## Getting Started

```bash
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

## Project Structure

```
app/              → Pages and routing
components/       → Reusable UI components
public/           → Static assets (images, fonts)
```

## Tech Stack

- **Next.js 14** — React framework
- **TypeScript** — Type safety
- **Tailwind CSS** — Utility-first styling
- **Framer Motion** — Animations
- **Vercel** — Deployment

## Scripts

| Command          | Description            |
| ---------------- | ---------------------- |
| `npm run dev`    | Start dev server       |
| `npm run build`  | Production build       |
| `npm run lint`   | Lint code              |