diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9e86135 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,190 @@ +# 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 --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/ +``` + +**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