@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/create-agent-skills/references/iteration-and-testing.md

@@ -0,0 +1,164 @@
+<overview>
+Skills improve through iteration and testing. This reference covers evaluation-driven development, Claude A/B testing patterns, and XML structure validation during testing.
+</overview>
+
+<evaluation_driven_development>
+<principle>
+Create evaluations BEFORE writing extensive documentation. This ensures your skill solves real problems rather than documenting imagined ones.
+</principle>
+
+<workflow>
+<step_1>
+**Identify gaps**: Run Claude on representative tasks without a skill. Document specific failures or missing context.
+</step_1>
+
+<step_2>
+**Create evaluations**: Build three scenarios that test these gaps.
+</step_2>
+
+<step_3>
+**Establish baseline**: Measure Claude's performance without the skill.
+</step_3>
+
+<step_4>
+**Write minimal instructions**: Create just enough content to address the gaps and pass evaluations.
+</step_4>
+
+<step_5>
+**Iterate**: Execute evaluations, compare against baseline, and refine.
+</step_5>
+</workflow>
+</evaluation_driven_development>
+
+<iterative_development_with_claude>
+<principle>
+The most effective skill development uses Claude itself. Work with "Claude A" (expert who helps refine) to create skills used by "Claude B" (agent executing tasks).
+</principle>
+
+<creating_skills>
+<workflow>
+<step_1>
+**Complete task without skill**: Work through problem with Claude A, noting what context you repeatedly provide.
+</step_1>
+
+<step_2>
+**Ask Claude A to create skill**: "Create a skill that captures this pattern we just used"
+</step_2>
+
+<step_3>
+**Review for conciseness**: Remove unnecessary explanations.
+</step_3>
+
+<step_4>
+**Improve architecture**: Organize content with progressive disclosure.
+</step_4>
+
+<step_5>
+**Test with Claude B**: Use fresh instance to test on real tasks.
+</step_5>
+
+<step_6>
+**Iterate based on observation**: Return to Claude A with specific issues observed.
+</step_6>
+</workflow>
+</creating_skills>
+</iterative_development_with_claude>
+
+<model_testing>
+<principle>
+Test with all models you plan to use. Different models have different strengths and need different levels of detail.
+</principle>
+
+<haiku_testing>
+**Claude Haiku** (fast, economical)
+
+Questions to ask:
+- Does the skill provide enough guidance?
+- Are examples clear and complete?
+- Do implicit assumptions become explicit?
+- Does Haiku need more structure?
+
+Haiku benefits from:
+- More explicit instructions
+- Complete examples (no partial code)
+- Clear success criteria
+- Step-by-step workflows
+</haiku_testing>
+
+<sonnet_testing>
+**Claude Sonnet** (balanced)
+
+Questions to ask:
+- Is the skill clear and efficient?
+- Does it avoid over-explanation?
+- Are workflows well-structured?
+- Does progressive disclosure work?
+
+Sonnet benefits from:
+- Balanced detail level
+- XML structure for clarity
+- Progressive disclosure
+- Concise but complete guidance
+</sonnet_testing>
+
+<opus_testing>
+**Claude Opus** (powerful reasoning)
+
+Questions to ask:
+- Does the skill avoid over-explaining?
+- Can Opus infer obvious steps?
+- Are constraints clear?
+- Is context minimal but sufficient?
+
+Opus benefits from:
+- Concise instructions
+- Principles over procedures
+- High degrees of freedom
+- Trust in reasoning capabilities
+</opus_testing>
+</model_testing>
+
+<observation_based_iteration>
+<principle>
+Iterate based on what you observe, not what you assume. Real usage reveals issues assumptions miss.
+</principle>
+
+<iteration_pattern>
+1. **Observe**: Run Claude on real tasks with current skill
+2. **Document**: Note specific issues, not general feelings
+3. **Hypothesize**: Why did this issue occur?
+4. **Fix**: Make targeted changes to address specific issues
+5. **Test**: Verify fix works on same scenario
+6. **Validate**: Ensure fix doesn't break other scenarios
+7. **Repeat**: Continue with next observed issue
+</iteration_pattern>
+</observation_based_iteration>
+
+<progressive_refinement>
+<principle>
+Skills don't need to be perfect initially. Start minimal, observe usage, add what's missing.
+</principle>
+
+<initial_version>
+Start with:
+- Valid YAML frontmatter
+- Required XML tags: objective, quick_start, success_criteria
+- Minimal working example
+- Basic success criteria
+
+Skip initially:
+- Extensive examples
+- Edge case documentation
+- Advanced features
+- Detailed reference files
+</initial_version>
+
+<iteration_additions>
+Add through iteration:
+- Examples when patterns aren't clear from description
+- Edge cases when observed in real usage
+- Advanced features when users need them
+- Reference files when SKILL.md approaches 500 lines
+- Validation scripts when errors are common
+</iteration_additions>
+</progressive_refinement>

package/plugins/lavra/skills/create-agent-skills/references/official-spec.md

@@ -0,0 +1,185 @@
+# Anthropic Official Skill Specification
+
+Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
+
+## SKILL.md File Structure
+
+Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
+
+### Basic Format
+
+```markdown
+---
+name: your-skill-name
+description: Brief description of what this Skill does and when to use it
+---
+
+# Your Skill Name
+
+## Instructions
+Provide clear, step-by-step guidance for Claude.
+
+## Examples
+Show concrete examples of using this Skill.
+```
+
+## Required Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
+| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
+| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
+| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
+
+## Skill Locations & Priority
+
+```
+Enterprise (highest priority) -> Personal -> Project -> Plugin (lowest priority)
+```
+
+| Type | Path | Applies to |
+|------|------|-----------|
+| **Enterprise** | See managed settings | All users in organization |
+| **Personal** | `~/.claude/skills/` | You, across all projects |
+| **Project** | `.claude/skills/` | Anyone working in repository |
+| **Plugin** | Bundled with plugins | Anyone with plugin installed |
+
+## How Skills Work
+
+1. **Discovery**: Claude loads only name and description at startup
+2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
+3. **Execution**: Claude follows the Skill's instructions and loads referenced files
+
+**Key Principle**: Skills are **model-invoked** -- Claude automatically decides which Skills to use based on your request.
+
+## Progressive Disclosure Pattern
+
+Keep `SKILL.md` under 500 lines by linking to supporting files:
+
+```
+my-skill/
+├── SKILL.md (required - overview and navigation)
+├── reference.md (detailed API docs - loaded when needed)
+├── examples.md (usage examples - loaded when needed)
+└── scripts/
+    └── helper.py (utility script - executed, not loaded)
+```
+
+### Example SKILL.md with References
+
+```markdown
+---
+name: pdf-processing
+description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
+allowed-tools: Read, Bash(python:*)
+---
+
+# PDF Processing
+
+## Quick start
+
+Extract text:
+```python
+import pdfplumber
+with pdfplumber.open("doc.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+For form filling, see [FORMS.md](FORMS.md).
+For detailed API reference, see [REFERENCE.md](REFERENCE.md).
+
+## Requirements
+
+Packages must be installed:
+```bash
+pip install pypdf pdfplumber
+```
+```
+
+## Restricting Tool Access
+
+```yaml
+---
+name: reading-files-safely
+description: Read files without making changes. Use when you need read-only file access.
+allowed-tools: Read, Grep, Glob
+---
+```
+
+Benefits:
+- Read-only Skills that shouldn't modify files
+- Limited scope for specific tasks
+- Security-sensitive workflows
+
+## Writing Effective Descriptions
+
+The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
+
+**Always write in third person.** The description is injected into the system prompt.
+
+- **Good:** "Processes Excel files and generates reports"
+- **Avoid:** "I can help you process Excel files"
+- **Avoid:** "You can use this to process Excel files"
+
+**Be specific and include key terms:**
+
+```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.
+```
+
+**Avoid vague descriptions:**
+
+```yaml
+description: Helps with documents  # Too vague!
+```
+
+## Complete Example: Commit Message Generator
+
+```markdown
+---
+name: generating-commit-messages
+description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+---
+
+# Generating Commit Messages
+
+## Instructions
+
+1. Run `git diff --staged` to see changes
+2. I'll suggest a commit message with:
+   - Summary under 50 characters
+   - Detailed description
+   - Affected components
+
+## Best practices
+
+- Use present tense
+- Explain what and why, not how
+```
+
+## Complete Example: Code Explanation Skill
+
+```markdown
+---
+name: explaining-code
+description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
+---
+
+# Explaining Code
+
+When explaining code, always include:
+
+1. **Start with an analogy**: Compare the code to something from everyday life
+2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
+3. **Walk through the code**: Explain step-by-step what happens
+4. **Highlight a gotcha**: What's a common misconception?
+
+Keep explanations conversational. For complex concepts, use multiple analogies.
+```
+
+## Distribution
+
+- **Project Skills**: Commit `.claude/skills/` to version control
+- **Plugins**: Add `skills/` directory to plugin with Skill folders
+- **Enterprise**: Deploy organization-wide through managed settings

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

@@ -0,0 +1,168 @@
+# Recommended Skill Structure
+
+The optimal structure for complex skills separates routing, workflows, and knowledge.
+
+<structure>
+```
+skill-name/
+├── SKILL.md              # Router + essential principles (unavoidable)
+├── workflows/            # Step-by-step procedures (how)
+│   ├── workflow-a.md
+│   ├── workflow-b.md
+│   └── ...
+└── references/           # Domain knowledge (what)
+    ├── reference-a.md
+    ├── reference-b.md
+    └── ...
+```
+</structure>
+
+<why_this_works>
+## Problems This Solves
+
+**Problem 1: Context gets skipped**
+When important principles are in a separate file, Claude may not read them.
+**Solution:** Put essential principles directly in SKILL.md. They load automatically.
+
+**Problem 2: Wrong context loaded**
+A "build" task loads debugging references. A "debug" task loads build references.
+**Solution:** Intake question determines intent -> routes to specific workflow -> workflow specifies which references to read.
+
+**Problem 3: Monolithic skills are overwhelming**
+500+ lines of mixed content makes it hard to find relevant parts.
+**Solution:** Small router (SKILL.md) + focused workflows + reference library.
+
+**Problem 4: Procedures mixed with knowledge**
+"How to do X" mixed with "What X means" creates confusion.
+**Solution:** Workflows are procedures (steps). References are knowledge (patterns, examples).
+</why_this_works>
+
+<skill_md_template>
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<essential_principles>
+## How This Skill Works
+
+[Inline principles that apply to ALL workflows. Cannot be skipped.]
+
+### Principle 1: [Name]
+[Brief explanation]
+
+### Principle 2: [Name]
+[Brief explanation]
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. [Option A]
+2. [Option B]
+3. [Option C]
+4. Something else
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "keyword", "keyword" | `workflows/option-a.md` |
+| 2, "keyword", "keyword" | `workflows/option-b.md` |
+| 3, "keyword", "keyword" | `workflows/option-c.md` |
+| 4, other | Clarify, then select |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Category A:** file-a.md, file-b.md
+**Category B:** file-c.md, file-d.md
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| option-a.md | [What it does] |
+| option-b.md | [What it does] |
+| option-c.md | [What it does] |
+</workflows_index>
+```
+</skill_md_template>
+
+<workflow_template>
+## Workflow Template
+
+```markdown
+# Workflow: [Name]
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/relevant-file.md
+2. references/another-file.md
+</required_reading>
+
+<process>
+## Step 1: [Name]
+[What to do]
+
+## Step 2: [Name]
+[What to do]
+
+## Step 3: [Name]
+[What to do]
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+</success_criteria>
+```
+</workflow_template>
+
+<when_to_use_this_pattern>
+## When to Use This Pattern
+
+**Use router + workflows + references when:**
+- Multiple distinct workflows (build vs debug vs ship)
+- Different workflows need different references
+- Essential principles must not be skipped
+- Skill has grown beyond 200 lines
+
+**Use simple single-file skill when:**
+- One workflow
+- Small reference set
+- Under 200 lines total
+- No essential principles to enforce
+</when_to_use_this_pattern>
+
+<key_insight>
+## The Key Insight
+
+**SKILL.md is always loaded. Use this guarantee.**
+
+Put unavoidable content in SKILL.md:
+- Essential principles
+- Intake question
+- Routing logic
+
+Put workflow-specific content in workflows/:
+- Step-by-step procedures
+- Required references for that workflow
+- Success criteria for that workflow
+
+Put reusable knowledge in references/:
+- Patterns and examples
+- Technical details
+- Domain expertise
+</key_insight>