@grimoire-cc/cli 0.6.3 → 0.7.1

package/packs/meta-pack/skills/gr.skill-developer/reference/file-organization.md

@@ -0,0 +1,452 @@
+# Skill File Organization Guide
+
+This guide provides comprehensive recommendations for organizing skill files to maximize performance, maintainability, and compliance with official Anthropic requirements.
+
+## Table of Contents
+
+- [Core Principles](#core-principles)
+- [Progressive Disclosure Architecture](#progressive-disclosure-architecture)
+- [Size Constraints](#size-constraints)
+- [Reference File Standards](#reference-file-standards)
+- [Linking Requirements](#linking-requirements)
+- [Table of Contents Requirements](#table-of-contents-requirements)
+- [File Size Optimization](#file-size-optimization)
+- [Well-Organized Examples](#well-organized-examples)
+- [Anti-Patterns](#anti-patterns)
+
+## Core Principles
+
+Effective skill organization follows these key principles:
+
+1. **Progressive Disclosure**: Core content in SKILL.md, detailed content in supporting files
+2. **Lazy Loading**: Files don't consume context until Claude accesses them
+3. **Flat Hierarchy**: Keep references one level deep from SKILL.md
+4. **Size Compliance**: Stay under official limits for performance
+5. **Discoverability**: Clear file names and organization
+
+## Progressive Disclosure Architecture
+
+### How It Works
+
+Progressive disclosure allows skills to contain extensive reference material without impacting context:
+
+- **Level 1 (Metadata)**: ~100 tokens per skill loaded at startup
+- **Level 2 (SKILL.md)**: Loaded when skill activates (up to 500 lines)
+- **Level 3 (Supporting Files)**: Loaded only when Claude needs them
+
+### Key Insight
+
+**Files don't consume context until accessed** - you can include dozens of reference files without penalty. The skill acts like a table of contents, pointing Claude to detailed materials as needed.
+
+### What Belongs Where
+
+**SKILL.md should contain:**
+- Overview and capabilities
+- How to use instructions
+- When to activate (trigger keywords)
+- Common use cases
+- Links to detailed reference materials
+- Essential examples
+
+**Supporting files should contain:**
+- Detailed specifications
+- Complete API references
+- Extended examples
+- Technical deep-dives
+- Complex workflows
+- Large data tables
+
+## Size Constraints
+
+### Official Anthropic Requirements
+
+**SKILL.md Body**
+- Maximum: **500 lines** (excluding YAML frontmatter)
+- Enforced: Validation script blocks if exceeded
+- Rationale: Optimal context window usage
+
+**Total Skill Bundle**
+- Maximum: **8MB** (all files combined)
+- Enforced: Validation script blocks if exceeded
+- Includes: SKILL.md + all supporting files + scripts
+
+**Skills Per Request**
+- Maximum: **8 skills** can be active per request
+- Context: Claude Code loads skills based on relevance
+
+### Why These Limits Matter
+
+- **Performance**: Smaller files load faster into context
+- **Cost**: Fewer tokens consumed per activation
+- **Maintainability**: Easier to update and navigate
+- **Compliance**: Required by Anthropic platform
+
+## Reference File Standards
+
+### Naming Conventions
+
+Use descriptive, hyphenated names:
+
+```text
+✅ GOOD:
+reference/api-specification.md
+reference/calculation-formulas.md
+reference/error-codes.md
+
+❌ BAD:
+reference/spec.md (too generic)
+reference/api_spec.md (underscores instead of hyphens)
+reference/APISpecification.md (camelCase)
+```
+
+### Directory Structure
+
+Keep structure flat and organized:
+
+```text
+.claude/skills/your-skill/
+├── SKILL.md                    # Main skill file (<500 lines)
+├── reference/                  # Detailed specifications
+│   ├── api-specification.md
+│   ├── data-formats.md
+│   └── error-handling.md
+├── examples/                   # Complete examples
+│   ├── basic-usage.md
+│   └── advanced-workflow.md
+├── templates/                  # Reusable templates
+│   └── report-template.md
+└── scripts/                    # Automation (optional)
+    └── process-data.py
+```
+
+### Single File vs. Multiple Files
+
+**Use a single reference file when:**
+- Content is tightly related (<200 lines)
+- Splitting would create artificial boundaries
+- Users typically need all information together
+
+**Use multiple reference files when:**
+- Content has distinct topics
+- Individual files would be >100 lines each
+- Users may need only specific sections
+- Improves navigation and maintenance
+
+## Linking Requirements
+
+### One Level Deep Rule
+
+**All reference files must link directly from SKILL.md** - do not nest references within other references.
+
+#### ✅ CORRECT: One Level Deep
+
+**SKILL.md:**
+```markdown
+For detailed API specifications, see [reference/api-specification.md](reference/api-specification.md).
+
+For error handling guidelines, see [reference/error-handling.md](reference/error-handling.md).
+```
+
+**reference/api-specification.md:**
+```markdown
+# API Specification
+
+## Endpoints
+
+### POST /api/process
+...
+```
+
+**reference/error-handling.md:**
+```markdown
+# Error Handling Guidelines
+
+## Error Codes
+...
+```
+
+#### ❌ INCORRECT: Nested References
+
+**SKILL.md:**
+```markdown
+For API information, see [reference/api-overview.md](reference/api-overview.md).
+```
+
+**reference/api-overview.md:**
+```markdown
+# API Overview
+
+For detailed endpoint specifications, see [reference/endpoints/post-endpoints.md](reference/endpoints/post-endpoints.md).
+```
+
+**Why this is wrong:** The user would need to read api-overview.md first, then follow a nested link. Claude should be able to read any reference file directly from SKILL.md.
+
+### Why One Level Deep?
+
+1. **Ensures complete reads**: Claude reads full files when accessing from SKILL.md
+2. **Avoids fragmentation**: User doesn't navigate multiple levels
+3. **Improves discoverability**: All references visible from main file
+4. **Simplifies maintenance**: Clear file relationships
+
+### Proper Linking Format
+
+Use relative paths with descriptive link text:
+
+```markdown
+✅ GOOD:
+See [API Specification](reference/api-specification.md) for complete endpoint details.
+
+For calculation formulas, refer to [reference/formulas.md](reference/formulas.md).
+
+❌ BAD:
+See api-specification.md (not a clickable link)
+See [here](reference/api-specification.md) (non-descriptive)
+See [API](../reference/api-specification.md) (unnecessary path navigation)
+```
+
+## Table of Contents Requirements
+
+### When Required
+
+**Reference files exceeding 100 lines must include a table of contents at the top.**
+
+### Why This Matters
+
+Even when Claude previews a file with partial reads, the table of contents ensures Claude can see the full scope of available information.
+
+### Format
+
+Place TOC immediately after the file title:
+
+```markdown
+# API Specification
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+  - [POST /api/process](#post-apiprocess)
+  - [GET /api/status](#get-apistatus)
+- [Error Codes](#error-codes)
+- [Rate Limiting](#rate-limiting)
+- [Examples](#examples)
+
+## Authentication
+
+...
+```
+
+### Best Practices
+
+- Use descriptive section names
+- Link to section anchors (GitHub-style)
+- Keep TOC concise (one level of nesting max)
+- Update TOC when adding/removing sections
+
+## File Size Optimization
+
+### Strategies to Stay Under Limits
+
+#### 1. Split Large Sections
+
+Instead of one large reference file, split by topic:
+
+```text
+Before (800 lines):
+reference/complete-guide.md
+
+After:
+reference/getting-started.md (150 lines)
+reference/advanced-usage.md (180 lines)
+reference/api-reference.md (220 lines)
+reference/troubleshooting.md (150 lines)
+```
+
+#### 2. Remove Redundancy
+
+- Don't repeat information from SKILL.md in reference files
+- Link between files instead of duplicating content
+- Use templates for repetitive structures
+
+#### 3. Move Examples to Dedicated Files
+
+```text
+examples/
+├── basic-usage.md           # Simple examples
+├── advanced-workflow.md     # Complex examples
+└── integration-patterns.md  # Real-world scenarios
+```
+
+#### 4. Use External Scripts
+
+Move complex logic to Python/Bash scripts instead of documenting in markdown:
+
+```text
+scripts/
+└── calculate-ratios.py  # Actual calculation logic
+
+reference/
+└── calculations.md      # High-level explanation + script usage
+```
+
+#### 5. Compress Tables and Data
+
+Instead of large markdown tables, consider:
+- CSV files referenced by scripts
+- JSON data files
+- External databases (when appropriate)
+
+### Checking Your Size
+
+Use the validation script to check current size:
+
+```bash
+cd ~/.claude/skills/skill-developer
+python scripts/validate-skill.py ~/.claude/skills/your-skill/SKILL.md
+```
+
+Output shows:
+- Line count for SKILL.md body
+- Total bundle size
+- Largest files
+- Recommendations
+
+## Well-Organized Examples
+
+### Example 1: Financial Analysis Skill
+
+```text
+.claude/skills/financial-analysis/
+├── SKILL.md (287 lines)          # Core skill definition
+├── reference/
+│   ├── ratio-formulas.md (156 lines, has TOC)
+│   ├── industry-standards.md (98 lines)
+│   └── data-sources.md (45 lines)
+├── examples/
+│   ├── quarterly-analysis.md
+│   └── peer-comparison.md
+└── scripts/
+    └── calculate-ratios.py
+
+Total size: 1.2MB
+```
+
+**Why this works:**
+- SKILL.md under 500 lines
+- Reference files split by topic
+- File >100 lines has TOC
+- All references one level from SKILL.md
+- Total bundle well under 8MB
+
+### Example 2: API Documentation Skill
+
+```text
+.claude/skills/api-docs/
+├── SKILL.md (421 lines)
+├── reference/
+│   ├── authentication.md (87 lines)
+│   ├── endpoints.md (234 lines, has TOC)
+│   ├── error-codes.md (112 lines, has TOC)
+│   └── rate-limiting.md (56 lines)
+└── examples/
+    ├── basic-requests.md
+    └── advanced-patterns.md
+
+Total size: 892KB
+```
+
+**Why this works:**
+- Clear separation of concerns
+- Large files have TOCs
+- Flat reference structure
+- Size well within limits
+
+## Anti-Patterns
+
+### ❌ Anti-Pattern 1: Monolithic SKILL.md
+
+```text
+.claude/skills/bad-example/
+└── SKILL.md (1,247 lines)  # Way over 500-line limit
+```
+
+**Problem**: Exceeds size limit, hard to maintain, poor context efficiency
+
+**Solution**: Split into SKILL.md + reference files
+
+### ❌ Anti-Pattern 2: Nested References
+
+```text
+.claude/skills/bad-example/
+├── SKILL.md
+└── reference/
+    ├── overview.md → links to detailed/
+    └── detailed/
+        ├── section1.md
+        └── section2.md
+```
+
+**Problem**: Violates "one level deep" rule
+
+**Solution**: Flatten to reference/*.md, all linked from SKILL.md
+
+### ❌ Anti-Pattern 3: Missing TOCs
+
+```text
+reference/
+└── massive-api-spec.md (847 lines, NO TOC)
+```
+
+**Problem**: Claude can't see full scope in partial read
+
+**Solution**: Add comprehensive TOC at top of file
+
+### ❌ Anti-Pattern 4: Unclear File Names
+
+```text
+reference/
+├── stuff.md
+├── misc.md
+└── notes.md
+```
+
+**Problem**: Non-descriptive, hard to know what to read
+
+**Solution**: Use descriptive names (api-specification.md, data-formats.md)
+
+### ❌ Anti-Pattern 5: Bloated Bundle
+
+```text
+.claude/skills/bad-example/
+├── SKILL.md
+├── reference/ (47 files, 12MB total)
+└── examples/ (hundreds of examples)
+```
+
+**Problem**: Exceeds 8MB limit
+
+**Solution**: Remove redundancy, consolidate files, use external resources
+
+## Summary Checklist
+
+When organizing your skill, verify:
+
+- [ ] SKILL.md body is under 500 lines
+- [ ] Total skill bundle is under 8MB
+- [ ] All references link directly from SKILL.md (one level deep)
+- [ ] Reference files >100 lines have table of contents
+- [ ] File names are descriptive and use hyphens
+- [ ] Directory structure is flat and logical
+- [ ] No redundant content across files
+- [ ] Validation script passes without errors
+
+## Validation
+
+Always validate your skill organization:
+
+```bash
+python ~/.claude/skills/skill-developer/scripts/validate-skill.py \
+  ~/.claude/skills/your-skill/SKILL.md
+```
+
+The script will check all requirements and provide actionable feedback for any violations.