claudeskill/CLAUDE.md

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

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install openpyxl

Skill Development Workflow

1. Initialize a new skill:

python3 .claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path skills

2. Test a script directly:

# 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):

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:

---
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:

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