# CLAUDE.md

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

## Project Overview

This is a **Claude Skills development environment** for creating and managing modular, self-contained skills that extend Claude's capabilities. The project includes skill creation tooling, example skills, and standalone scripts.

### Key Architecture

```
claudeskill/
├── .claude/skills/           # Available skills for Claude Code
│   ├── skill-creator/        # Meta-skill for creating new skills
│   └── excel-to-markdown/    # Excel to Markdown conversion skill
├── scripts/                  # Standalone scripts (can be referenced by skills)
│   └── excel_to_markdown.py  # Excel → Markdown converter
├── skills/                   # Development area for skills under development
│   └── excel-to-markdown/    # Development version of excel-to-markdown skill
└── .venv/                    # Python virtual environment (openpyxl dependency)
```

**Important:** Two locations exist for skills:
- `.claude/skills/` - Skills installed and available to Claude Code
- `skills/` - Development/staging area for new or modified skills

## Common Commands

### Environment Setup
```bash
# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install openpyxl
```

### Skill Development Workflow

**1. Initialize a new skill:**
```bash
python3 .claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path skills
```

**2. Test a script directly:**
```bash
# Test Excel to Markdown converter
python3 scripts/excel_to_markdown.py demo.xlsx -o demo.md --show-rows --show-cols

# Or use uv run (configured in permissions)
uv run --with openpyxl scripts/excel_to_markdown.py demo.xlsx -o output.md
```

**3. Package a skill (creates .skill file):**
```bash
python3 .claude/skills/skill-creator/scripts/package_skill.py skills/<skill-name>
```

**Note:** Only package skills when the user explicitly requests it. Skills are typically used directly from the directory structure during development.

## Skill Architecture

### Skill Structure

Every skill follows this structure:

```
skill-name/
├── SKILL.md (required)       # Main skill documentation with YAML frontmatter
├── scripts/ (optional)        # Executable code (Python/Bash/etc.)
├── references/ (optional)     # Documentation loaded into context as needed
└── assets/ (optional)         # Files used in output (templates, images, etc.)
```

### SKILL.md Format

**Required frontmatter:**
```yaml
---
name: skill-name
description: Clear description of when to use this skill (this is the primary trigger mechanism)
---
```

**Critical design principle:** The `description` field is the primary trigger mechanism. Include:
- What the skill does
- Specific scenarios/contexts when it should be used
- File types or tasks that trigger it

**Body:** Instructions and guidance (only loaded after skill triggers)

### Progressive Disclosure Strategy

Skills use a three-level loading system:
1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by Claude

**Best practices:**
- Keep SKILL.md body under 500 lines
- Split content into `references/` for domain-specific or variant-specific details
- Include clear links from SKILL.md to reference files with "when to use" guidance
- Avoid deeply nested references (keep references one level deep from SKILL.md)

### Resource Types

**scripts/** - Executable code for:
- Tasks that require deterministic reliability
- Operations that are repeatedly rewritten
- Fragile, error-prone sequences

**references/** - Documentation for:
- Domain knowledge (schemas, APIs, business logic)
- Detailed workflow guides
- Variant-specific information (e.g., different providers/frameworks)

**assets/** - Files for output:
- Templates (.pptx, .docx, boilerplate directories)
- Images, icons, fonts
- Files that get copied or used in final output

## Skill Creation Guidelines

### Core Principles

1. **Concise is Key** - Default assumption: Claude is already smart. Only add information Claude doesn't have. Challenge each piece of information's token cost.

2. **Appropriate Freedom Levels**:
   - **High freedom** (text instructions): Multiple valid approaches
   - **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists
   - **Low freedom** (specific scripts): Fragile/error-prone operations

3. **No Auxiliary Files** - Do NOT create README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, etc. Skills should only contain what an AI agent needs to do the job.

### Creation Process

Follow these steps in order:

1. **Understand with concrete examples** - Gather specific usage scenarios
2. **Plan reusable contents** - Identify scripts, references, assets needed
3. **Initialize skill** - Run `init_skill.py` to create template structure
4. **Edit the skill** - Implement resources and write SKILL.md
5. **Package** - Run `package_skill.py` to create .skill file (only when user requests)
6. **Iterate** - Improve based on real usage

### SKILL.md Writing Guidelines

**Structure patterns:**
- **Workflow-based**: Sequential processes with decision trees
- **Task-based**: Collection of operations/capabilities
- **Reference/Guidelines**: Standards or specifications
- **Capabilities-based**: Interrelated features

**Writing style:** Always use imperative/infinitive form (e.g., "Convert the file", not "You should convert the file")

**Frontmatter description example:**
```yaml
description: Comprehensive document creation, editing, and analysis. Use when Claude needs to work with .docx files for: (1) Creating new documents, (2) Modifying content, (3) Working with tracked changes, or any other document tasks
```

## Key Files

- `.claude/skills/skill-creator/SKILL.md` - Comprehensive guide for skill creation
- `.claude/skills/skill-creator/references/workflows.md` - Sequential and conditional workflow patterns
- `.claude/skills/skill-creator/references/output-patterns.md` - Template and example patterns
- `.claude/skills/skill-creator/scripts/init_skill.py` - Initialize new skill from template
- `.claude/skills/skill-creator/scripts/package_skill.py` - Package skill into .skill file (validates first)
- `.claude/skills/skill-creator/scripts/quick_validate.py` - Skill validation utilities

## Current Skills

### excel-to-markdown
Converts Excel (.xlsx, .xls) files to Markdown table format with automatic data range detection.

**Features:** Auto-detect data range, specify row/column ranges, show row/column numbers, handle cell special characters, partial data extraction

**Script location:** `scripts/excel_to_markdown.py`

**Dependencies:** `openpyxl` (already installed in `.venv/`)

### skill-creator
Meta-skill for creating effective skills. Provides templates, validation, and packaging tooling.

## Development Notes

- Python 3.10+ required
- Virtual environment at `.venv/` with `openpyxl` dependency
- The `.gitignore` excludes `.claude/` directory, `.venv/`, and Excel files
- Skills in `.claude/skills/` are automatically available to Claude Code
- Skills in `skills/` are under development/staging