@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/create-agent-skills/references/best-practices.md

@@ -0,0 +1,404 @@
+# Skill Authoring Best Practices
+
+Source: [platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Your Skill shares the context window with everything else Claude needs to know.
+
+**Default assumption**: Claude is already very smart. Only add context Claude doesn't already have.
+
+Challenge each piece of information:
+- "Does Claude really need this explanation?"
+- "Can I assume Claude knows this?"
+- "Does this paragraph justify its token cost?"
+
+**Good example (concise, ~50 tokens):**
+```markdown
+## Extract PDF text
+
+Use pdfplumber for text extraction:
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+```
+
+**Bad example (too verbose, ~150 tokens):**
+```markdown
+## Extract PDF text
+
+PDF (Portable Document Format) files are a common file format that contains
+text, images, and other content. To extract text from a PDF, you'll need to
+use a library. There are many libraries available...
+```
+
+### Set Appropriate Degrees of Freedom
+
+Match specificity to task fragility and variability.
+
+**High freedom** (multiple valid approaches):
+```markdown
+## Code review process
+
+1. Analyze the code structure and organization
+2. Check for potential bugs or edge cases
+3. Suggest improvements for readability
+4. Verify adherence to project conventions
+```
+
+**Medium freedom** (preferred pattern with variation):
+```markdown
+## Generate report
+
+Use this template and customize as needed:
+
+```python
+def generate_report(data, format="markdown"):
+    # Process data
+    # Generate output in specified format
+```
+```
+
+**Low freedom** (fragile, exact sequence required):
+```markdown
+## Database migration
+
+Run exactly this script:
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+Do not modify the command or add flags.
+```
+
+### Test With All Models
+
+Skills act as additions to models. Test with Haiku, Sonnet, and Opus.
+
+- **Haiku**: Does the Skill provide enough guidance?
+- **Sonnet**: Is the Skill clear and efficient?
+- **Opus**: Does the Skill avoid over-explaining?
+
+## Naming Conventions
+
+Use **gerund form** (verb + -ing) for Skill names:
+
+**Good:**
+- `processing-pdfs`
+- `analyzing-spreadsheets`
+- `managing-databases`
+- `testing-code`
+- `writing-documentation`
+
+**Acceptable alternatives:**
+- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
+- Action-oriented: `process-pdfs`, `analyze-spreadsheets`
+
+**Avoid:**
+- Vague: `helper`, `utils`, `tools`
+- Generic: `documents`, `data`, `files`
+- Reserved: `anthropic-*`, `claude-*`
+
+## Writing Effective Descriptions
+
+**Always write in third person.** The description is injected into the system prompt.
+
+**Be specific and include key terms:**
+
+```yaml
+# PDF Processing skill
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+
+# Excel Analysis skill
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+
+# Git Commit Helper skill
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+**Avoid vague descriptions:**
+```yaml
+description: Helps with documents  # Too vague!
+description: Processes data       # Too generic!
+description: Does stuff with files # Useless!
+```
+
+## Progressive Disclosure Patterns
+
+### Pattern 1: High-level guide with references
+
+```markdown
+---
+name: pdf-processing
+description: Extracts text and tables from PDF files, fills forms, merges documents.
+---
+
+# PDF Processing
+
+## Quick start
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+## Advanced features
+
+**Form filling**: See [FORMS.md](FORMS.md)
+**API reference**: See [REFERENCE.md](REFERENCE.md)
+**Examples**: See [EXAMPLES.md](EXAMPLES.md)
+```
+
+### Pattern 2: Domain-specific organization
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+### Pattern 3: Conditional details
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+## Keep References One Level Deep
+
+Claude may partially read files when they're referenced from other referenced files.
+
+**Bad (too deep):**
+```markdown
+# SKILL.md
+See [advanced.md](advanced.md)...
+
+# advanced.md
+See [details.md](details.md)...
+
+# details.md
+Here's the actual information...
+```
+
+**Good (one level deep):**
+```markdown
+# SKILL.md
+
+**Basic usage**: [in SKILL.md]
+**Advanced features**: See [advanced.md](advanced.md)
+**API reference**: See [reference.md](reference.md)
+**Examples**: See [examples.md](examples.md)
+```
+
+## Workflows and Feedback Loops
+
+### Workflow with Checklist
+
+```markdown
+## Research synthesis workflow
+
+Copy this checklist:
+
+```
+- [ ] Step 1: Read all source documents
+- [ ] Step 2: Identify key themes
+- [ ] Step 3: Cross-reference claims
+- [ ] Step 4: Create structured summary
+- [ ] Step 5: Verify citations
+```
+
+**Step 1: Read all source documents**
+
+Review each document in `sources/`. Note main arguments.
+...
+```
+
+### Feedback Loop Pattern
+
+```markdown
+## Document editing process
+
+1. Make your edits to `word/document.xml`
+2. **Validate immediately**: `python scripts/validate.py unpacked_dir/`
+3. If validation fails:
+   - Review the error message
+   - Fix the issues
+   - Run validation again
+4. **Only proceed when validation passes**
+5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
+```
+
+## Common Patterns
+
+### Template Pattern
+
+```markdown
+## Report structure
+
+Use this template:
+
+```markdown
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+```
+
+### Examples Pattern
+
+```markdown
+## Commit message format
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly
+Output:
+```
+fix(reports): correct date formatting in timezone conversion
+```
+```
+
+### Conditional Workflow Pattern
+
+```markdown
+## Document modification
+
+1. Determine the modification type:
+
+   **Creating new content?** -> Follow "Creation workflow"
+   **Editing existing?** -> Follow "Editing workflow"
+
+2. Creation workflow:
+   - Use docx-js library
+   - Build document from scratch
+
+3. Editing workflow:
+   - Unpack existing document
+   - Modify XML directly
+   - Validate after each change
+```
+
+## Content Guidelines
+
+### Avoid Time-Sensitive Information
+
+**Bad:**
+```markdown
+If you're doing this before August 2025, use the old API.
+```
+
+**Good:**
+```markdown
+## Current method
+
+Use the v2 API endpoint: `api.example.com/v2/messages`
+
+## Old patterns
+
+<details>
+<summary>Legacy v1 API (deprecated 2025-08)</summary>
+The v1 API used: `api.example.com/v1/messages`
+</details>
+```
+
+### Use Consistent Terminology
+
+**Good - Consistent:**
+- Always "API endpoint"
+- Always "field"
+- Always "extract"
+
+**Bad - Inconsistent:**
+- Mix "API endpoint", "URL", "API route", "path"
+- Mix "field", "box", "element", "control"
+
+## Anti-Patterns to Avoid
+
+### Windows-Style Paths
+
+- **Good**: `scripts/helper.py`, `reference/guide.md`
+- **Avoid**: `scripts\helper.py`, `reference\guide.md`
+
+### Too Many Options
+
+**Bad:**
+```markdown
+You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...
+```
+
+**Good:**
+```markdown
+Use pdfplumber for text extraction:
+```python
+import pdfplumber
+```
+
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
+```
+
+## Checklist for Effective Skills
+
+### Core Quality
+- [ ] Description is specific and includes key terms
+- [ ] Description includes both what and when
+- [ ] SKILL.md body under 500 lines
+- [ ] Additional details in separate files
+- [ ] No time-sensitive information
+- [ ] Consistent terminology
+- [ ] Examples are concrete
+- [ ] References one level deep
+- [ ] Progressive disclosure used appropriately
+- [ ] Workflows have clear steps
+
+### Code and Scripts
+- [ ] Scripts handle errors explicitly
+- [ ] No "voodoo constants" (all values justified)
+- [ ] Required packages listed
+- [ ] Scripts have clear documentation
+- [ ] No Windows-style paths
+- [ ] Validation steps for critical operations
+- [ ] Feedback loops for quality-critical tasks
+
+### Testing
+- [ ] At least three test scenarios
+- [ ] Tested with Haiku, Sonnet, and Opus
+- [ ] Tested with real usage scenarios
+- [ ] Team feedback incorporated

package/plugins/lavra/skills/create-agent-skills/references/common-patterns.md

@@ -0,0 +1,121 @@
+<overview>
+This reference documents common patterns for skill authoring, including templates, examples, terminology consistency, and anti-patterns. All patterns use pure XML structure.
+</overview>
+
+<template_pattern>
+<description>
+Provide templates for output format. Match the level of strictness to your needs.
+</description>
+
+<strict_requirements>
+Use when output format must be exact and consistent:
+
+```xml
+<report_structure>
+ALWAYS use this exact template structure:
+
+```markdown
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+</report_structure>
+```
+
+**When to use**: Compliance reports, standardized formats, automated processing
+</strict_requirements>
+
+<flexible_guidance>
+Use when Claude should adapt the format based on context:
+
+```xml
+<report_structure>
+Here is a sensible default format, but use your best judgment:
+
+```markdown
+# [Analysis Title]
+
+## Executive summary
+[Overview]
+
+## Key findings
+[Adapt sections based on what you discover]
+
+## Recommendations
+[Tailor to the specific context]
+```
+
+Adjust sections as needed for the specific analysis type.
+</report_structure>
+```
+
+**When to use**: Exploratory analysis, context-dependent formatting, creative tasks
+</flexible_guidance>
+</template_pattern>
+
+<examples_pattern>
+<description>
+For skills where output quality depends on seeing examples, provide input/output pairs.
+</description>
+
+<when_to_use>
+- Output format has nuances that text explanations can't capture
+- Pattern recognition is easier than rule following
+- Examples demonstrate edge cases
+- Multi-shot learning improves quality
+</when_to_use>
+</examples_pattern>
+
+<consistent_terminology>
+<principle>
+Choose one term and use it throughout the skill. Inconsistent terminology confuses Claude and reduces execution quality.
+</principle>
+
+<implementation>
+1. Choose terminology early in skill development
+2. Document key terms in `<objective>` or `<context>`
+3. Use find/replace to enforce consistency
+4. Review reference files for consistent usage
+</implementation>
+</consistent_terminology>
+
+<provide_default_with_escape_hatch>
+<principle>
+Provide a default approach with an escape hatch for special cases, not a list of alternatives. Too many options paralyze decision-making.
+</principle>
+
+<implementation>
+1. Recommend ONE default approach
+2. Explain when to use the default (implied: most of the time)
+3. Add ONE escape hatch for edge cases
+4. Link to advanced reference if multiple alternatives truly needed
+</implementation>
+</provide_default_with_escape_hatch>
+
+<progressive_disclosure_pattern>
+<description>
+Keep SKILL.md concise by linking to detailed reference files. Claude loads reference files only when needed.
+</description>
+</progressive_disclosure_pattern>
+
+<validation_pattern>
+<description>
+For skills with validation steps, make validation scripts verbose and specific.
+</description>
+</validation_pattern>
+
+<checklist_pattern>
+<description>
+For complex multi-step workflows, provide a checklist Claude can copy and track progress.
+</description>
+</checklist_pattern>

package/plugins/lavra/skills/create-agent-skills/references/core-principles.md

@@ -0,0 +1,103 @@
+<overview>
+Core principles guide skill authoring decisions. These principles ensure skills are efficient, effective, and maintainable across different models and use cases.
+</overview>
+
+<conciseness_principle>
+<description>
+The context window is shared. Your skill shares it with the system prompt, conversation history, other skills' metadata, and the actual request.
+</description>
+
+<guidance>
+Only add context Claude doesn't already have. Challenge each piece of information:
+- "Does Claude really need this explanation?"
+- "Can I assume Claude knows this?"
+- "Does this paragraph justify its token cost?"
+
+Assume Claude is smart. Don't explain obvious concepts.
+</guidance>
+</conciseness_principle>
+
+<degrees_of_freedom_principle>
+<description>
+Match the level of specificity to the task's fragility and variability. Give Claude more freedom for creative tasks, less freedom for fragile operations.
+</description>
+
+<matching_specificity>
+The key is matching specificity to fragility:
+
+- **Fragile operations** (database migrations, payment processing, security): Low freedom, exact instructions
+- **Standard operations** (API calls, file processing, data transformation): Medium freedom, preferred pattern with flexibility
+- **Creative operations** (code review, content generation, analysis): High freedom, heuristics and principles
+
+Mismatched specificity causes problems:
+- Too much freedom on fragile tasks -> errors and failures
+- Too little freedom on creative tasks -> rigid, suboptimal outputs
+</matching_specificity>
+</degrees_of_freedom_principle>
+
+<model_testing_principle>
+<description>
+Skills act as additions to models, so effectiveness depends on the underlying model. What works for Opus might need more detail for Haiku.
+</description>
+
+<balancing_across_models>
+Aim for instructions that work well across all target models. Find the balance that serves your target audience.
+
+See [iteration-and-testing.md](iteration-and-testing.md) for model testing examples.
+</balancing_across_models>
+</model_testing_principle>
+
+<progressive_disclosure_principle>
+<description>
+SKILL.md serves as an overview. Reference files contain details. Claude loads reference files only when needed.
+</description>
+
+<implementation>
+- Keep SKILL.md under 500 lines
+- Split detailed content into reference files
+- Keep references one level deep from SKILL.md
+- Link to references from relevant sections
+- Use descriptive reference file names
+
+See [skill-structure.md](skill-structure.md) for progressive disclosure patterns.
+</implementation>
+</progressive_disclosure_principle>
+
+<validation_principle>
+<description>
+Validation scripts are force multipliers. They catch errors that Claude might miss and provide actionable feedback.
+</description>
+
+<characteristics>
+Good validation scripts:
+- Provide verbose, specific error messages
+- Show available valid options when something is invalid
+- Pinpoint exact location of problems
+- Suggest actionable fixes
+- Are deterministic and reliable
+
+See [workflows-and-validation.md](workflows-and-validation.md) for validation patterns.
+</characteristics>
+</validation_principle>
+
+<principle_summary>
+<conciseness>
+Only add context Claude doesn't have. Assume Claude is smart. Challenge every piece of content.
+</conciseness>
+
+<degrees_of_freedom>
+Match specificity to fragility. High freedom for creative tasks, low freedom for fragile operations, medium for standard work.
+</degrees_of_freedom>
+
+<model_testing>
+Test with all target models. Balance detail level to work across Haiku, Sonnet, and Opus.
+</model_testing>
+
+<progressive_disclosure>
+Keep SKILL.md concise. Split details into reference files. Load reference files only when needed.
+</progressive_disclosure>
+
+<validation>
+Make validation scripts verbose and specific. Catch errors early with actionable feedback.
+</validation>
+</principle_summary>

package/plugins/lavra/skills/create-agent-skills/references/executable-code.md

@@ -0,0 +1,92 @@
+<when_to_use_scripts>
+Even if Claude could write a script, pre-made scripts offer advantages:
+- More reliable than generated code
+- Save tokens (no need to include code in context)
+- Save time (no code generation required)
+- Ensure consistency across uses
+
+<execution_vs_reference>
+Make clear whether Claude should:
+- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
+- **Read it as reference** (for complex logic): "See `analyze_form.py` for the extraction algorithm"
+
+For most utility scripts, execution is preferred.
+</execution_vs_reference>
+
+<how_scripts_work>
+When Claude executes a script via bash:
+1. Script code never enters context window
+2. Only script output consumes tokens
+3. Far more efficient than having Claude generate equivalent code
+</how_scripts_work>
+</when_to_use_scripts>
+
+<file_organization>
+<scripts_directory>
+**Best practice**: Place all executable scripts in a `scripts/` subdirectory within the skill folder.
+
+```
+skill-name/
+├── SKILL.md
+├── scripts/
+│   ├── main_utility.py
+│   ├── helper_script.py
+│   └── validator.py
+└── references/
+    └── api-docs.md
+```
+
+**Benefits**:
+- Keeps skill root clean and organized
+- Clear separation between documentation and executable code
+- Consistent pattern across all skills
+- Easy to reference: `python scripts/script_name.py`
+
+**Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
+
+```bash
+python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+```
+</scripts_directory>
+</file_organization>
+
+<solve_dont_punt>
+Handle error conditions rather than punting to Claude.
+
+<configuration_values>
+Document configuration parameters to avoid "voodoo constants":
+
+```python
+# HTTP requests typically complete within 30 seconds
+REQUEST_TIMEOUT = 30
+
+# Three retries balances reliability vs speed
+MAX_RETRIES = 3
+```
+</configuration_values>
+</solve_dont_punt>
+
+<package_dependencies>
+<runtime_constraints>
+Skills run in code execution environment with platform-specific limitations:
+- **claude.ai**: Can install packages from npm and PyPI
+- **Anthropic API**: No network access and no runtime package installation
+</runtime_constraints>
+
+<guidance>
+List required packages in your SKILL.md and verify they're available.
+</guidance>
+</package_dependencies>
+
+<mcp_tool_references>
+If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
+
+<format>ServerName:tool_name</format>
+
+<examples>
+- Use the BigQuery:bigquery_schema tool to retrieve table schemas.
+- Use the GitHub:create_issue tool to create issues.
+</examples>
+
+Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
+</mcp_tool_references>