@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/create-agent-skills/references/skill-structure.md

@@ -0,0 +1,215 @@
+<overview>
+Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
+</overview>
+
+<xml_structure_requirements>
+<critical_rule>
+**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
+</critical_rule>
+
+<required_tags>
+Every skill MUST have these three tags:
+
+- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
+- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
+- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
+</required_tags>
+
+<conditional_tags>
+Add based on skill complexity and domain requirements:
+
+- **`<context>`** - Background/situational information
+- **`<workflow>` or `<process>`** - Step-by-step procedures
+- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
+- **`<validation>`** - How to verify outputs
+- **`<examples>`** - Multi-shot learning
+- **`<anti_patterns>`** - Common mistakes to avoid
+- **`<security_checklist>`** - Non-negotiable security patterns
+- **`<testing>`** - Testing workflows
+- **`<common_patterns>`** - Code examples and recipes
+- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
+
+See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
+</conditional_tags>
+
+<tag_selection_intelligence>
+**Simple skills** (single domain, straightforward):
+- Required tags only
+- Example: Text extraction, file format conversion
+
+**Medium skills** (multiple patterns, some complexity):
+- Required tags + workflow/examples as needed
+- Example: Document processing with steps, API integration
+
+**Complex skills** (multiple domains, security, APIs):
+- Required tags + conditional tags as appropriate
+- Example: Payment processing, authentication systems, multi-step workflows
+</tag_selection_intelligence>
+
+<xml_nesting>
+Properly nest XML tags for hierarchical content:
+
+```xml
+<examples>
+<example number="1">
+<input>User input</input>
+<output>Expected output</output>
+</example>
+</examples>
+```
+
+Always close tags:
+```xml
+<objective>
+Content here
+</objective>
+```
+</xml_nesting>
+
+<tag_naming_conventions>
+Use descriptive, semantic names:
+- `<workflow>` not `<steps>`
+- `<success_criteria>` not `<done>`
+- `<anti_patterns>` not `<dont_do>`
+
+Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
+</tag_naming_conventions>
+</xml_structure_requirements>
+
+<yaml_requirements>
+<required_fields>
+```yaml
+---
+name: skill-name-here
+description: What it does and when to use it (third person, specific triggers)
+---
+```
+</required_fields>
+
+<name_field>
+**Validation rules**:
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- No XML tags
+- No reserved words: "anthropic", "claude"
+- Must match directory name exactly
+
+**Examples**:
+- process-pdfs
+- manage-facebook-ads
+- setup-stripe-payments
+</name_field>
+
+<description_field>
+**Validation rules**:
+- Non-empty, maximum 1024 characters
+- No XML tags
+- Third person (never first or second person)
+- Include what it does AND when to use it
+
+**Critical rule**: Always write in third person.
+
+**Structure**: Include both capabilities and triggers.
+
+**Effective examples**:
+```yaml
+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.
+```
+</description_field>
+</yaml_requirements>
+
+<naming_conventions>
+Use **verb-noun convention** for skill names:
+
+<pattern name="create">
+Building/authoring tools
+
+Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
+</pattern>
+
+<pattern name="manage">
+Managing external services or resources
+
+Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
+</pattern>
+
+<pattern name="setup">
+Configuration/integration tasks
+
+Examples: `setup-stripe-payments`, `setup-meta-tracking`
+</pattern>
+
+<pattern name="generate">
+Generation tasks
+
+Examples: `generate-ai-images`
+</pattern>
+
+<avoid_patterns>
+- Vague: `helper`, `utils`, `tools`
+- Generic: `documents`, `data`, `files`
+- Reserved words: `anthropic-helper`, `claude-tools`
+- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
+</avoid_patterns>
+</naming_conventions>
+
+<progressive_disclosure>
+<principle>
+SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
+</principle>
+
+<practical_guidance>
+- Keep SKILL.md body under 500 lines
+- Split content into separate files when approaching this limit
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+</practical_guidance>
+
+<critical_rules>
+**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md -> advanced.md -> details.md) as Claude may only partially read deeply nested files.
+
+**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
+
+**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
+</critical_rules>
+</progressive_disclosure>
+
+<file_organization>
+<filesystem_navigation>
+Claude navigates your skill directory using bash commands:
+
+- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
+- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
+- Organize by domain: `reference/finance.md`, `reference/sales.md`
+</filesystem_navigation>
+
+<directory_structure>
+Typical skill structure:
+
+```
+skill-name/
+├── SKILL.md (main entry point, pure XML structure)
+├── references/ (optional, for progressive disclosure)
+│   ├── guide-1.md (pure XML structure)
+│   ├── guide-2.md (pure XML structure)
+│   └── examples.md (pure XML structure)
+└── scripts/ (optional, for utility scripts)
+    ├── validate.py
+    └── process.py
+```
+</directory_structure>
+</file_organization>
+
+<validation_checklist>
+Before finalizing a skill, verify:
+
+- YAML frontmatter valid (name matches directory, description in third person)
+- No markdown headings in body (pure XML structure)
+- Required tags present: objective, quick_start, success_criteria
+- Conditional tags appropriate for complexity level
+- All XML tags properly closed
+- Progressive disclosure applied (SKILL.md < 500 lines)
+- Reference files use pure XML structure
+- File paths use forward slashes
+- Descriptive file names
+</validation_checklist>

package/plugins/lavra/skills/create-agent-skills/references/using-scripts.md

@@ -0,0 +1,113 @@
+# Using Scripts in Skills
+
+<purpose>
+Scripts are executable code that Claude runs as-is rather than regenerating each time. They ensure reliable, error-free execution of repeated operations.
+</purpose>
+
+<when_to_use>
+Use scripts when:
+- The same code runs across multiple skill invocations
+- Operations are error-prone when rewritten from scratch
+- Complex shell commands or API interactions are involved
+- Consistency matters more than flexibility
+
+Common script types:
+- **Deployment** - Deploy to Vercel, publish packages, push releases
+- **Setup** - Initialize projects, install dependencies, configure environments
+- **API calls** - Authenticated requests, webhook handlers, data fetches
+- **Data processing** - Transform files, batch operations, migrations
+- **Build processes** - Compile, bundle, test runners
+</when_to_use>
+
+<script_structure>
+Scripts live in `scripts/` within the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── workflows/
+├── references/
+├── templates/
+└── scripts/
+    ├── deploy.sh
+    ├── setup.py
+    └── fetch-data.ts
+```
+
+A well-structured script includes:
+1. Clear purpose comment at top
+2. Input validation
+3. Error handling
+4. Idempotent operations where possible
+5. Clear output/feedback
+</script_structure>
+
+<script_example>
+```bash
+#!/bin/bash
+# deploy.sh - Deploy project to Vercel
+# Usage: ./deploy.sh [environment]
+# Environments: preview (default), production
+
+set -euo pipefail
+
+ENVIRONMENT="${1:-preview}"
+
+# Validate environment
+if [[ "$ENVIRONMENT" != "preview" && "$ENVIRONMENT" != "production" ]]; then
+    echo "Error: Environment must be 'preview' or 'production'"
+    exit 1
+fi
+
+echo "Deploying to $ENVIRONMENT..."
+
+if [[ "$ENVIRONMENT" == "production" ]]; then
+    vercel --prod
+else
+    vercel
+fi
+
+echo "Deployment complete."
+```
+</script_example>
+
+<workflow_integration>
+Workflows reference scripts like this:
+
+```xml
+<process>
+## Step 5: Deploy
+
+1. Ensure all tests pass
+2. Run `scripts/deploy.sh production`
+3. Verify deployment succeeded
+4. Update user with deployment URL
+</process>
+```
+
+The workflow tells Claude WHEN to run the script. The script handles HOW the operation executes.
+</workflow_integration>
+
+<best_practices>
+**Do:**
+- Make scripts idempotent (safe to run multiple times)
+- Include clear usage comments
+- Validate inputs before executing
+- Provide meaningful error messages
+- Use `set -euo pipefail` in bash scripts
+
+**Don't:**
+- Hardcode secrets or credentials (use environment variables)
+- Create scripts for one-off operations
+- Skip error handling
+- Make scripts do too many unrelated things
+- Forget to make scripts executable (`chmod +x`)
+</best_practices>
+
+<security_considerations>
+- Never embed API keys, tokens, or secrets in scripts
+- Use environment variables for sensitive configuration
+- Validate and sanitize any user-provided inputs
+- Be cautious with scripts that delete or modify data
+- Consider adding `--dry-run` options for destructive operations
+</security_considerations>

package/plugins/lavra/skills/create-agent-skills/references/using-templates.md

@@ -0,0 +1,112 @@
+# Using Templates in Skills
+
+<purpose>
+Templates are reusable output structures that Claude copies and fills in. They ensure consistent, high-quality outputs without regenerating structure each time.
+</purpose>
+
+<when_to_use>
+Use templates when:
+- Output should have consistent structure across invocations
+- The structure matters more than creative generation
+- Filling placeholders is more reliable than blank-page generation
+- Users expect predictable, professional-looking outputs
+
+Common template types:
+- **Plans** - Project plans, implementation plans, migration plans
+- **Specifications** - Technical specs, feature specs, API specs
+- **Documents** - Reports, proposals, summaries
+- **Configurations** - Config files, settings, environment setups
+- **Scaffolds** - File structures, boilerplate code
+</when_to_use>
+
+<template_structure>
+Templates live in `templates/` within the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── workflows/
+├── references/
+└── templates/
+    ├── plan-template.md
+    ├── spec-template.md
+    └── report-template.md
+```
+
+A template file contains:
+1. Clear section markers
+2. Placeholder indicators (use `{{placeholder}}` or `[PLACEHOLDER]`)
+3. Inline guidance for what goes where
+4. Example content where helpful
+</template_structure>
+
+<template_example>
+```markdown
+# {{PROJECT_NAME}} Implementation Plan
+
+## Overview
+{{1-2 sentence summary of what this plan covers}}
+
+## Goals
+- {{Primary goal}}
+- {{Secondary goals...}}
+
+## Scope
+**In scope:**
+- {{What's included}}
+
+**Out of scope:**
+- {{What's explicitly excluded}}
+
+## Phases
+
+### Phase 1: {{Phase name}}
+**Duration:** {{Estimated duration}}
+**Deliverables:**
+- {{Deliverable 1}}
+- {{Deliverable 2}}
+
+### Phase 2: {{Phase name}}
+...
+
+## Success Criteria
+- [ ] {{Measurable criterion 1}}
+- [ ] {{Measurable criterion 2}}
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {{Risk}} | {{H/M/L}} | {{H/M/L}} | {{Strategy}} |
+```
+</template_example>
+
+<workflow_integration>
+Workflows reference templates like this:
+
+```xml
+<process>
+## Step 3: Generate Plan
+
+1. Read `templates/plan-template.md`
+2. Copy the template structure
+3. Fill each placeholder based on gathered requirements
+4. Review for completeness
+</process>
+```
+
+The workflow tells Claude WHEN to use the template. The template provides WHAT structure to produce.
+</workflow_integration>
+
+<best_practices>
+**Do:**
+- Keep templates focused on structure, not content
+- Use clear placeholder syntax consistently
+- Include brief inline guidance where sections might be ambiguous
+- Make templates complete but minimal
+
+**Don't:**
+- Put excessive example content that might be copied verbatim
+- Create templates for outputs that genuinely need creative generation
+- Over-constrain with too many required sections
+- Forget to update templates when requirements change
+</best_practices>

package/plugins/lavra/skills/create-agent-skills/references/workflows-and-validation.md

@@ -0,0 +1,122 @@
+<overview>
+This reference covers patterns for complex workflows, validation loops, and feedback cycles in skill authoring. All patterns use pure XML structure.
+</overview>
+
+<complex_workflows>
+<principle>
+Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist.
+</principle>
+
+<when_to_use>
+Use checklist pattern when:
+- Workflow has 5+ sequential steps
+- Steps must be completed in order
+- Progress tracking helps prevent errors
+- Easy resumption after interruption is valuable
+</when_to_use>
+</complex_workflows>
+
+<feedback_loops>
+<validate_fix_repeat_pattern>
+<principle>
+Run validator -> fix errors -> repeat. This pattern greatly improves output quality.
+</principle>
+
+<why_it_works>
+- Catches errors early before changes are applied
+- Machine-verifiable with objective verification
+- Plan can be iterated without touching originals
+- Reduces total iteration cycles
+</why_it_works>
+</validate_fix_repeat_pattern>
+
+<plan_validate_execute_pattern>
+<principle>
+When Claude performs complex, open-ended tasks, create a plan in a structured format, validate it, then execute.
+
+Workflow: analyze -> **create plan file** -> **validate plan** -> execute -> verify
+</principle>
+
+<when_to_use>
+Use plan-validate-execute when:
+- Operations are complex and error-prone
+- Changes are irreversible or difficult to undo
+- Planning can be validated independently
+- Catching errors early saves significant time
+</when_to_use>
+</plan_validate_execute_pattern>
+</feedback_loops>
+
+<conditional_workflows>
+<principle>
+Guide Claude through decision points with clear branching logic.
+</principle>
+
+<when_to_use>
+Use conditional workflows when:
+- Different task types require different approaches
+- Decision points are clear and well-defined
+- Workflows are mutually exclusive
+- Guiding Claude to correct path improves outcomes
+</when_to_use>
+</conditional_workflows>
+
+<validation_scripts>
+<principles>
+Validation scripts are force multipliers. They catch errors that Claude might miss and provide actionable feedback for fixing issues.
+</principles>
+
+<characteristics_of_good_validation>
+<verbose_errors>
+**Good**: "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"
+**Bad**: "Invalid field"
+</verbose_errors>
+
+<specific_feedback>
+**Good**: "Line 47: Expected closing tag `</paragraph>` but found `</section>`"
+**Bad**: "XML syntax error"
+</specific_feedback>
+
+<actionable_suggestions>
+**Good**: "Required field 'customer_name' is missing. Add: {\"customer_name\": \"value\"}"
+**Bad**: "Missing required field"
+</actionable_suggestions>
+</characteristics_of_good_validation>
+
+<benefits>
+- Catches errors before they propagate
+- Reduces iteration cycles
+- Provides learning feedback
+- Makes debugging deterministic
+- Enables confident execution
+</benefits>
+</validation_scripts>
+
+<checkpoint_pattern>
+<principle>
+For long workflows, add checkpoints where Claude can pause and verify progress before continuing.
+</principle>
+
+<benefits>
+- Prevents cascading errors
+- Easier to diagnose issues
+- Clear progress indicators
+- Natural pause points for review
+- Reduces wasted work from early errors
+</benefits>
+</checkpoint_pattern>
+
+<error_recovery>
+<principle>
+Design workflows with clear error recovery paths. Claude should know what to do when things go wrong.
+</principle>
+
+<when_to_use>
+Include error recovery when:
+- Workflows interact with external systems
+- File operations could fail
+- Network calls could timeout
+- User input could be invalid
+- Errors are recoverable
+</when_to_use>
+</error_recovery>

package/plugins/lavra/skills/create-agent-skills/templates/router-skill.md

@@ -0,0 +1,73 @@
+---
+name: {{SKILL_NAME}}
+description: {{What it does}} Use when {{trigger conditions}}.
+---
+
+<essential_principles>
+## {{Core Concept}}
+
+{{Principles that ALWAYS apply, regardless of which workflow runs}}
+
+### 1. {{First principle}}
+{{Explanation}}
+
+### 2. {{Second principle}}
+{{Explanation}}
+
+### 3. {{Third principle}}
+{{Explanation}}
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. {{First option}}
+2. {{Second option}}
+3. {{Third option}}
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "{{keywords}}" | `workflows/{{first-workflow}}.md` |
+| 2, "{{keywords}}" | `workflows/{{second-workflow}}.md` |
+| 3, "{{keywords}}" | `workflows/{{third-workflow}}.md` |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<quick_reference>
+## {{Skill Name}} Quick Reference
+
+{{Brief reference information always useful to have visible}}
+</quick_reference>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+- {{reference-1.md}} - {{purpose}}
+- {{reference-2.md}} - {{purpose}}
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| {{first-workflow}}.md | {{purpose}} |
+| {{second-workflow}}.md | {{purpose}} |
+| {{third-workflow}}.md | {{purpose}} |
+</workflows_index>
+
+<success_criteria>
+A well-executed {{skill name}}:
+- {{First criterion}}
+- {{Second criterion}}
+- {{Third criterion}}
+</success_criteria>

package/plugins/lavra/skills/create-agent-skills/templates/simple-skill.md

@@ -0,0 +1,33 @@
+---
+name: {{SKILL_NAME}}
+description: {{What it does}} Use when {{trigger conditions}}.
+---
+
+<objective>
+{{Clear statement of what this skill accomplishes}}
+</objective>
+
+<quick_start>
+{{Immediate actionable guidance - what Claude should do first}}
+</quick_start>
+
+<process>
+## Step 1: {{First action}}
+
+{{Instructions for step 1}}
+
+## Step 2: {{Second action}}
+
+{{Instructions for step 2}}
+
+## Step 3: {{Third action}}
+
+{{Instructions for step 3}}
+</process>
+
+<success_criteria>
+{{Skill name}} is complete when:
+- [ ] {{First success criterion}}
+- [ ] {{Second success criterion}}
+- [ ] {{Third success criterion}}
+</success_criteria>