@grimoire-cc/cli 0.6.3 → 0.7.1

package/packs/meta-pack/skills/gr.skill-developer/examples/brand-guidelines.md

@@ -0,0 +1,94 @@
+# Brand Guidelines Skill Example
+
+This is a complete example of a skill that applies corporate branding standards to documents.
+
+```yaml
+---
+name: applying-brand-guidelines
+description: This skill applies consistent corporate branding and styling to all generated documents including colors, fonts, layouts, and messaging
+---
+
+# Corporate Brand Guidelines Skill
+
+This skill ensures all generated documents adhere to corporate brand standards for consistent, professional communication.
+
+## Brand Identity
+
+### Company: Acme Corporation
+**Tagline**: "Innovation Through Excellence"
+**Industry**: Technology Solutions
+
+## Visual Standards
+
+### Color Palette
+
+**Primary Colors**:
+- **Acme Blue**: #0066CC (RGB: 0, 102, 204) - Headers, primary buttons
+- **Acme Navy**: #003366 (RGB: 0, 51, 102) - Text, accents
+- **White**: #FFFFFF - Backgrounds, reverse text
+
+**Secondary Colors**:
+- **Success Green**: #28A745 - Positive metrics
+- **Warning Amber**: #FFC107 - Cautions
+- **Error Red**: #DC3545 - Negative values
+- **Neutral Gray**: #6C757D - Secondary text
+
+### Typography
+
+**Primary Font Family**: Segoe UI, system-ui, sans-serif
+
+**Font Hierarchy**:
+- **H1**: 32pt, Bold, Acme Blue
+- **H2**: 24pt, Semibold, Acme Navy
+- **H3**: 18pt, Semibold, Acme Navy
+- **Body**: 11pt, Regular, Acme Navy
+- **Caption**: 9pt, Regular, Neutral Gray
+
+## Document Standards
+
+### PowerPoint Templates
+- Title slide: Acme Blue background, white text
+- Content slides: White background, Acme Navy text
+- Charts: Use primary/secondary color palette
+- Footer: Company name, page number, date
+
+### Excel Workbooks
+- Header row: Acme Blue background, white bold text
+- Data rows: Alternating white/light gray (#F8F9FA)
+- Numbers: Right-aligned, 2 decimal places
+- Currency: $ prefix, comma separators
+
+### PDF Documents
+- Page size: Letter (8.5" x 11")
+- Margins: 1" all sides
+- Header: Company logo (top-left), document title (top-right)
+- Footer: Page numbers centered
+
+## Content Guidelines
+
+### Tone and Voice
+- **Professional yet approachable**: Avoid jargon, use clear language
+- **Confident and innovative**: Emphasize solutions and possibilities
+- **Customer-focused**: Address client needs and benefits
+
+### Messaging Standards
+- Lead with value proposition
+- Use active voice
+- Keep sentences concise (<20 words)
+- Include call-to-action in conclusions
+
+## Scripts
+
+- `apply_brand.py`: Automated brand formatting application
+- `validate_brand.py`: Brand compliance verification
+```
+
+## Key Takeaways
+
+This example demonstrates:
+
+1. **Standards enforcement pattern**: Detailed specifications for compliance
+2. **Reference materials**: Colors, fonts, layouts as on-demand resources
+3. **Multi-format support**: PowerPoint, Excel, PDF standards
+4. **Content + visual**: Both design and messaging guidelines
+5. **Validation scripts**: Automated brand compliance checking

package/packs/meta-pack/skills/gr.skill-developer/examples/financial-analysis.md

@@ -0,0 +1,85 @@
+# Financial Analysis Skill Example
+
+This is a complete example of a skill that calculates financial ratios and metrics.
+
+```yaml
+---
+name: analyzing-financial-statements
+description: This skill calculates key financial ratios and metrics from financial statement data for investment analysis
+---
+
+# Financial Ratio Calculator Skill
+
+This skill provides comprehensive financial ratio analysis for evaluating company performance, profitability, liquidity, and valuation.
+
+## Capabilities
+
+Calculate and interpret:
+- **Profitability Ratios**: ROE, ROA, Gross Margin, Operating Margin, Net Margin
+- **Liquidity Ratios**: Current Ratio, Quick Ratio, Cash Ratio
+- **Leverage Ratios**: Debt-to-Equity, Interest Coverage, Debt Service Coverage
+- **Efficiency Ratios**: Asset Turnover, Inventory Turnover, Receivables Turnover
+- **Valuation Ratios**: P/E, P/B, P/S, EV/EBITDA, PEG
+- **Per-Share Metrics**: EPS, Book Value per Share, Dividend per Share
+
+## How to Use
+
+1. **Input Data**: Provide financial statement data (income statement, balance sheet, cash flow)
+2. **Select Ratios**: Specify which ratios to calculate or use "all" for comprehensive analysis
+3. **Interpretation**: The skill will calculate ratios and provide industry-standard interpretations
+
+## Input Format
+
+Financial data can be provided as:
+- CSV with financial line items
+- JSON with structured financial statements
+- Text description of key financial figures
+- Excel files with financial statements
+
+## Output Format
+
+Results include:
+- Calculated ratios with values
+- Industry benchmark comparisons (when available)
+- Trend analysis (if multiple periods provided)
+- Interpretation and insights
+- Excel report with formatted results
+
+## Example Usage
+
+"Calculate key financial ratios for this company based on the attached financial statements"
+
+"What's the P/E ratio if the stock price is $50 and annual earnings are $2.50 per share?"
+
+"Analyze the liquidity position using the balance sheet data"
+
+## Scripts
+
+- `calculate_ratios.py`: Main calculation engine for all financial ratios
+- `interpret_ratios.py`: Provides interpretation and benchmarking
+
+## Best Practices
+
+1. Always validate data completeness before calculations
+2. Handle missing values appropriately (use industry averages or exclude)
+3. Consider industry context when interpreting ratios
+4. Include period comparisons for trend analysis
+5. Flag unusual or concerning ratios
+
+## Limitations
+
+- Requires accurate financial data
+- Industry benchmarks are general guidelines
+- Some ratios may not apply to all industries
+- Historical data doesn't guarantee future performance
+```
+
+## Key Takeaways
+
+This example demonstrates:
+
+1. **Clear domain focus**: Financial analysis and ratio calculation
+2. **Rich trigger keywords**: "financial ratios", "metrics", "financial statement", "investment analysis"
+3. **Structured sections**: Capabilities, input/output, examples, scripts
+4. **Bundled scripts**: Python files for calculations (code doesn't enter context)
+5. **Practical guidance**: Best practices and limitations

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

@@ -0,0 +1,410 @@
+# Skill Best Practices
+
+Comprehensive best practices for creating high-quality, discoverable, and maintainable skills.
+
+## Content Quality
+
+### Be Specific and Actionable
+
+**Good:**
+
+```markdown
+"Calculate ROE by dividing net income by shareholder equity"
+```
+
+**Bad:**
+
+```markdown
+"Calculate financial ratios appropriately"
+```
+
+**Why:** Specific instructions tell Claude exactly what to do. Vague guidance leads to inconsistent results.
+
+### Use Concrete Examples
+
+**Good:**
+
+```markdown
+"What's the P/E ratio if the stock price is $50 and EPS is $2.50?"
+```
+
+**Bad:**
+
+```markdown
+"Calculate P/E ratio"
+```
+
+**Why:** Concrete examples show users how to interact with the skill and demonstrate expected output.
+
+### Define Terminology
+
+**Good:**
+
+```markdown
+- **ROE (Return on Equity)**: Net Income ÷ Shareholder Equity
+  Measures how effectively a company uses shareholder capital
+```
+
+**Bad:**
+
+```markdown
+- ROE: A profitability ratio
+```
+
+**Why:** Clear definitions help both Claude and users understand domain-specific terms.
+
+## Organization
+
+### Clear Hierarchy
+
+Use consistent heading levels:
+
+- `##` for major sections (Capabilities, How to Use, Best Practices)
+- `###` for subsections (within major sections)
+- `####` sparingly for deep topics (only when necessary)
+
+### Logical Flow
+
+Organize content in this order:
+
+1. **Introduction** - What is this skill?
+2. **Capabilities** - What can it do?
+3. **How to Use** - Step-by-step instructions
+4. **Input/Output** - What goes in, what comes out
+5. **Examples** - Show concrete usage
+6. **Scripts** - Supporting automation (if applicable)
+7. **Best Practices** - How to use it well
+8. **Limitations** - Boundaries and constraints
+
+**Why:** This flow matches how users think: "What is it?" → "What does it do?" → "How do I use it?" → "What should I watch out for?"
+
+### Scannable Content
+
+Format for easy scanning:
+
+- **Bullet lists** for options, features, or categories
+- **Numbered lists** for sequential steps or workflows
+- **Bold** for key terms and important concepts
+- **Code blocks** for examples, formulas, or syntax
+- **Tables** for comparisons or structured data
+
+**Example:**
+
+```markdown
+## Capabilities
+
+Calculate these ratio categories:
+- **Profitability**: ROE, ROA, margins
+- **Liquidity**: Current ratio, quick ratio
+- **Leverage**: Debt-to-equity, coverage ratios
+```
+
+## Discoverability
+
+### Rich Descriptions with Keywords
+
+**Good:**
+
+```yaml
+description: "Python data science coding patterns and best practices. Use when writing Python code, analyzing data, creating visualizations, or working with pandas and numpy"
+```
+
+**Bad:**
+
+```yaml
+description: "Helps with Python programming"
+```
+
+**Why:** Rich descriptions with multiple keywords increase activation accuracy.
+
+### Multiple Trigger Points
+
+Include variety in your description:
+
+- **Synonyms:** "branding" AND "styling"
+- **File types:** "PowerPoint", "Excel", "PDF"
+- **Actions:** "creating", "formatting", "analyzing", "validating"
+- **Domain terms:** "financial ratios", "brand guidelines", "API patterns"
+- **Natural phrases:** How users actually ask questions
+
+**Example:**
+
+```yaml
+description: "This skill applies consistent corporate branding and styling to all generated documents including PowerPoint, Excel, and PDF files. Use when creating, formatting, or reviewing branded materials."
+# Covers: branding, styling, documents, specific file types, multiple action verbs
+```
+
+## Progressive Disclosure
+
+### Keep Core Instructions Concise
+
+**Main SKILL.md body:** Maximum 500 lines (excluding YAML frontmatter)
+
+- Essential instructions only
+- High-level workflow
+- Links to supporting files
+- Enforced by validation script
+
+**Total skill bundle:** Maximum 8MB (all files combined)
+
+- Includes SKILL.md + all supporting files + scripts
+- Enforced by validation script
+
+**Supporting files:** Loaded on-demand
+
+- Detailed specifications → `reference/`
+- Full examples → `examples/`
+- Templates → `templates/`
+- Scripts → `scripts/`
+- **Files don't consume context until accessed** - you can include dozens of reference files without penalty
+
+### When to Split Content
+
+**Keep in SKILL.md:**
+
+- Overview and purpose
+- Key capabilities
+- Basic usage steps
+- Simple examples
+- Links to detailed resources
+
+**Move to supporting files:**
+
+- Full skill examples (>50 lines)
+- Detailed API specifications
+- Complete templates
+- Extensive best practices guides
+- Industry benchmarks or lookup tables
+
+### Reference File Organization Standards
+
+**One Level Deep Linking:**
+
+All reference files must link directly from SKILL.md - do not nest references within other references. This ensures Claude can read any reference file directly without navigation.
+
+**Example (correct):**
+
+```markdown
+<!-- SKILL.md -->
+For API details, see [reference/api-specification.md](reference/api-specification.md).
+For error handling, see [reference/error-handling.md](reference/error-handling.md).
+```
+
+**Table of Contents for Long Files:**
+
+Reference files exceeding 100 lines must include a table of contents at the top. This ensures Claude can see the full scope even in partial reads.
+
+**Example:**
+
+```markdown
+# API Specification
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+- [Error Codes](#error-codes)
+
+## Authentication
+...
+```
+
+### Size Limit Guidelines
+
+**SKILL.md body: 500 lines maximum (enforced)**
+
+If approaching this limit:
+- Extract detailed sections to reference files
+- Move full examples to `examples/` directory
+- Keep only essential instructions in SKILL.md
+
+**Total skill bundle: 8MB maximum (enforced)**
+
+If approaching this limit:
+- Remove redundant content
+- Compress or remove large images
+- Split large reference files by topic
+- Use external resources for very large datasets
+
+**Reference files >100 lines: Add table of contents (warned if missing)**
+
+This is a strong recommendation but not enforced with blocking errors.
+
+**For comprehensive file organization guidance:** See [reference/file-organization.md](reference/file-organization.md)
+
+## Scripts and Automation
+
+### When to Bundle Scripts
+
+Add scripts for:
+
+- **Complex calculations** (financial ratios, statistical analysis)
+- **Formatting automation** (brand application, document generation)
+- **Data transformation** (parsing, conversion, validation)
+- **Validation** (compliance checking, quality assurance)
+
+### Script Documentation
+
+Always document scripts clearly:
+
+```markdown
+## Scripts
+
+- `calculate_ratios.py`: Main calculation engine for all financial ratios
+  - Input: Financial statement dict or CSV
+  - Output: Dict of calculated ratios with interpretations
+  - Usage: Called automatically when ratio calculation requested
+
+- `interpret_ratios.py`: Provides interpretation and benchmarking
+  - Input: Calculated ratios dict
+  - Output: Textual interpretation with industry comparisons
+  - Usage: Called after calculations for context
+```
+
+### Benefits of Scripts
+
+- **Context efficiency:** Script code never enters context, only output
+- **Reliability:** Deterministic operations (calculations, formatting)
+- **Maintainability:** Update logic without changing skill instructions
+
+## Testing and Validation
+
+### Test Activation
+
+1. **Positive tests:** Ask questions matching your keywords
+
+   ```text
+   "Calculate financial ratios for this company"  # Should activate
+   "Analyze the P/E ratio"                       # Should activate
+   ```
+
+2. **Negative tests:** Ask unrelated questions
+
+   ```text
+   "What's the weather today?"                   # Should NOT activate
+   "Write a Python function"                     # Should NOT activate (unless Python skill)
+   ```
+
+### Test Instructions
+
+1. Follow your own "How to Use" steps
+2. Verify examples work as described
+3. Check that outputs match "Output Format" section
+4. Ensure limitations are accurate
+
+### Quality Checklist
+
+Before finalizing:
+
+**YAML Frontmatter:**
+
+- [ ] Name is lowercase with hyphens, ≤64 chars
+- [ ] Name matches directory name
+- [ ] Description ≤1024 chars
+- [ ] Description includes WHAT and WHEN
+- [ ] No reserved words or XML tags
+
+**Content:**
+
+- [ ] Clear introduction
+- [ ] Specific, actionable instructions
+- [ ] Concrete examples
+- [ ] Defined terminology
+- [ ] Proper heading hierarchy
+
+**Supporting Files:**
+
+- [ ] Relative paths are correct
+- [ ] Files exist in expected locations
+- [ ] Scripts are documented
+- [ ] No broken links
+
+## Common Anti-Patterns
+
+### ❌ Don't: Overly Broad Scope
+
+```yaml
+# Too broad - won't activate reliably
+description: "Helps with programming tasks"
+```
+
+**Do:** Focus on specific domain
+
+```yaml
+description: "Python data science coding patterns for pandas and numpy. Use when analyzing data or creating visualizations"
+```
+
+### ❌ Don't: Missing Trigger Keywords
+
+```yaml
+description: "Contains financial information"
+```
+
+**Do:** Include action verbs and use cases
+
+```yaml
+description: "Calculates financial ratios and metrics from financial statement data for investment analysis"
+```
+
+### ❌ Don't: Vague Instructions
+
+```markdown
+## How to Use
+
+1. Provide data
+2. Get results
+```
+
+**Do:** Be specific
+
+```markdown
+## How to Use
+
+1. **Provide financial statements:** Upload income statement, balance sheet, or provide revenue/earnings figures
+2. **Specify ratios:** Request specific ratios (P/E, ROE) or "all" for comprehensive analysis
+3. **Review results:** Calculated ratios with industry benchmarks and trend analysis
+```
+
+### ❌ Don't: Embed Large Examples
+
+```markdown
+# SKILL.md (1000+ lines with full examples)
+```
+
+**Do:** Extract to separate files
+
+```markdown
+# SKILL.md (300 lines)
+See `examples/financial-analysis.md` for a complete example.
+```
+
+## Maintenance
+
+### Keep Skills Updated
+
+- Review quarterly for accuracy
+- Update examples as best practices evolve
+- Add new capabilities incrementally
+- Deprecate outdated information
+
+### Version Control
+
+Use git to track changes:
+
+```bash
+git commit -m "skill-developer: Add visualization examples"
+```
+
+### Gather Feedback
+
+Monitor skill effectiveness:
+
+- Does it activate when expected?
+- Are instructions clear to users?
+- Do examples work correctly?
+- Are there common questions not covered?
+
+## Resources
+
+- [Official Skills Documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [Anthropic Cookbooks - Custom Skills](https://github.com/anthropics/claude-cookbooks/tree/main/skills/custom_skills)