@grimoire-cc/cli 0.6.2 → 0.7.0

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

@@ -0,0 +1,459 @@
+# Common Skill Patterns
+
+Proven patterns for different types of skills, based on Anthropic cookbook examples.
+
+## Table of Contents
+
+- [Pattern 1: Structured Data Processing](#pattern-1-structured-data-processing)
+- [Pattern 2: Standards Enforcement](#pattern-2-standards-enforcement)
+- [Pattern 3: Multi-Step Workflows](#pattern-3-multi-step-workflows)
+- [Pattern 4: Reference and Lookup](#pattern-4-reference-and-lookup)
+- [Choosing the Right Pattern](#choosing-the-right-pattern)
+- [Mixing Patterns](#mixing-patterns)
+- [Resources](#resources)
+
+## Pattern 1: Structured Data Processing
+
+**Use for:** Skills that process structured data (financial analysis, scientific calculations, data transformation)
+
+### Characteristics
+
+- Clear input format requirements
+- Deterministic processing steps
+- Structured output with calculations
+- Often includes scripts for complex logic
+
+### Structure Template
+
+```markdown
+## Capabilities
+
+Process and analyze:
+- **Data Type 1**: Specific processing
+- **Data Type 2**: Specific calculations
+- **Data Type 3**: Specific transformations
+
+## Input Format
+
+Accepts multiple formats:
+- **CSV**: Column headers: Field1, Field2, Field3
+- **JSON**: `{"field1": value, "field2": value}`
+- **Excel**: Sheet name "Data" with labeled rows
+
+Minimum required fields:
+- Field1 (required): Description
+- Field2 (required): Description
+- Field3 (optional): Description
+
+## Processing Steps
+
+1. **Validate data completeness**
+   - Check all required fields present
+   - Verify data types and ranges
+   - Handle missing values appropriately
+
+2. **Transform to standard format**
+   - Normalize units and scales
+   - Convert to consistent data structure
+   - Apply any necessary conversions
+
+3. **Perform calculations**
+   - Execute primary analysis
+   - Calculate derived metrics
+   - Generate comparisons
+
+4. **Interpret results**
+   - Apply domain expertise
+   - Compare to benchmarks
+   - Identify notable patterns
+
+## Output Format
+
+Structured results including:
+- **Calculated values:** Primary metrics with units
+- **Benchmarks:** Comparisons to standards (when available)
+- **Trends:** Historical or comparative analysis
+- **Interpretations:** Domain-specific insights
+- **Formatted report:** Excel/PDF with visualizations
+
+## Scripts
+
+- `process_data.py`: Main data processing engine
+- `validate_input.py`: Input validation and sanitization
+- `calculate_metrics.py`: Core calculations
+- `generate_report.py`: Output formatting
+```
+
+### Examples Using This Pattern
+
+- Financial ratio analysis
+- Scientific data analysis
+- Statistical processing
+- Data quality assessment
+
+---
+
+## Pattern 2: Standards Enforcement
+
+**Use for:** Skills that enforce consistency (brand guidelines, coding standards, compliance checking)
+
+### Characteristics
+
+- Detailed specifications and rules
+- Validation checklists
+- Before/after examples
+- Compliance verification
+
+### Structure Template
+
+```markdown
+## Standards Overview
+
+This skill enforces [domain] standards for consistent, compliant [outputs].
+
+### Applicable To
+
+- Document Type 1 (PowerPoint presentations)
+- Document Type 2 (Excel workbooks)
+- Document Type 3 (PDF reports)
+
+## Standards Specifications
+
+### Category 1: Visual Standards
+
+**Color Palette:**
+- **Primary Color**: #0066CC - Use for headers, CTAs
+- **Secondary Color**: #003366 - Use for body text
+- **Accent Color**: #28A745 - Use for success states
+- **Never use:** Colors outside approved palette
+
+**Typography:**
+- **H1**: 32pt Bold Primary Font
+- **H2**: 24pt Semibold Primary Font
+- **Body**: 11pt Regular Primary Font
+- **Minimum line spacing**: 1.15
+
+### Category 2: Content Standards
+
+**Tone and Voice:**
+- Professional yet approachable
+- Active voice preferred
+- Sentence length <20 words
+- Avoid jargon unless defined
+
+**Required Elements:**
+- Document title (top-right)
+- Company logo (top-left)
+- Page numbers (centered bottom)
+- Date (bottom-right)
+
+### Category 3: Format Standards
+
+**Page Setup:**
+- Size: Letter (8.5" × 11")
+- Margins: 1" all sides
+- Orientation: Portrait (unless exception)
+
+**File Naming:**
+- Format: `[Category]_[Title]_[Date]_[Version].ext`
+- Example: `Report_Q4Analysis_2024-01-15_v2.pdf`
+
+## Validation Checklist
+
+Before finalizing, verify:
+
+**Visual Compliance:**
+- [ ] Colors match approved palette
+- [ ] Fonts are from approved list
+- [ ] Logo placement correct
+- [ ] Spacing meets minimums
+
+**Content Compliance:**
+- [ ] Tone matches standards
+- [ ] Required elements present
+- [ ] Terminology consistent
+- [ ] Grammar and style correct
+
+**Format Compliance:**
+- [ ] Page setup correct
+- [ ] File named properly
+- [ ] Metadata complete
+- [ ] Quality standards met
+
+## Scripts
+
+- `apply_standards.py`: Automated standards application
+- `validate_compliance.py`: Compliance verification
+- `generate_report.py`: Compliance report generation
+```
+
+### Examples Using This Pattern
+
+- Corporate brand guidelines
+- Coding style enforcement
+- Document formatting standards
+- Regulatory compliance checking
+
+---
+
+## Pattern 3: Multi-Step Workflows
+
+**Use for:** Skills that guide complex processes (project setup, analysis workflows, multi-stage operations)
+
+### Characteristics
+
+- Sequential phases with dependencies
+- Clear success criteria for each phase
+- Decision points and branching
+- Progress tracking
+
+### Structure Template
+
+```markdown
+## Workflow Overview
+
+This skill guides you through [process name] in [X] phases.
+
+**Total time:** Estimate
+**Prerequisites:** What's needed before starting
+**Outputs:** What you'll have when done
+
+## Phase 1: Preparation
+
+**Objective:** Set up environment and gather requirements
+
+### Steps
+
+1. **Gather inputs**
+   - Item 1: Description and source
+   - Item 2: Description and source
+   - Item 3: Description and source
+
+2. **Validate prerequisites**
+   - [ ] Requirement 1 met
+   - [ ] Requirement 2 met
+   - [ ] Requirement 3 met
+
+3. **Set up environment**
+   - Action 1: Specific instructions
+   - Action 2: Specific instructions
+
+### Success Criteria
+
+- [ ] All inputs collected
+- [ ] Prerequisites validated
+- [ ] Environment ready
+
+**Next:** Proceed to Phase 2 only after all criteria met
+
+## Phase 2: Execution
+
+**Objective:** Perform main operations
+
+### Steps
+
+1. **Process data**
+   - Substep 1: Details
+   - Substep 2: Details
+   - Substep 3: Details
+
+2. **Generate outputs**
+   - Output 1: Format and content
+   - Output 2: Format and content
+
+3. **Verify results**
+   - Check 1: What to verify
+   - Check 2: What to verify
+
+### Decision Point
+
+**If verification passes:** Proceed to Phase 3
+**If issues found:** Return to step 1 with corrections
+
+### Success Criteria
+
+- [ ] Processing complete
+- [ ] Outputs generated
+- [ ] Results verified
+
+## Phase 3: Finalization
+
+**Objective:** Complete and deliver results
+
+### Steps
+
+1. **Format deliverables**
+   - Apply formatting standards
+   - Add documentation
+   - Package for delivery
+
+2. **Quality review**
+   - [ ] Completeness check
+   - [ ] Accuracy check
+   - [ ] Format check
+
+3. **Deliver and document**
+   - Submit deliverables
+   - Document process
+   - Archive artifacts
+
+### Success Criteria
+
+- [ ] All deliverables complete
+- [ ] Quality standards met
+- [ ] Documentation finalized
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue 1: Problem description**
+- Cause: What causes this
+- Solution: How to fix
+- Prevention: How to avoid
+
+**Issue 2: Problem description**
+- Cause: What causes this
+- Solution: How to fix
+- Prevention: How to avoid
+
+## Scripts
+
+- `phase1_setup.py`: Automates preparation phase
+- `phase2_process.py`: Executes main operations
+- `phase3_finalize.py`: Handles finalization
+- `verify_phase.py`: Validates phase completion
+```
+
+### Examples Using This Pattern
+
+- Project initialization workflows
+- Data migration processes
+- Analysis pipelines
+- Deployment procedures
+
+---
+
+## Pattern 4: Reference and Lookup
+
+**Use for:** Skills that provide quick reference information (API docs, formula references, terminology)
+
+### Characteristics
+
+- Organized by category or topic
+- Searchable structure
+- Quick access to specific information
+- Minimal processing, maximum reference
+
+### Structure Template
+
+```markdown
+## Quick Reference
+
+Fast lookup for [domain] information.
+
+### Category 1: [Name]
+
+#### Item 1
+**Description:** Brief explanation
+**Usage:** When and how to use
+**Example:** `concrete example`
+**Related:** Links to related items
+
+#### Item 2
+**Description:** Brief explanation
+**Usage:** When and how to use
+**Example:** `concrete example`
+**Related:** Links to related items
+
+### Category 2: [Name]
+
+#### Item 1
+**Formula:** `mathematical or code formula`
+**Parameters:**
+- `param1`: Description and valid range
+- `param2`: Description and valid range
+**Returns:** What it produces
+**Example:** Working example with values
+
+## Common Combinations
+
+Frequently used together:
+
+**Combination 1: Use Case Name**
+- Use Item A for: Purpose
+- Then Item B for: Purpose
+- Finally Item C for: Purpose
+
+**Combination 2: Use Case Name**
+- Start with Item X
+- Apply Item Y
+- Validate with Item Z
+
+## Lookup Tables
+
+### Table 1: [Name]
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| Entry 1 | Data | Context |
+| Entry 2 | Data | Context |
+
+### Table 2: [Name]
+
+| Parameter | Range | Default | Description |
+|-----------|-------|---------|-------------|
+| Param 1 | 0-100 | 50 | Details |
+| Param 2 | A-Z | A | Details |
+```
+
+### Examples Using This Pattern
+
+- API reference documentation
+- Formula and calculation guides
+- Configuration references
+- Terminology glossaries
+
+---
+
+## Choosing the Right Pattern
+
+| If your skill... | Use this pattern |
+|------------------|------------------|
+| Processes data with calculations | Structured Data Processing |
+| Enforces rules or standards | Standards Enforcement |
+| Guides multi-step processes | Multi-Step Workflows |
+| Provides reference information | Reference and Lookup |
+| Combines multiple aspects | Mix patterns as needed |
+
+## Mixing Patterns
+
+Complex skills can combine patterns:
+
+**Example: Financial Analysis Skill**
+
+- **Primary:** Structured Data Processing (for calculations)
+- **Secondary:** Reference and Lookup (for ratio definitions)
+- **Tertiary:** Standards Enforcement (for report formatting)
+
+**Structure:**
+
+```markdown
+## Capabilities
+[List all capabilities across patterns]
+
+## Financial Ratio Reference
+[Reference pattern for definitions]
+
+## Data Processing
+[Structured data pattern for calculations]
+
+## Report Standards
+[Standards enforcement for outputs]
+```
+
+## Resources
+
+- See `examples/` directory for complete skill examples using these patterns
+- Refer to `templates/` for starting templates
+- Check `reference/best-practices.md` for quality guidelines

package/packs/meta-pack/skills/gr.skill-developer/reference/yaml-spec.md

@@ -0,0 +1,214 @@
+# YAML Frontmatter Specification
+
+Complete specification for skill YAML frontmatter requirements based on official Anthropic documentation.
+
+## Table of Contents
+
+- [Required Structure](#required-structure)
+- [File Size Constraints](#file-size-constraints)
+- [Field Requirements](#field-requirements)
+  - [name Field](#name-field)
+  - [description Field](#description-field)
+- [Keyword Strategy](#keyword-strategy)
+- [Validation Checklist](#validation-checklist)
+- [Directory Naming](#directory-naming)
+- [Source](#source)
+
+## Required Structure
+
+Every SKILL.md file MUST start with YAML frontmatter:
+
+```yaml
+---
+name: your-skill-name
+description: Brief description of what this Skill does and when to use it
+---
+```
+
+## File Size Constraints
+
+Every skill must comply with these official Anthropic size limits:
+
+### SKILL.md Body Size
+
+**Maximum:** 500 lines (excluding YAML frontmatter)
+
+**Enforcement:** Validation script will block skills exceeding this limit
+
+**Rationale:** Optimal context window usage and performance
+
+**How to comply:**
+- Keep core instructions in SKILL.md
+- Move detailed content to supporting files (reference/, examples/, templates/)
+- Link to supporting files for additional details
+
+### Total Skill Bundle Size
+
+**Maximum:** 8MB (all files combined)
+
+**Includes:** SKILL.md + all supporting files (reference/, examples/, templates/, scripts/)
+
+**Enforcement:** Validation script will block if total size exceeds limit
+
+**How to comply:**
+- Remove redundant content
+- Compress or remove large images
+- Split large files by topic
+- Use external resources for very large datasets
+
+### Skills Per Request Limit
+
+**Maximum:** 8 skills can be loaded per request
+
+**Context:** Claude Code automatically loads relevant skills based on user queries. This limit ensures context window efficiency.
+
+### Additional Requirements
+
+**Reference files >100 lines:** Should include a table of contents at the top
+
+**Enforcement:** Validation script warns (non-blocking) if missing
+
+**Purpose:** Ensures Claude can see full scope even in partial file reads
+
+**Reference file linking:** Keep all references one level deep from SKILL.md
+
+**Enforcement:** Validation script warns if nested references detected
+
+**Purpose:** Ensures Claude can access any reference directly from SKILL.md
+
+## Field Requirements
+
+### `name` Field
+
+**Type:** String
+**Required:** Yes
+**Maximum length:** 64 characters
+
+**Format rules:**
+
+- Lowercase letters only (a-z)
+- Numbers allowed (0-9)
+- Hyphens allowed as separators (-)
+- No other characters (no underscores, spaces, or special characters)
+- No XML tags
+- Must match directory name exactly
+
+**Reserved words (cannot use):**
+
+- "anthropic"
+- "claude"
+
+**Examples:**
+
+✅ **Valid names:**
+
+- `analyzing-financial-statements`
+- `python-data-science`
+- `brand-guidelines-2024`
+- `api-design-patterns`
+
+❌ **Invalid names:**
+
+- `Analyzing_Financial_Statements` (uppercase, underscores)
+- `python data science` (spaces)
+- `claude-helper` (reserved word)
+- `api.design.patterns` (periods not allowed)
+- `very-long-skill-name-that-exceeds-the-sixty-four-character-limit-for-names` (>64 chars)
+
+### `description` Field
+
+**Type:** String
+**Required:** Yes
+**Minimum length:** 1 character (non-empty)
+**Maximum length:** 1024 characters
+
+**Content requirements:**
+
+- No XML tags
+- Must include BOTH:
+  1. **What** the skill does (functionality)
+  2. **When** to use it (trigger keywords)
+
+**Purpose:**
+The description enables Claude's automatic skill activation. When users ask questions matching keywords in the description, Claude loads this skill.
+
+**Best practice formula:**
+
+```text
+[Domain/Technology] + [What it does] + [When/Keywords for activation]
+```
+
+**Examples:**
+
+✅ **Good descriptions:**
+
+```yaml
+description: "This skill calculates key financial ratios and metrics from financial statement data for investment analysis"
+# Keywords: financial ratios, metrics, financial statement, investment analysis
+
+description: "Python coding standards and patterns for data science projects. Use when writing Python code, analyzing data, or creating visualizations"
+# Keywords: Python, coding standards, data science, writing code, analyzing data, visualizations
+
+description: "This skill applies consistent corporate branding and styling to all generated documents including colors, fonts, layouts, and messaging"
+# Keywords: branding, styling, documents, colors, fonts, layouts, messaging
+```
+
+❌ **Bad descriptions:**
+
+```yaml
+description: "Helps with finance"
+# Too vague, no trigger keywords
+
+description: "Contains brand information"
+# No actionable keywords, doesn't explain when to use
+
+description: "ROE, ROA, P/E calculator"
+# Too technical without context, unclear when to activate
+```
+
+## Keyword Strategy
+
+Include these in your description for better discoverability:
+
+1. **Domain/Technology terms:** "financial analysis", "Python", "brand guidelines"
+2. **Action verbs:** "calculates", "applies", "analyzes", "creates", "validates"
+3. **Object nouns:** "ratios", "documents", "code", "data", "reports"
+4. **Use cases:** "investment analysis", "data science projects", "corporate branding"
+5. **Natural phrases:** How users would actually ask questions
+
+## Validation Checklist
+
+Before finalizing frontmatter:
+
+- [ ] YAML starts with `---` on its own line
+- [ ] YAML ends with `---` on its own line
+- [ ] `name` field present and not empty
+- [ ] `name` is ≤64 characters
+- [ ] `name` uses only lowercase, numbers, hyphens
+- [ ] `name` doesn't contain "anthropic" or "claude"
+- [ ] `name` matches directory name exactly
+- [ ] `description` field present and not empty
+- [ ] `description` is ≤1024 characters
+- [ ] `description` explains WHAT skill does
+- [ ] `description` includes WHEN keywords
+- [ ] No XML tags in any field
+- [ ] No trailing spaces or formatting issues
+
+## Directory Naming
+
+The skill directory name must match the `name` field exactly:
+
+```text
+✅ Correct:
+.claude/skills/analyzing-financial-statements/
+  └── SKILL.md (name: analyzing-financial-statements)
+
+❌ Incorrect:
+.claude/skills/financial-analysis/
+  └── SKILL.md (name: analyzing-financial-statements)
+  # Mismatch! Directory doesn't match name field
+```
+
+## Source
+
+Based on [Official Claude Code Skills Documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)