codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/llm-prompt-optimizer/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: llm-prompt-optimizer
+description: "Use when improving prompts for any LLM. Applies proven prompt engineering techniques to boost output quality, reduce hallucinations, and cut token usage."
+risk: safe
+source: community
+date_added: "2026-03-04"
+---
+
+# LLM Prompt Optimizer
+
+## Overview
+
+This skill transforms weak, vague, or inconsistent prompts into precision-engineered instructions that reliably produce high-quality outputs from any LLM (Claude, Gemini, GPT-4, Llama, etc.). It applies systematic prompt engineering frameworks — from zero-shot to few-shot, chain-of-thought, and structured output patterns.
+
+## When to Use This Skill
+
+- Use when a prompt returns inconsistent, vague, or hallucinated results
+- Use when you need structured/JSON output from an LLM reliably
+- Use when designing system prompts for AI agents or chatbots
+- Use when you want to reduce token usage without sacrificing quality
+- Use when implementing chain-of-thought reasoning for complex tasks
+- Use when prompts work on one model but fail on another
+
+## Step-by-Step Guide
+
+### 1. Diagnose the Weak Prompt
+
+Before optimizing, identify which problem pattern applies:
+
+| Problem | Symptom | Fix |
+|---------|---------|-----|
+| Too vague | Generic, unhelpful answers | Add role + context + constraints |
+| No structure | Unformatted, hard-to-parse output | Specify output format explicitly |
+| Hallucination | Confident wrong answers | Add "say I don't know if unsure" |
+| Inconsistent | Different answers each run | Add few-shot examples |
+| Too long | Verbose, padded responses | Add length constraints |
+
+### 2. Apply the RSCIT Framework
+
+Every optimized prompt should have:
+
+- **R** — **Role**: Who is the AI in this interaction?
+- **S** — **Situation**: What context does it need?
+- **C** — **Constraints**: What are the rules and limits?
+- **I** — **Instructions**: What exactly should it do?
+- **T** — **Template**: What should the output look like?
+
+**Before (weak prompt):**
+```
+Explain machine learning.
+```
+
+**After (optimized prompt):**
+```
+You are a senior ML engineer explaining concepts to a junior developer.
+
+Context: The developer has 1 year of Python experience but no ML background.
+
+Task: Explain supervised machine learning in simple terms.
+
+Constraints:
+- Use an analogy from everyday life
+- Maximum 200 words
+- No mathematical formulas
+- End with one actionable next step
+
+Format: Plain prose, no bullet points.
+```
+
+### 3. Chain-of-Thought (CoT) Pattern
+
+For reasoning tasks, instruct the model to think step-by-step:
+
+```
+Solve this problem step by step, showing your work at each stage.
+Only provide the final answer after completing all reasoning steps.
+
+Problem: [your problem here]
+
+Thinking process:
+Step 1: [identify what's given]
+Step 2: [identify what's needed]
+Step 3: [apply logic or formula]
+Step 4: [verify the answer]
+
+Final Answer:
+```
+
+### 4. Few-Shot Examples Pattern
+
+Provide 2-3 examples to establish the pattern:
+
+```
+Classify the sentiment of customer reviews as POSITIVE, NEGATIVE, or NEUTRAL.
+
+Examples:
+Review: "This product exceeded my expectations!" -> POSITIVE
+Review: "It arrived broken and support was useless." -> NEGATIVE  
+Review: "Product works as described, nothing special." -> NEUTRAL
+
+Now classify:
+Review: "[your review here]" ->
+```
+
+### 5. Structured JSON Output Pattern
+
+```
+Extract the following information from the text below and return it as valid JSON only.
+Do not include any explanation or markdown — just the raw JSON object.
+
+Schema:
+{
+  "name": string,
+  "email": string | null,
+  "company": string | null,
+  "role": string | null
+}
+
+Text: [input text here]
+```
+
+### 6. Reduce Hallucination Pattern
+
+```
+Answer the following question based ONLY on the provided context.
+If the answer is not contained in the context, respond with exactly: "I don't have enough information to answer this."
+Do not make up or infer information not present in the context.
+
+Context:
+[your context here]
+
+Question: [your question here]
+```
+
+### 7. Prompt Compression Techniques
+
+Reduce token count without losing effectiveness:
+
+```
+# Verbose (expensive)
+"Please carefully analyze the following code and provide a detailed explanation of 
+what it does, how it works, and any potential issues you might find."
+
+# Compressed (efficient, same quality)
+"Analyze this code: explain what it does, how it works, and flag any issues."
+```
+
+## Best Practices
+
+- ✅ **Do:** Always specify the output format (JSON, markdown, plain text, bullet list)
+- ✅ **Do:** Use delimiters (```, ---) to separate instructions from content
+- ✅ **Do:** Test prompts with edge cases (empty input, unusual data)
+- ✅ **Do:** Version your system prompts in source control
+- ✅ **Do:** Add "think step by step" for math, logic, or multi-step tasks
+- ❌ **Don't:** Use negative-only instructions ("don't be verbose") — add positive alternatives
+- ❌ **Don't:** Assume the model knows your codebase context — always include it
+- ❌ **Don't:** Use the same prompt across different models without testing — they behave differently
+
+## Prompt Audit Checklist
+
+Before using a prompt in production:
+
+- [ ] Does it have a clear role/persona?
+- [ ] Is the output format explicitly defined?
+- [ ] Are edge cases handled (empty input, ambiguous data)?
+- [ ] Is the length appropriate (not too long/short)?
+- [ ] Has it been tested on 5+ varied inputs?
+- [ ] Is hallucination risk addressed for factual tasks?
+
+## Troubleshooting
+
+**Problem:** Model ignores format instructions
+**Solution:** Move format instructions to the END of the prompt, after examples. Use strong language: "You MUST return only valid JSON."
+
+**Problem:** Inconsistent results between runs
+**Solution:** Lower the temperature setting (0.0-0.3 for factual tasks). Add more few-shot examples.
+
+**Problem:** Prompt works in playground but fails in production
+**Solution:** Check if system prompt is being sent correctly. Verify token limits aren't being exceeded (use a token counter).
+
+**Problem:** Output is too long
+**Solution:** Add explicit word/sentence limits: "Respond in exactly 3 bullet points, each under 20 words."

package/templates/.agent/skills/local-legal-seo-audit/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: local-legal-seo-audit
+description: "Audit and improve local SEO for law firms, attorneys, forensic experts and legal/professional services sites with local presence, focusing on GBP, directories, E-E-A-T and practice/location pages."
+risk: safe
+source: original
+date_added: "2026-02-27"
+---
+
+# Local Legal SEO Audit
+
+You are an expert in local SEO for legal and professional services. Your goal is to audit and improve the organic visibility of law firms, attorneys, forensic experts, legal consultants, and related professional services with a local or regional presence.
+
+This skill is scoped to the **specific needs of legal and professional services sites**, where trust signals, local authority, E-E-A-T, and directory presence are the primary ranking levers.
+
+## When to Use
+Use this skill when:
+- You need to audit or improve local SEO for a law firm, attorney, forensic expert, or similar legal/professional services website.
+- The goal is to improve visibility in Google local pack/maps, legal directories, and local organic results for specific practice areas or cities.
+
+Do **not** use this skill when:
+- You need a general SEO health check across any niche (use `seo-audit`).
+- You are investigating a sudden traffic or rankings crash (use `seo-forensic-incident-response`).
+
+---
+
+## Initial Assessment
+
+Before auditing, gather context:
+
+1. **Practice & Business Context**
+   - What is the practice area? (criminal law, civil litigation, forensic expertise, notary, etc.)
+   - Solo practitioner, small firm, or large office?
+   - Single location or multiple offices?
+   - Primary geographic target? (city, state, region, national)
+
+2. **Current Visibility**
+   - Are they appearing in Google local pack (maps results)?
+   - What keywords are they currently ranking for?
+   - Do they have a Google Business Profile?
+   - Any competitor firms consistently outranking them?
+
+3. **Existing Assets**
+   - Do they have a website? CMS used?
+   - Do they have a Google Business Profile?
+   - Are they listed in legal directories (Jusbrasil, OAB, Avvo, Justia, FindLaw, etc.)?
+   - Do they have any reviews?
+
+4. **Goals**
+   - Drive phone calls and contact form submissions?
+   - Rank for specific case types (e.g., "advogado criminal em [cidade]")?
+   - Build authority for forensic reports or expert witness services?
+
+---
+
+## Audit Framework
+
+### Priority Order for Legal & Forensic Sites
+
+1. **Google Business Profile & Local Pack** (highest impact for local queries)
+2. **E-E-A-T & Trust Signals** (critical for YMYL — legal is a Your Money or Your Life category)
+3. **On-Page Optimization** (practice area pages, location pages)
+4. **Technical Foundations** (crawlability, mobile, speed)
+5. **Directory & Citation Consistency** (NAP, legal directories)
+6. **Content Strategy** (FAQ, blog, case types)
+7. **Reviews & Reputation** (trust and local ranking factor)
+
+---
+
+## Google Business Profile (GBP) Audit
+
+For legal services, GBP is often the single highest-ROI local SEO asset.
+
+**Profile Completeness**
+- Business name matches website and directories exactly
+- Correct primary category (e.g., "Law Firm", "Attorney", "Forensic Consultant")
+- Secondary categories added where relevant
+- Full address and service area configured
+- Primary phone number consistent with website
+- Website URL linked correctly
+- Business hours accurate and updated
+- Services listed with descriptions
+- Q&A section populated with common questions
+
+**Photos & Visual Content**
+- Office exterior and interior photos
+- Team photos (humanize the brand)
+- Logo uploaded
+- Regular photo updates (signals active profile)
+
+**Reviews**
+- Total number of reviews vs. local competitors
+- Average star rating
+- Owner responses to reviews (all, especially negative)
+- Review velocity (frequency of new reviews)
+- Strategy for ethically requesting reviews from satisfied clients
+
+**GBP Posts**
+- Regular posts (news, case type highlights, legal tips)
+- Event posts for seminars or free consultations
+- Offer posts if applicable
+
+---
+
+## E-E-A-T Audit for Legal Sites
+
+Legal sites fall under Google's YMYL (Your Money or Your Life) classification. E-E-A-T signals are heavily weighted.
+
+### Experience
+- Does the site demonstrate real case experience?
+- Are there case studies, results, or anonymized client outcomes?
+- Does the attorney/expert have documented field experience? (years, cases, specializations)
+- For forensic experts: are expert witness history, court appearances, or published reports referenced?
+
+### Expertise
+- Attorney/expert bio pages with:
+  - Academic credentials (graduation, postgraduate, PhD, certifications)
+  - Bar registration number or professional council registration (OAB, CFC, etc.)
+  - Areas of specialization clearly stated
+  - Publications, articles, or academic contributions
+  - Speaking engagements or media appearances
+- Content written or reviewed by a qualified professional
+- Accurate, up-to-date legal information
+
+### Authoritativeness
+- Is the firm/expert cited or referenced by external sources?
+- Are they listed in authoritative legal directories?
+- Media mentions, interviews, or press coverage
+- Recognized by professional associations
+- Academic publications or research (especially relevant for forensic experts)
+
+### Trustworthiness
+- Clear "About" page with real people and credentials
+- Physical address visible and verifiable
+- Contact page with phone, email, and address
+- Privacy policy and terms of use
+- Secure site (HTTPS, valid SSL)
+- No misleading claims or guarantees of outcomes
+- Disclaimer on legal content where applicable
+
+---
+
+## On-Page SEO Audit
+
+### Practice Area Pages
+
+Each major practice area or service should have a dedicated, optimized page.
+
+**Check for:**
+- One page per distinct practice area (e.g., "Defesa Criminal", "Perícia Digital", "Laudo Grafotécnico")
+- Primary keyword in title tag, H1, and URL
+- Unique, expert-written content per page
+- Internal links to and from the homepage and other related pages
+- Clear calls to action (phone number, WhatsApp button, contact form)
+- Schema markup for LegalService or ProfessionalService (see schema-markup skill)
+
+**Common issues:**
+- All services crammed onto a single page
+- Generic content not differentiated by specialty
+- No clear geographic signal on practice area pages
+
+### Location Pages
+
+For firms serving multiple cities or regions:
+
+- Dedicated page per location with unique content
+- City/neighborhood keyword in title, H1, and URL
+- Embed Google Maps on each location page
+- NAP (Name, Address, Phone) consistent with GBP
+- Local landmarks, courthouse references, or regional context
+- No copy-paste duplicate content across location pages
+
+### Homepage
+
+- Clear headline communicating practice area + location
+- Primary keyword (e.g., "Escritório de Advocacia Criminal em Belo Horizonte")
+- Trust signals above the fold: years of experience, credentials, bar number
+- Social proof: client count, case count, review snippets
+- Clear primary CTA (call, WhatsApp, free consultation)
+
+### Title Tags & Meta Descriptions
+
+- Format for legal pages: `[Service] em [City] | [Firm Name]`
+- Include primary keyword naturally
+- Meta descriptions: highlight differentiator (experience, specialization, availability)
+- No duplicate titles or descriptions across pages
+
+### Heading Structure
+
+- Single H1 per page with primary keyword
+- H2s for subsections (subtopics of the practice area)
+- H3s for supporting details
+- No headings used purely for styling
+
+---
+
+## Technical SEO Audit
+
+Focus on issues most common in legal site CMS platforms (WordPress, Wix, Squarespace):
+
+**Mobile Experience**
+- Most legal searches happen on mobile
+- Click-to-call button prominent on mobile
+- Fast load time on 4G/mobile networks
+- No intrusive pop-ups that block content on mobile
+
+**Core Web Vitals**
+- LCP < 2.5s (especially homepage and practice area pages)
+- CLS < 0.1 (common issue on sites with banners or cookie popups)
+- INP < 200ms
+
+**Crawlability**
+- Robots.txt not blocking key pages
+- XML sitemap submitted to Google Search Console
+- All practice area and location pages indexed
+
+**HTTPS & Security**
+- Full HTTPS with valid certificate
+- No mixed content
+- Privacy policy accessible
+
+**URL Structure**
+- Clean, readable URLs: `/advogado-criminal-belo-horizonte/`
+- No session IDs or unnecessary parameters
+- Consistent trailing slash handling
+
+---
+
+## Directory & Citation Audit (NAP Consistency)
+
+For local legal SEO, citations in authoritative directories are a significant ranking factor.
+
+**Core Legal Directories (Brazil)**
+- OAB (Ordem dos Advogados do Brasil) — official listing
+- Jusbrasil — attorney profile and articles
+- Escavador — academic and professional profile
+- ORCID — for forensic experts with publications
+
+**Core Legal Directories (International)**
+- Avvo
+- FindLaw
+- Justia
+- Martindale-Hubbell
+- Google Business Profile (primary)
+
+**General Citation Sources**
+- Yelp, Facebook Business, Apple Maps, Bing Places
+- Industry associations
+
+**NAP Audit**
+- Name, Address, and Phone are identical across all listings
+- No outdated addresses or old phone numbers
+- Duplicate listings identified and removed or merged
+- Website URL consistent across all citations
+
+---
+
+## Content Strategy for Legal Sites
+
+### FAQ Content
+
+Legal FAQ pages rank well for long-tail queries and build trust.
+
+- Create FAQ pages per practice area
+- Target "question" queries: "o que fazer quando", "quanto tempo demora", "qual a diferença entre"
+- Use FAQ schema markup for rich results
+- Keep answers accurate, brief, and written in plain language
+
+### Blog / Legal Articles
+
+- Target informational queries potential clients search before hiring
+- Organize by practice area topic cluster
+- Include author byline with credentials
+- Update articles regularly (show freshness for time-sensitive legal content)
+- Internal link from articles to relevant practice area pages
+
+### For Forensic Experts
+
+- Publish case-type explainers (e.g., "Como funciona uma perícia grafotécnica")
+- Describe the expert witness process and what to expect
+- Share academic abstracts or summaries of published research
+- Explain the difference between types of forensic reports (laudo, parecer, vistoria)
+
+---
+
+## Reviews & Reputation Audit
+
+- Total reviews on GBP vs. top 3 local competitors
+- Strategy for requesting reviews (post-consultation, post-case-resolution)
+- Are all reviews responded to by the firm?
+- Any negative reviews unaddressed?
+- Presence on secondary review platforms: Facebook, Reclame Aqui (if applicable)
+
+---
+
+## Output Format
+
+### Audit Report Structure
+
+**Executive Summary**
+- Overall local visibility assessment
+- Top 3–5 priority issues
+- Quick wins identified (e.g., incomplete GBP, missing practice area pages)
+
+**GBP Findings**
+For each issue:
+- **Issue**: What is missing or wrong
+- **Impact**: High/Medium/Low
+- **Fix**: Specific action
+
+**E-E-A-T & Trust Findings**
+Same format
+
+**On-Page Findings**
+Same format
+
+**Technical Findings**
+Same format
+
+**Directory & Citation Findings**
+Same format
+
+**Prioritized Action Plan**
+1. Critical (blocks visibility or trust: missing GBP, no HTTPS, no practice area pages)
+2. High impact (E-E-A-T improvements, location pages, review strategy)
+3. Quick wins (title tags, meta descriptions, GBP photos, FAQ schema)
+4. Long-term (content strategy, link building, academic publications)
+
+---
+
+## Task-Specific Questions
+
+1. What is the primary practice area and geographic target market?
+2. Do you have a Google Business Profile? Is it verified?
+3. Are you listed in OAB, Jusbrasil, Escavador, or other relevant directories?
+4. How many reviews do you currently have, and who are your main local competitors?
+5. Do you have dedicated pages for each practice area, or is everything on one page?
+6. For forensic experts: do you have published research, ORCID profile, or academic affiliations?
+
+---
+
+## Related Skills
+
+- **seo-audit**: For general SEO health checks outside the legal/local context.
+- **seo-forensic-incident-response**: For investigating sudden drops in traffic or rankings.
+- **schema-markup**: For implementing LegalService, Attorney, and FAQ structured data.
+- **ai-seo**: For optimizing legal content for AI search experiences and featured snippets.
+- **page-cro**: For improving conversion rate on practice area pages and contact forms.