@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/create-agent-skills/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: creating-agent-skills
+description: "Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices."
+disable-model-invocation: true
+---
+
+# Creating Agent Skills
+
+This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
+
+## Core Principles
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
+
+### 2. Standard Markdown Format
+
+Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
+
+```markdown
+---
+name: my-skill-name
+description: What it does and when to use it
+---
+
+# My Skill Name
+
+## Quick Start
+Immediate actionable guidance...
+
+## Instructions
+Step-by-step procedures...
+
+## Examples
+Concrete usage examples...
+```
+
+### 3. Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
+
+```
+my-skill/
+├── SKILL.md              # Entry point (required)
+├── reference.md          # Detailed docs (loaded when needed)
+├── examples.md           # Usage examples
+└── scripts/              # Utility scripts (executed, not loaded)
+```
+
+### 4. Effective Descriptions
+
+The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
+
+**Good:**
+```yaml
+description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Bad:**
+```yaml
+description: Helps with documents
+```
+
+## Skill Structure
+
+### Required Frontmatter
+
+| Field | Required | Max Length | Description |
+|-------|----------|------------|-------------|
+| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
+| `description` | Yes | 1024 chars | What it does AND when to use it |
+| `allowed-tools` | No | - | Tools Claude can use without asking |
+| `model` | No | - | Specific model to use |
+
+### Naming Conventions
+
+Use **gerund form** (verb + -ing) for skill names:
+
+- `processing-pdfs`
+- `analyzing-spreadsheets`
+- `generating-commit-messages`
+- `reviewing-code`
+
+Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
+
+### Body Structure
+
+Use standard markdown headings:
+
+```markdown
+# Skill Name
+
+## Quick Start
+Fastest path to value...
+
+## Instructions
+Core guidance Claude follows...
+
+## Examples
+Input/output pairs showing expected behavior...
+
+## Advanced Features
+Additional capabilities (link to reference files)...
+
+## Guidelines
+Rules and constraints...
+```
+
+## What Would You Like To Do?
+
+1. **Create new skill** - Build from scratch
+2. **Audit existing skill** - Check against best practices
+3. **Add component** - Add workflow/reference/example
+4. **Get guidance** - Understand skill design
+
+## Creating a New Skill
+
+### Step 1: Choose Type
+
+**Simple skill (single file):**
+- Under 500 lines
+- Self-contained guidance
+- No complex workflows
+
+**Progressive disclosure skill (multiple files):**
+- SKILL.md as overview
+- Reference files for detailed docs
+- Scripts for utilities
+
+### Step 2: Create SKILL.md
+
+```markdown
+---
+name: your-skill-name
+description: [What it does]. Use when [trigger conditions].
+---
+
+# Your Skill Name
+
+## Quick Start
+
+[Immediate actionable example]
+
+```[language]
+[Code example]
+```
+
+## Instructions
+
+[Core guidance]
+
+## Examples
+
+**Example 1:**
+Input: [description]
+Output:
+```
+[result]
+```
+
+## Guidelines
+
+- [Constraint 1]
+- [Constraint 2]
+```
+
+### Step 3: Add Reference Files (If Needed)
+
+Link from SKILL.md to detailed content:
+
+```markdown
+For API reference, see [REFERENCE.md](REFERENCE.md).
+For form filling guide, see [FORMS.md](FORMS.md).
+```
+
+Keep references **one level deep** from SKILL.md.
+
+### Step 4: Add Scripts (If Needed)
+
+Scripts execute without loading into context:
+
+```markdown
+## Utility Scripts
+
+Extract fields:
+```bash
+python scripts/analyze.py input.pdf > fields.json
+```
+```
+
+### Step 5: Test With Real Usage
+
+1. Test with actual tasks, not test scenarios
+2. Observe where Claude struggles
+3. Refine based on real behavior
+4. Test with Haiku, Sonnet, and Opus
+
+## Auditing Existing Skills
+
+Check against this rubric:
+
+- [ ] Valid YAML frontmatter (name + description)
+- [ ] Description includes trigger keywords
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] SKILL.md under 500 lines
+- [ ] References one level deep
+- [ ] Examples are concrete, not abstract
+- [ ] Consistent terminology
+- [ ] No time-sensitive information
+- [ ] Scripts handle errors explicitly
+
+## Common Patterns
+
+### Template Pattern
+
+Provide output templates for consistent results:
+
+```markdown
+## Report Template
+
+```markdown
+# [Analysis Title]
+
+## Executive Summary
+[One paragraph overview]
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Recommendations
+1. [Action item]
+2. [Action item]
+```
+```
+
+### Workflow Pattern
+
+For complex multi-step tasks:
+
+```markdown
+## Migration Workflow
+
+Copy this checklist:
+
+```
+- [ ] Step 1: Backup database
+- [ ] Step 2: Run migration script
+- [ ] Step 3: Validate output
+- [ ] Step 4: Update configuration
+```
+
+**Step 1: Backup database**
+Run: `./scripts/backup.sh`
+...
+```
+
+### Conditional Pattern
+
+Guide through decision points:
+
+```markdown
+## Choose Your Approach
+
+**Creating new content?** Follow "Creation workflow" below.
+**Editing existing?** Follow "Editing workflow" below.
+```
+
+## Anti-Patterns to Avoid
+
+- **XML tags in body** - Use markdown headings instead
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Too many options** - Provide a default with escape hatch
+- **Windows paths** - Always use forward slashes
+- **Punting to Claude** - Scripts should handle errors
+- **Time-sensitive info** - Use "old patterns" section instead
+
+## Reference Files
+
+For detailed guidance, see:
+
+- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
+- [best-practices.md](references/best-practices.md) - Skill authoring best practices
+
+## Success Criteria
+
+A well-structured skill:
+- Has valid YAML frontmatter with descriptive name and description
+- Uses standard markdown headings (not XML tags)
+- Keeps SKILL.md under 500 lines
+- Links to reference files for detailed content
+- Includes concrete examples with input/output pairs
+- Has been tested with real usage
+
+Sources:
+- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
+- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [GitHub - anthropics/skills](https://github.com/anthropics/skills)

package/plugins/lavra/skills/create-agent-skills/references/api-security.md

@@ -0,0 +1,60 @@
+<overview>
+When building skills that make API calls requiring credentials (API keys, tokens, secrets), follow this protocol to prevent credentials from appearing in chat.
+</overview>
+
+<the_problem>
+Raw curl commands with environment variables expose credentials:
+
+```bash
+# BAD - API key visible in chat
+curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data
+```
+
+When Claude executes this, the full command with expanded `$API_KEY` appears in the conversation.
+</the_problem>
+
+<the_solution>
+Use `~/.claude/scripts/secure-api.sh` - a wrapper that loads credentials internally.
+
+<for_supported_services>
+```bash
+# GOOD - No credentials visible
+~/.claude/scripts/secure-api.sh <service> <operation> [args]
+
+# Examples:
+~/.claude/scripts/secure-api.sh facebook list-campaigns
+~/.claude/scripts/secure-api.sh ghl search-contact "email@example.com"
+```
+</for_supported_services>
+</the_solution>
+
+<credential_storage>
+**Location:** `~/.claude/.env` (global for all skills, accessible from any directory)
+
+**Format:**
+```bash
+# Service credentials
+SERVICE_API_KEY=your-key-here
+SERVICE_ACCOUNT_ID=account-id-here
+
+# Another service
+OTHER_API_TOKEN=token-here
+OTHER_BASE_URL=https://api.other.com
+```
+
+**Loading in script:**
+```bash
+set -a
+source ~/.claude/.env 2>/dev/null || { echo "Error: ~/.claude/.env not found" >&2; exit 1; }
+set +a
+```
+</credential_storage>
+
+<best_practices>
+1. **Never use raw curl with `$VARIABLE` in skill examples** - always use the wrapper
+2. **Add all operations to the wrapper** - don't make users figure out curl syntax
+3. **Auto-create credential placeholders** - add empty fields to `~/.claude/.env` immediately when creating the skill
+4. **Keep credentials in `~/.claude/.env`** - one central location, works everywhere
+5. **Document each operation** - show examples in SKILL.md
+6. **Handle errors gracefully** - check for missing env vars, show helpful error messages
+</best_practices>

package/plugins/lavra/skills/create-agent-skills/references/be-clear-and-direct.md

@@ -0,0 +1,84 @@
+<golden_rule>
+Show your skill to someone with minimal context and ask them to follow the instructions. If they're confused, Claude will likely be too.
+</golden_rule>
+
+<overview>
+Clarity and directness are fundamental to effective skill authoring. Clear instructions reduce errors, improve execution quality, and minimize token waste.
+</overview>
+
+<guidelines>
+<contextual_information>
+Give Claude contextual information that frames the task:
+
+- What the task results will be used for
+- What audience the output is meant for
+- What workflow the task is part of
+- The end goal or what successful completion looks like
+
+Context helps Claude make better decisions and produce more appropriate outputs.
+</contextual_information>
+
+<specificity>
+Be specific about what you want Claude to do. If you want code only and nothing else, say so.
+
+**Vague**: "Help with the report"
+**Specific**: "Generate a markdown report with three sections: Executive Summary, Key Findings, Recommendations"
+
+Specificity eliminates ambiguity and reduces iteration cycles.
+</specificity>
+
+<sequential_steps>
+Provide instructions as sequential steps. Use numbered lists or bullet points.
+
+Sequential steps create clear expectations and reduce the chance Claude skips important operations.
+</sequential_steps>
+</guidelines>
+
+<avoid_ambiguity>
+<principle>
+Eliminate words and phrases that create ambiguity or leave decisions open.
+</principle>
+
+<ambiguous_phrases>
+"Try to..." - Implies optional. Use "Always..." or "Never..." instead.
+"Should probably..." - Unclear obligation. Use "Must..." or "May optionally..." instead.
+"Generally..." - When are exceptions allowed? Use "Always... except when..." instead.
+"Consider..." - Should Claude always do this or only sometimes? Use "If X, then Y" or "Always..." instead.
+</ambiguous_phrases>
+</avoid_ambiguity>
+
+<define_edge_cases>
+<principle>
+Anticipate edge cases and define how to handle them. Don't leave Claude guessing.
+</principle>
+</define_edge_cases>
+
+<output_format_specification>
+<principle>
+When output format matters, specify it precisely. Show examples.
+</principle>
+</output_format_specification>
+
+<decision_criteria>
+<principle>
+When Claude must make decisions, provide clear criteria.
+</principle>
+</decision_criteria>
+
+<constraints_and_requirements>
+<principle>
+Clearly separate "must do" from "nice to have" from "must not do".
+</principle>
+</constraints_and_requirements>
+
+<success_criteria>
+<principle>
+Define what success looks like. How will Claude know it succeeded?
+</principle>
+</success_criteria>
+
+<testing_clarity>
+<principle>
+Test your instructions by asking: "Could I hand these instructions to a junior developer and expect correct results?"
+</principle>
+</testing_clarity>