Add CLAUDE.md documentation for future Claude Code instances
Provides comprehensive guidance on the project's skill development environment, including architecture, common commands, skill creation workflow, and coding guidelines. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Misaka Company
190
CLAUDE.md
Normal file
190
CLAUDE.md
Normal file
@@ -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 <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
|
||||
Reference in New Issue
Block a user