# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a Claude Skills collection repository containing:
- **ourdigital-custom-skills/**: Organization-specific skills (OurDigital workflows, Jamie Brand, SEO tools)
- **claude-skills-examples/**: Reference examples from Anthropic's official skills repository
- **official-skills-collection/**: Notion integration skills and other 3rd party examples
- **reference/**: Format requirements documentation

## Skill Structure

Every skill must follow this structure:
```
skill-name/
├── SKILL.md (required)     # YAML frontmatter + instructions
├── scripts/                # Executable code (Python/Bash)
├── references/             # Documentation loaded as needed
├── assets/                 # Templates, images, fonts
├── templates/              # Output templates (HTML, MD)
└── examples/               # Usage examples
```

### SKILL.md Format Requirements

All SKILL.md files MUST start with YAML frontmatter:
```yaml
---
name: skill-name-here      # lowercase with hyphens, required
version: 1.0.0             # semantic versioning
description: Description   # when Claude should use this skill, required
author: Author Name
tags:
  - tag1
  - tag2
---
```

## Creating New Skills

Use the skill creator initialization script:
```bash
python claude-skills-examples/skills-main/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
```

Package a skill for distribution:
```bash
python claude-skills-examples/skills-main/skill-creator/scripts/package_skill.py <path/to/skill-folder>
```

## Skill Design Principles

1. **Progressive Disclosure**: Skills use three-level loading:
   - Metadata (name + description) - always in context (~100 words)
   - SKILL.md body - when skill triggers (<5k words)
   - Bundled resources - as needed by Claude

2. **Writing Style**: Use imperative/infinitive form (verb-first), not second person. Write for AI consumption.

3. **Resource Organization**:
   - `scripts/` - For repeatedly rewritten or deterministic code
   - `references/` - For documentation Claude reads while working (keep >10k word files searchable via grep patterns)
   - `assets/` - For output resources (templates, images) not loaded into context

## Directory Layout

```
ourdigital-custom-skills/             # Production custom skills
├── 00-ourdigital-visual-storytelling/   # Blog featured image prompts
├── 01-ourdigital-research-publisher/    # Research-to-publication workflow
├── 02-notion-organizer/                 # Notion workspace management
├── 03-research-to-presentation/         # Research to slides (legacy format)
├── 04-seo-gateway-strategist/           # SEO gateway page planning
├── 05-gateway-page-content-builder/     # Gateway page content generation
├── 20-jamie-brand-editor/               # Jamie Clinic content editor
└── 21-jamie-brand-guardian/             # Jamie Clinic brand compliance

claude-skills-examples/skills-main/  # Anthropic reference examples
├── skill-creator/          # Meta skill for creating skills
├── document-skills/        # docx, pdf, pptx, xlsx manipulation
├── algorithmic-art/        # p5.js generative art
├── mcp-builder/            # MCP server creation guide
└── webapp-testing/         # Playwright testing

official-skills-collection/          # 3rd party skills
├── notion-meeting-intelligence/
├── notion-research-documentation/
├── notion-knowledge-capture/
└── notion-spec-to-implementation/
```

## Key Reference Files

- `reference/SKILL-FORMAT-REQUIREMENTS.md` - Format specification
- `claude-skills-examples/skills-main/skill-creator/SKILL.md` - Comprehensive skill creation guide
- `claude-skills-examples/skills-main/README.md` - Official skills documentation