@grimoire-cc/cli 0.6.3 → 0.7.0

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

@@ -0,0 +1,321 @@
+---
+name: grimoire:skill-developer
+description: Create and maintain custom skills for Claude Code following official Anthropic patterns. Use when creating new skills, updating existing skills, or organizing skill documentation.
+user_invocable: true
+disable-model-invocation: true
+---
+
+# Skill Developer
+
+This meta-skill teaches you how to create effective custom skills for Claude Code, following official Anthropic documentation and the progressive disclosure architecture.
+
+## What Are Skills?
+
+Skills are specialized knowledge modules that Claude loads when working on specific tasks. They provide:
+
+- **Instruction sets:** Domain-specific guidance and patterns
+- **Automatic activation:** Based on description keywords
+- **Progressive disclosure:** Supporting files loaded on-demand
+- **Context efficiency:** Only relevant content in context window
+
+Skills live in `.claude/skills/{skill-name}/SKILL.md` with optional supporting files.
+
+## When to Create a Skill
+
+Create a skill when you need:
+
+- **Consistent patterns** across multiple tasks (code style, financial analysis)
+- **Domain expertise** captured in one place (industry standards, calculations)
+- **Reference material** easily accessible (formulas, specifications)
+- **Specialized workflows** for specific domains (multi-step processes)
+
+**Don't create a skill when:**
+
+- You need task execution (create an agent instead)
+- It's a one-time task or simple query
+- The domain is too broad or unfocused
+
+## YAML Frontmatter Requirements
+
+Every SKILL.md must start with YAML frontmatter:
+
+```yaml
+---
+name: your-skill-name
+description: "What this skill does and when to use it with trigger keywords"
+---
+```
+
+### Quick Requirements
+
+**`name` field:**
+
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- Must match directory name exactly
+- Cannot contain "anthropic" or "claude"
+
+**`description` field:**
+
+- Maximum 1024 characters
+- Must include WHAT the skill does
+- Must include WHEN to use it (trigger keywords)
+
+**For detailed specifications:** See [reference/yaml-spec.md](reference/yaml-spec.md)
+
+## Official Size and Structure Requirements
+
+Every skill must comply with these official Anthropic requirements:
+
+- **SKILL.md body:** Maximum 500 lines (excluding YAML frontmatter)
+- **Total bundle size:** Maximum 8MB (all files combined)
+- **Skills per request:** Maximum 8 skills can be loaded
+- **Reference files >100 lines:** Must include table of contents at top
+- **Reference file linking:** Keep all references one level deep from SKILL.md
+
+These limits are enforced by the validation script and ensure optimal performance.
+
+**For detailed file organization guidance:** See [reference/file-organization.md](reference/file-organization.md)
+
+## File Structure Options
+
+**Minimal (single file):**
+
+```text
+.claude/skills/skill-name/
+└── SKILL.md
+```
+
+**Complete (progressive disclosure):**
+
+```text
+.claude/skills/skill-name/
+├── SKILL.md              # Core instructions (<500 lines)
+├── templates/            # Skill templates
+├── examples/             # Full skill examples
+├── reference/            # Detailed specifications
+└── scripts/              # Automation (Python, Bash)
+```
+
+Claude loads supporting files only when relevant - **files don't consume context until accessed**. This means you can include dozens of reference files without penalty, as they're only loaded when Claude needs them.
+
+## Content Structure Pattern
+
+Follow this structure for SKILL.md:
+
+1. **YAML Frontmatter** - Required (name, description)
+2. **Title & Introduction** - What this skill does
+3. **Capabilities** - What it can help with
+4. **How to Use** - Step-by-step instructions
+5. **Input/Output Format** - What goes in, what comes out
+6. **Example Usage** - Concrete user queries
+7. **Scripts** - Supporting automation (optional)
+8. **Best Practices** - How to use well
+9. **Limitations** - Boundaries and constraints
+
+**Keep SKILL.md body under 500 lines.** Move detailed content to supporting files to stay within limits.
+
+## Skill Creation Workflow
+
+### 1. Define Scope
+
+Answer before writing:
+
+- What domain or task?
+- What specific capabilities?
+- What triggers activation (keywords)?
+- What input does it need?
+- What output does it produce?
+
+### 2. Choose Template
+
+Use `scripts/create-skill.sh` to scaffold from a template:
+
+```bash
+# Basic skill (single-purpose)
+./scripts/create-skill.sh my-skill --template basic
+
+# Domain skill (specialized expertise)
+./scripts/create-skill.sh financial-analysis --template domain
+```
+
+**Templates:** See [templates/](templates/) directory
+
+### 3. Write Content
+
+Follow the content structure pattern:
+
+- Be specific and actionable
+- Use concrete examples
+- Define terminology
+- Keep it concise
+
+**Best practices:** See [reference/best-practices.md](reference/best-practices.md)
+
+### 4. Add Supporting Materials
+
+**When to add scripts:**
+
+- Complex calculations
+- Formatting automation
+- Data transformation
+- Validation checks
+
+**Progressive disclosure:**
+
+- Detailed specs → `reference/`
+- Full examples → `examples/`
+- Templates → `templates/`
+- Scripts → `scripts/`
+
+### 5. Validate
+
+```bash
+./scripts/validate-skill.py .claude/skills/my-skill/SKILL.md
+```
+
+Checks:
+
+- YAML frontmatter format
+- Name requirements
+- Description requirements
+- Directory name matching
+
+### 6. Test Activation
+
+Ask questions with your description keywords:
+
+- Should activate for relevant queries
+- Should NOT activate for unrelated queries
+
+### 7. Refine
+
+Adjust based on:
+
+- Does it activate when expected?
+- Are instructions clear?
+- Do examples work?
+
+## Examples
+
+**Complete skill examples:**
+
+- [examples/financial-analysis.md](examples/financial-analysis.md) - Financial ratio calculator
+- [examples/brand-guidelines.md](examples/brand-guidelines.md) - Corporate branding standards
+
+**Common patterns:**
+
+- [reference/patterns.md](reference/patterns.md) - Structured data, standards enforcement, workflows
+
+## Quick Start
+
+Create a new skill in 5 steps:
+
+**1. Use scaffolding script:**
+
+```bash
+cd .claude/skills/skill-developer/scripts
+./create-skill.sh my-new-skill
+```
+
+**2. Edit the generated SKILL.md:**
+
+- Add capabilities
+- Write "How to Use" instructions
+- Include example usage
+- Add best practices and limitations
+
+**3. Validate:**
+
+```bash
+./validate-skill.py ../my-new-skill/SKILL.md
+```
+
+**4. Test:**
+Ask Claude questions matching your keywords
+
+**5. Refine:**
+Adjust description and content based on activation accuracy
+
+## Automation Scripts
+
+**Create new skill:**
+
+```bash
+scripts/create-skill.sh <skill-name> [--template basic|domain]
+```
+
+Scaffolds directory structure and SKILL.md from template
+
+**Validate skill:**
+
+```bash
+scripts/validate-skill.py <path-to-SKILL.md>
+```
+
+Validates YAML frontmatter and requirements
+
+## Best Practices Summary
+
+**Discoverability:**
+
+- Rich descriptions with action verbs
+- Include domain terms and use cases
+- Multiple trigger keywords
+
+**Content Quality:**
+
+- Specific, actionable instructions
+- Concrete examples
+- Defined terminology
+
+**Organization:**
+
+- Clear heading hierarchy
+- Logical flow (what → how → examples → practices)
+- Scannable formatting (bullets, bold, code blocks)
+
+**Progressive Disclosure:**
+
+- Keep SKILL.md body <500 lines, total bundle <8MB
+- Move detailed content to supporting files
+- Files don't consume context until accessed
+- Scripts execute without entering context
+
+**For comprehensive guidelines:** See [reference/best-practices.md](reference/best-practices.md)
+
+## Common Patterns
+
+Skills typically follow one of these patterns:
+
+- **Structured Data Processing** - Analysis, calculations, transformations
+- **Standards Enforcement** - Branding, style guides, compliance
+- **Multi-Step Workflows** - Guided processes with phases
+- **Reference and Lookup** - Quick access to specifications
+
+**Pattern details:** See [reference/patterns.md](reference/patterns.md)
+
+## Resources
+
+### Official Documentation
+
+- [Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+### Official Examples
+
+- [Claude Cookbooks - Custom Skills](https://github.com/anthropics/claude-cookbooks/tree/main/skills/custom_skills)
+
+### This Skill's Resources
+
+- [templates/](templates/) - Basic and domain-specific templates
+- [examples/](examples/) - Complete skill examples
+- [reference/](reference/) - Detailed specifications and best practices
+- [scripts/](scripts/) - Automation tools
+
+## Limitations
+
+- Skills don't execute tasks (they provide guidance to Claude)
+- Custom skills don't sync across Claude surfaces (Code, API, claude.ai)
+- Activation depends on keyword matching in description
+- Skills load at startup (Level 1 metadata ~100 tokens per skill)

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