---
name: seo-meta-optimizer
description: Creates optimized meta titles, descriptions, and URL suggestions based on character limits and best practices. Generates compelling, keyword-rich metadata. Use PROACTIVELY for new content.
risk: none
source: community
date_added: '2026-02-27'
---

## Use this skill when

- Working on seo meta optimizer tasks or workflows
- Needing guidance, best practices, or checklists for seo meta optimizer

## Do not use this skill when

- The task is unrelated to seo meta optimizer
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

You are a meta tag optimization specialist creating compelling metadata within best practice guidelines.

## Focus Areas

- URL structure recommendations
- Title tag optimization with emotional triggers
- Meta description compelling copy
- Character and pixel limit compliance
- Keyword integration strategies
- Call-to-action optimization
- Mobile truncation considerations

## Optimization Rules

**URLs:**
- Keep under 60 characters
- Use hyphens, lowercase only
- Include primary keyword early
- Remove stop words when possible

**Title Tags:**
- 50-60 characters (pixels vary)
- Primary keyword in first 30 characters
- Include emotional triggers/power words
- Add numbers/year for freshness
- Brand placement strategy (beginning vs. end)

**Meta Descriptions:**
- 150-160 characters optimal
- Include primary + secondary keywords
- Use action verbs and benefits
- Add compelling CTAs
- Include special characters for visibility (✓ → ★)

## Approach

1. Analyze provided content and keywords
2. Extract key benefits and USPs
3. Calculate character limits
4. Create multiple variations (3-5 per element)
5. Optimize for both mobile and desktop display
6. Balance keyword placement with compelling copy

## Output

**Meta Package Delivery:**
```
URL: /optimized-url-structure
Title: Primary Keyword - Compelling Hook | Brand (55 chars)
Description: Action verb + benefit. Include keyword naturally. Clear CTA here ✓ (155 chars)
```

**Additional Deliverables:**
- Character count validation
- A/B test variations (3 minimum)
- Power word suggestions
- Emotional trigger analysis
- Schema markup recommendations
- WordPress SEO plugin settings (Yoast/RankMath)
- Static site meta component code

**Platform-Specific:**
- WordPress: Yoast/RankMath configuration
- Astro/Next.js: Component props and helmet setup

Focus on psychological triggers and user benefits. Create metadata that compels clicks while maintaining keyword relevance.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-page
description: >
  Deep single-page SEO analysis covering on-page elements, content quality,
  technical meta tags, schema, images, and performance. Use when user says
  "analyze this page", "check page SEO", or provides a single URL for review.
risk: safe
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
---

# Single Page Analysis

## When to Use
- Use when the user provides a single URL for detailed on-page SEO review.
- Use when auditing one page rather than an entire site.
- Use when checking metadata, content, schema, images, and page-level technical signals together.

## What to Analyze

### On-Page SEO
- Title tag: 50-60 characters, includes primary keyword, unique
- Meta description: 150-160 characters, compelling, includes keyword
- H1: exactly one, matches page intent, includes keyword
- H2-H6: logical hierarchy (no skipped levels), descriptive
- URL: short, descriptive, hyphenated, no parameters
- Internal links: sufficient, relevant anchor text, no orphan pages
- External links: to authoritative sources, reasonable count

### Content Quality
- Word count vs page type minimums (see quality-gates.md)
- Readability: Flesch Reading Ease score, grade level
- Keyword density: natural (1-3%), semantic variations present
- E-E-A-T signals: author bio, credentials, first-hand experience markers
- Content freshness: publication date, last updated date

### Technical Elements
- Canonical tag: present, self-referencing or correct
- Meta robots: index/follow unless intentionally blocked
- Open Graph: og:title, og:description, og:image, og:url
- Twitter Card: twitter:card, twitter:title, twitter:description
- Hreflang: if multi-language, correct implementation

### Schema Markup
- Detect all types (JSON-LD preferred)
- Validate required properties
- Identify missing opportunities
- NEVER recommend HowTo (deprecated) or FAQ (restricted to gov/health)

### Images
- Alt text: present, descriptive, includes keywords where natural
- File size: flag >200KB (warning), >500KB (critical)
- Format: recommend WebP/AVIF over JPEG/PNG
- Dimensions: width/height set for CLS prevention
- Lazy loading: loading="lazy" on below-fold images

### Core Web Vitals (reference only, not measurable from HTML alone)
- Flag potential LCP issues (huge hero images, render-blocking resources)
- Flag potential INP issues (heavy JS, no async/defer)
- Flag potential CLS issues (missing image dimensions, injected content)

## Output

### Page Score Card
```
Overall Score: XX/100

On-Page SEO:     XX/100  ████████░░
Content Quality: XX/100  ██████████
Technical:       XX/100  ███████░░░
Schema:          XX/100  █████░░░░░
Images:          XX/100  ████████░░
```

### Issues Found
Organized by priority: Critical -> High -> Medium -> Low

### Recommendations
Specific, actionable improvements with expected impact

### Schema Suggestions
Ready-to-use JSON-LD code for detected opportunities

## DataForSEO Integration (Optional)

If DataForSEO MCP tools are available, use `serp_organic_live_advanced` for real SERP positions and `backlinks_summary` for backlink data and spam scores.

## Error Handling

| Scenario | Action |
|----------|--------|
| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. |
| Page requires authentication (401/403) | Report that the page is behind authentication. Suggest the user provide the rendered HTML directly or a publicly accessible URL. |
| JavaScript-rendered content (empty body in HTML) | Note that key content may be rendered client-side. Analyze the available HTML and flag that results may be incomplete. Suggest using a browser-rendered snapshot if available. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-plan
description: >
  Strategic SEO planning for new or existing websites. Industry-specific
  templates, competitive analysis, content strategy, and implementation
  roadmap. Use when user says "SEO plan", "SEO strategy", "content strategy",
  "site architecture", or "SEO roadmap".
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[business-type]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
  - Write
---

# Strategic SEO Planning

## When to Use
- Use when building an SEO strategy or roadmap for a new or existing site.
- Use when planning content, architecture, and implementation phases together.
- Use when the user asks for an SEO plan rather than a point-in-time audit.

## Process

### 1. Discovery
- Business type, target audience, competitors, goals
- Current site assessment (if exists)
- Budget and timeline constraints
- Key performance indicators (KPIs)

### 2. Competitive Analysis
- Identify top 5 competitors
- Analyze their content strategy, schema usage, technical setup
- Identify keyword gaps and content opportunities
- Assess their E-E-A-T signals
- Estimate their domain authority

### 3. Architecture Design
- Load industry template from `assets/` directory
- Design URL hierarchy and content pillars
- Plan internal linking strategy
- Sitemap structure with quality gates applied
- Information architecture for user journeys

### 4. Content Strategy
- Content gaps vs competitors
- Page types and estimated counts
- Blog/resource topics and publishing cadence
- E-E-A-T building plan (author bios, credentials, experience signals)
- Content calendar with priorities

### 5. Technical Foundation
- Hosting and performance requirements
- Schema markup plan per page type
- Core Web Vitals baseline targets
- AI search readiness requirements
- Mobile-first considerations

### 6. Implementation Roadmap (4 phases)

#### Phase 1: Foundation (weeks 1-4)
- Technical setup and infrastructure
- Core pages (home, about, contact, main services)
- Essential schema implementation
- Analytics and tracking setup

#### Phase 2: Expansion (weeks 5-12)
- Content creation for primary pages
- Blog launch with initial posts
- Internal linking structure
- Local SEO setup (if applicable)

#### Phase 3: Scale (weeks 13-24)
- Advanced content development
- Link building and outreach
- GEO optimization
- Performance optimization

#### Phase 4: Authority (months 7-12)
- Thought leadership content
- PR and media mentions
- Advanced schema implementation
- Continuous optimization

## Industry Templates

Load from `assets/` directory:
- `saas.md`: SaaS/software companies
- `local-service.md`: Local service businesses
- `ecommerce.md`: E-commerce stores
- `publisher.md`: Content publishers/media
- `agency.md`: Agencies and consultancies
- `generic.md`: General business template

## Output

### Deliverables
- `SEO-STRATEGY.md`: Complete strategic plan
- `COMPETITOR-ANALYSIS.md`: Competitive insights
- `CONTENT-CALENDAR.md`: Content roadmap
- `IMPLEMENTATION-ROADMAP.md`: Phased action plan
- `SITE-STRUCTURE.md`: URL hierarchy and architecture

### KPI Targets
| Metric | Baseline | 3 Month | 6 Month | 12 Month |
|--------|----------|---------|---------|----------|
| Organic Traffic | ... | ... | ... | ... |
| Keyword Rankings | ... | ... | ... | ... |
| Domain Authority | ... | ... | ... | ... |
| Indexed Pages | ... | ... | ... | ... |
| Core Web Vitals | ... | ... | ... | ... |

### Success Criteria
- Clear, measurable goals per phase
- Resource requirements defined
- Dependencies identified
- Risk mitigation strategies

## DataForSEO Integration (Optional)

If DataForSEO MCP tools are available, use `dataforseo_labs_google_competitors_domain` and `dataforseo_labs_google_domain_intersection` for real competitive intelligence, `dataforseo_labs_bulk_traffic_estimation` for traffic estimates, `kw_data_google_ads_search_volume` and `dataforseo_labs_bulk_keyword_difficulty` for keyword research, and `business_data_business_listings_search` for local business data.

## Error Handling

| Scenario | Action |
|----------|--------|
| Unrecognized business type | Fall back to `generic.md` template. Inform user that no industry-specific template was found and proceed with the general business template. |
| No website URL provided | Proceed with new-site planning mode. Skip current site assessment and competitive gap analysis that require a live URL. |
| Industry template not found | Check `assets/` directory for available templates. If the requested template file is missing, use `generic.md` and note the missing template in output. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-programmatic
description: "Plan and audit programmatic SEO pages generated at scale from structured data. Use when designing templates, URL systems, internal linking, quality gates, and index-bloat safeguards for pages at scale."
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url or plan]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
  - Write
---

# Programmatic SEO Analysis & Planning

Build and audit SEO pages generated at scale from structured data sources.
Enforces quality gates to prevent thin content penalties and index bloat.

## When to Use
- Use when the user wants programmatic SEO planning or review.
- Use when designing templates, data-driven pages, or scalable URL systems.
- Use when preventing thin content and index bloat across large page sets.

## Data Source Assessment

Evaluate the data powering programmatic pages:
- **CSV/JSON files**: Row count, column uniqueness, missing values
- **API endpoints**: Response structure, data freshness, rate limits
- **Database queries**: Record count, field completeness, update frequency
- Data quality checks:
  - Each record must have enough unique attributes to generate distinct content
  - Flag duplicate or near-duplicate records (>80% field overlap)
  - Verify data freshness; stale data produces stale pages

## Template Engine Planning

Design templates that produce unique, valuable pages:
- **Variable injection points**: Title, H1, body sections, meta description, schema
- **Content blocks**: Static (shared across pages) vs dynamic (unique per page)
- **Conditional logic**: Show/hide sections based on data availability
- **Supplementary content**: Related items, contextual tips, user-generated content
- Template review checklist:
  - Each page must read as a standalone, valuable resource
  - No "mad-libs" patterns (just swapping city/product names in identical text)
  - Dynamic sections must add genuine information, not just keyword variations

## URL Pattern Strategy

### Common Patterns
- `/tools/[tool-name]`: Tool/product directory pages
- `/[city]/[service]`: Location + service pages
- `/integrations/[platform]`: Integration landing pages
- `/glossary/[term]`: Definition/reference pages
- `/templates/[template-name]`: Downloadable template pages

### URL Rules
- Lowercase, hyphenated slugs derived from data
- Logical hierarchy reflecting site architecture
- No duplicate slugs; enforce uniqueness at generation time
- Keep URLs under 100 characters
- No query parameters for primary content URLs
- Consistent trailing slash usage (match existing site pattern)

## Internal Linking Automation

- **Hub/spoke model**: Category hub pages linking to individual programmatic pages
- **Related items**: Auto-link to 3-5 related pages based on data attributes
- **Breadcrumbs**: Generate BreadcrumbList schema from URL hierarchy
- **Cross-linking**: Link between programmatic pages sharing attributes (same category, same city, same feature)
- **Anchor text**: Use descriptive, varied anchor text. Avoid exact-match keyword repetition
- Link density: 3-5 internal links per 1000 words (match seo-content guidelines)

## Thin Content Safeguards

### Quality Gates

| Metric | Threshold | Action |
|--------|-----------|--------|
| Pages without content review | 100+ | ⚠ WARNING: require content audit before publishing |
| Pages without justification | 500+ | 🛑 HARD STOP: require explicit user approval and thin content audit |
| Unique content per page | <40% | ❌ Flag as thin content (likely penalty risk) |
| Word count per page | <300 | ⚠ Flag for review (may lack sufficient value) |

### Scaled Content Abuse: Enforcement Context (2025-2026)

Google's Scaled Content Abuse policy (introduced March 2024) saw major enforcement escalation in 2025:

- **June 2025:** Wave of manual actions targeting websites with AI-generated content at scale
- **August 2025:** SpamBrain spam update enhanced pattern detection for AI-generated link schemes and content farms
- **Result:** Google reported 45% reduction in low-quality, unoriginal content in search results post-March 2024 enforcement

**Enhanced quality gates for programmatic pages:**
- **Content differentiation:** ≥30-40% of content must be genuinely unique between any two programmatic pages (not just city/keyword string replacement)
- **Human review:** Minimum 5-10% sample review of generated pages before publishing
- **Progressive rollout:** Publish in batches of 50-100 pages. Monitor indexing and rankings for 2-4 weeks before expanding. Never publish 500+ programmatic pages simultaneously without explicit quality review.
- **Standalone value test:** Each page should pass: "Would this page be worth publishing even if no other similar pages existed?"
- **Site reputation abuse:** If publishing programmatic content under a high-authority domain (not your own), this may trigger site reputation abuse penalties. Google began enforcing this aggressively in November 2024.

> **Recommendation:** The WARNING gate at `<40% unique content` remains appropriate. Consider a HARD STOP at `<30%` unique content to prevent scaled content abuse risk.

### Safe Programmatic Pages (OK at scale)
✅ Integration pages (with real setup docs, API details, screenshots)
✅ Template/tool pages (with downloadable content, usage instructions)
✅ Glossary pages (200+ word definitions with examples, related terms)
✅ Product pages (unique specs, reviews, comparison data)
✅ Data-driven pages (unique statistics, charts, analysis per record)

### Penalty Risk (avoid at scale)
❌ Location pages with only city name swapped in identical text
❌ "Best [tool] for [industry]" without industry-specific value
❌ "[Competitor] alternative" without real comparison data
❌ AI-generated pages without human review and unique value-add
❌ Pages where >60% of content is shared template boilerplate

### Uniqueness Calculation
Unique content % = (words unique to this page) / (total words on page) × 100

Measure against all other pages in the programmatic set. Shared headers, footers, and navigation are excluded from the calculation. Template boilerplate text IS included.

## Canonical Strategy

- Every programmatic page must have a self-referencing canonical tag
- Parameter variations (sort, filter, pagination) canonical to the base URL
- Paginated series: canonical to page 1 or use rel=next/prev
- If programmatic pages overlap with manual pages, the manual page is canonical
- No canonical to a different domain unless intentional cross-domain setup

## Sitemap Integration

- Auto-generate sitemap entries for all programmatic pages
- Split at 50,000 URLs per sitemap file (protocol limit)
- Use sitemap index if multiple sitemap files needed
- `<lastmod>` reflects actual data update timestamp (not generation time)
- Exclude noindexed programmatic pages from sitemap
- Register sitemap in robots.txt
- Update sitemap dynamically as new records are added to data source

## Index Bloat Prevention

- **Noindex low-value pages**: Pages that don't meet quality gates
- **Pagination**: Noindex paginated results beyond page 1 (or use rel=next/prev)
- **Faceted navigation**: Noindex filtered views, canonical to base category
- **Crawl budget**: For sites with >10k programmatic pages, monitor crawl stats in Search Console
- **Thin page consolidation**: Merge records with insufficient data into aggregated pages
- **Regular audits**: Monthly review of indexed page count vs intended count

## Output

### Programmatic SEO Score: XX/100

### Assessment Summary
| Category | Status | Score |
|----------|--------|-------|
| Data Quality | ✅/⚠/❌ | XX/100 |
| Template Uniqueness | ✅/⚠/❌ | XX/100 |
| URL Structure | ✅/⚠/❌ | XX/100 |
| Internal Linking | ✅/⚠/❌ | XX/100 |
| Thin Content Risk | ✅/⚠/❌ | XX/100 |
| Index Management | ✅/⚠/❌ | XX/100 |

### Critical Issues (fix immediately)
### High Priority (fix within 1 week)
### Medium Priority (fix within 1 month)
### Low Priority (backlog)

### Recommendations
- Data source improvements
- Template modifications
- URL pattern adjustments
- Quality gate compliance actions

## Error Handling

| Scenario | Action |
|----------|--------|
| URL unreachable | Report connection error with status code. Suggest verifying URL accessibility and checking for authentication requirements. |
| No programmatic pages detected | Inform user that no template-generated or data-driven page patterns were found. Suggest checking if pages use client-side rendering or if the URL points to the correct section. |
| Thin content threshold exceeded | Trigger quality gate warning. Report the unique content percentage and flag pages below 40% uniqueness. Require user acknowledgment before proceeding. |
| Quality gate violation | Halt analysis at the HARD STOP threshold (500+ pages without justification or <30% unique content). Present findings and require explicit user approval to continue. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-schema
description: >
  Detect, validate, and generate Schema.org structured data. JSON-LD format
  preferred. Use when user says "schema", "structured data", "rich results",
  "JSON-LD", or "markup".
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
  - Write
---

# Schema Markup Analysis & Generation

## When to Use
- Use when detecting, validating, or generating Schema.org structured data.
- Use when the user asks about JSON-LD, rich results, or markup opportunities.
- Use when schema validation is the main task, rather than a broader SEO audit.

## Detection

1. Scan page source for JSON-LD `<script type="application/ld+json">`
2. Check for Microdata (`itemscope`, `itemprop`)
3. Check for RDFa (`typeof`, `property`)
4. Always recommend JSON-LD as primary format (Google's stated preference)

## Validation

- Check required properties per schema type
- Validate against Google's supported rich result types
- Test for common errors:
  - Missing @context
  - Invalid @type
  - Wrong data types
  - Placeholder text
  - Relative URLs (should be absolute)
  - Invalid date formats
- Flag deprecated types (see below)

## Schema Type Status (as of Feb 2026)

Read `references/schema-types.md` for the full list. Key rules:

### ACTIVE (recommend freely):
Organization, LocalBusiness, SoftwareApplication, WebApplication, Product (with Certification markup as of April 2025), ProductGroup, Offer, Service, Article, BlogPosting, NewsArticle, Review, AggregateRating, BreadcrumbList, WebSite, WebPage, Person, ProfilePage, ContactPage, VideoObject, ImageObject, Event, JobPosting, Course, DiscussionForumPosting

### VIDEO & SPECIALIZED (recommend freely):
BroadcastEvent, Clip, SeekToAction, SoftwareSourceCode

See `schema/templates.json` for ready-to-use JSON-LD templates for these types.

> **JSON-LD and JavaScript rendering:** Per Google's December 2025 JS SEO guidance, structured data injected via JavaScript may face delayed processing. For time-sensitive markup (especially Product, Offer), include JSON-LD in the initial server-rendered HTML.

### RESTRICTED (only for specific sites):
- **FAQ**: ONLY for government and healthcare authority sites (restricted Aug 2023)

### DEPRECATED (never recommend):
- **HowTo**: Rich results removed September 2023
- **SpecialAnnouncement**: Deprecated July 31, 2025
- **CourseInfo, EstimatedSalary, LearningVideo**: Retired June 2025
- **ClaimReview**: Retired from rich results June 2025
- **VehicleListing**: Retired from rich results June 2025
- **Practice Problem**: Retired from rich results late 2025
- **Dataset**: Retired from rich results late 2025
- **Book Actions**: Deprecated then reversed, still functional as of Feb 2026 (historical note)

## Generation

When generating schema for a page:
1. Identify page type from content analysis
2. Select appropriate schema type(s)
3. Generate valid JSON-LD with all required + recommended properties
4. Include only truthful, verifiable data. Use placeholders clearly marked for user to fill
5. Validate output before presenting

## Common Schema Templates

### Organization
```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Company Name]",
  "url": "[Website URL]",
  "logo": "[Logo URL]",
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "[Phone]",
    "contactType": "customer service"
  },
  "sameAs": [
    "[Facebook URL]",
    "[LinkedIn URL]",
    "[Twitter URL]"
  ]
}
```

### LocalBusiness
```json
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "[Business Name]",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "[Street]",
    "addressLocality": "[City]",
    "addressRegion": "[State]",
    "postalCode": "[ZIP]",
    "addressCountry": "US"
  },
  "telephone": "[Phone]",
  "openingHours": "Mo-Fr 09:00-17:00",
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": "[Lat]",
    "longitude": "[Long]"
  }
}
```

### Article/BlogPosting
```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Title]",
  "author": {
    "@type": "Person",
    "name": "[Author Name]"
  },
  "datePublished": "[YYYY-MM-DD]",
  "dateModified": "[YYYY-MM-DD]",
  "image": "[Image URL]",
  "publisher": {
    "@type": "Organization",
    "name": "[Publisher]",
    "logo": {
      "@type": "ImageObject",
      "url": "[Logo URL]"
    }
  }
}
```

## Output

- `SCHEMA-REPORT.md`: detection and validation results
- `generated-schema.json`: ready-to-use JSON-LD snippets

### Validation Results
| Schema | Type | Status | Issues |
|--------|------|--------|--------|
| ... | ... | ✅/⚠/❌ | ... |

### Recommendations
- Missing schema opportunities
- Validation fixes needed
- Generated code for implementation

## Error Handling

| Scenario | Action |
|----------|--------|
| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if the page requires authentication. |
| No schema markup found | Report that no JSON-LD, Microdata, or RDFa was detected. Recommend appropriate schema types based on page content analysis. |
| Invalid JSON-LD syntax | Parse and report specific syntax errors (missing brackets, trailing commas, unquoted keys). Provide corrected JSON-LD output. |
| Deprecated schema type detected | Flag the deprecated type with its retirement date. Recommend the current replacement type or advise removal if no replacement exists. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-sitemap
description: >
  Analyze existing XML sitemaps or generate new ones with industry templates.
  Validates format, URLs, and structure. Use when user says "sitemap",
  "generate sitemap", "sitemap issues", or "XML sitemap".
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url or generate]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
  - Write
---

# Sitemap Analysis & Generation

## When to Use
- Use when analyzing an existing XML sitemap or generating a new one.
- Use when the user mentions sitemap issues, sitemap generation, or sitemap validation.
- Use when checking URL coverage, sitemap limits, and sitemap quality rules.

## Mode 1: Analyze Existing Sitemap

### Validation Checks
- Valid XML format
- URL count <50,000 per file (protocol limit)
- All URLs return HTTP 200
- `<lastmod>` dates are accurate (not all identical)
- No deprecated tags: `<priority>` and `<changefreq>` are ignored by Google
- Sitemap referenced in robots.txt
- Compare crawled pages vs sitemap; flag missing pages

### Quality Signals
- Sitemap index file if >50k URLs
- Split by content type (pages, posts, images, videos)
- No non-canonical URLs in sitemap
- No noindexed URLs in sitemap
- No redirected URLs in sitemap
- HTTPS URLs only (no HTTP)

### Common Issues
| Issue | Severity | Fix |
|-------|----------|-----|
| >50k URLs in single file | Critical | Split with sitemap index |
| Non-200 URLs | High | Remove or fix broken URLs |
| Noindexed URLs included | High | Remove from sitemap |
| Redirected URLs included | Medium | Update to final URLs |
| All identical lastmod | Low | Use actual modification dates |
| Priority/changefreq used | Info | Can remove (ignored by Google) |

## Mode 2: Generate New Sitemap

### Process
1. Ask for business type (or auto-detect from existing site)
2. Load industry template from `../seo-plan/assets/` directory
3. Interactive structure planning with user
4. Apply quality gates:
   - ⚠ WARNING at 30+ location pages (require 60%+ unique content)
   - 🛑 HARD STOP at 50+ location pages (require justification)
5. Generate valid XML output
6. Split at 50k URLs with sitemap index
7. Generate STRUCTURE.md documentation

### Safe Programmatic Pages (OK at scale)
✅ Integration pages (with real setup docs)
✅ Template/tool pages (with downloadable content)
✅ Glossary pages (200+ word definitions)
✅ Product pages (unique specs, reviews)
✅ User profile pages (user-generated content)

### Penalty Risk (avoid at scale)
❌ Location pages with only city name swapped
❌ "Best [tool] for [industry]" without industry-specific value
❌ "[Competitor] alternative" without real comparison data
❌ AI-generated pages without human review and unique value

## Sitemap Format

### Standard Sitemap
```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/page</loc>
    <lastmod>2026-02-07</lastmod>
  </url>
</urlset>
```

### Sitemap Index (for >50k URLs)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-pages.xml</loc>
    <lastmod>2026-02-07</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-posts.xml</loc>
    <lastmod>2026-02-07</lastmod>
  </sitemap>
</sitemapindex>
```

## Error Handling

- **URL unreachable**: Report the HTTP status code and suggest checking if the site is live
- **No sitemap found**: Check common locations (/sitemap.xml, /sitemap_index.xml, robots.txt reference) before reporting "not found"
- **Invalid XML format**: Report specific parsing errors with line numbers
- **Rate limiting detected**: Back off and report partial results with a note about retry timing

## Output

### For Analysis
- `VALIDATION-REPORT.md`: analysis results
- Issues list with severity
- Recommendations

### For Generation
- `sitemap.xml` (or split files with index)
- `STRUCTURE.md`: site architecture documentation
- URL count and organization summary

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-snippet-hunter
description: Formats content to be eligible for featured snippets and SERP features. Creates snippet-optimized content blocks based on best practices. Use PROACTIVELY for question-based content.
risk: none
source: community
date_added: '2026-02-27'
---

## Use this skill when

- Working on seo snippet hunter tasks or workflows
- Needing guidance, best practices, or checklists for seo snippet hunter

## Do not use this skill when

- The task is unrelated to seo snippet hunter
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

You are a featured snippet optimization specialist formatting content for position zero potential.

## Focus Areas

- Featured snippet content formatting
- Question-answer structure
- Definition optimization
- List and step formatting
- Table structure for comparisons
- Concise, direct answers
- FAQ content optimization

## Snippet Types & Formats

**Paragraph Snippets (40-60 words):**
- Direct answer in opening sentence
- Question-based headers
- Clear, concise definitions
- No unnecessary words

**List Snippets:**
- Numbered steps (5-8 items)
- Bullet points for features
- Clear header before list
- Concise descriptions

**Table Snippets:**
- Comparison data
- Specifications
- Structured information
- Clean formatting

## Snippet Optimization Strategy

1. Format content for snippet eligibility
2. Create multiple snippet formats
3. Place answers near content beginning
4. Use questions as headers
5. Provide immediate, clear answers
6. Include relevant context

## Approach

1. Identify questions in provided content
2. Determine best snippet format
3. Create snippet-optimized blocks
4. Format answers concisely
5. Structure surrounding context
6. Suggest FAQ schema markup
7. Create multiple answer variations

## Output

**Snippet Package:**
```markdown
## [Exact Question from SERP]

[40-60 word direct answer paragraph with keyword in first sentence. Clear, definitive response that fully answers the query.]

### Supporting Details:
- Point 1 (enriching context)
- Point 2 (related entity)
- Point 3 (additional value)
```

**Deliverables:**
- Snippet-optimized content blocks
- PAA question/answer pairs
- Competitor snippet analysis
- Format recommendations (paragraph/list/table)
- Schema markup (FAQPage, HowTo)
- Position tracking targets
- Content placement strategy

**Advanced Tactics:**
- Jump links for long content
- FAQ sections for PAA dominance
- Comparison tables for products
- Step-by-step with images
- Video timestamps for snippets
- Voice search optimization

**Platform Implementation:**
- WordPress: FAQ block setup
- Static sites: Structured content components
- Schema.org markup templates

Focus on clear, direct answers. Format content to maximize featured snippet eligibility.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-structure-architect
description: Analyzes and optimizes content structure including header hierarchy, suggests schema markup, and internal linking opportunities. Creates search-friendly content organization.
risk: safe
source: community
date_added: '2026-02-27'
---

## Use this skill when

- Working on seo structure architect tasks or workflows
- Needing guidance, best practices, or checklists for seo structure architect

## Do not use this skill when

- The task is unrelated to seo structure architect
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

You are a content structure specialist analyzing and improving information architecture.

## Focus Areas

- Header tag hierarchy (H1-H6) analysis
- Content organization and flow
- Schema markup suggestions
- Internal linking opportunities
- Table of contents structure
- Content depth assessment
- Logical information flow

## Header Tag Best Practices

**SEO Guidelines:**
- One H1 per page matching main topic
- H2s for main sections with variations
- H3s for subsections with related terms
- Maintain logical hierarchy
- Natural keyword integration

## Siloing Strategy

1. Create topical theme clusters
2. Establish parent/child relationships
3. Build contextual internal links
4. Maintain relevance within silos
5. Cross-link only when highly relevant

## Schema Markup Priority

**High-Impact Schemas:**
- Article/BlogPosting
- FAQ Schema
- HowTo Schema
- Review/AggregateRating
- Organization/LocalBusiness
- BreadcrumbList

## Approach

1. Analyze provided content structure
2. Evaluate header hierarchy
3. Identify structural improvements
4. Suggest internal linking opportunities
5. Recommend appropriate schema types
6. Assess content organization
7. Format for featured snippet potential

## Output

**Structure Blueprint:**
```
H1: Primary Keyword Focus
├── H2: Major Section (Secondary KW)
│   ├── H3: Subsection (LSI)
│   └── H3: Subsection (Entity)
└── H2: Major Section (Related KW)
```

**Deliverables:**
- Header hierarchy outline
- Silo/cluster map visualization
- Internal linking matrix
- Schema markup JSON-LD code
- Breadcrumb implementation
- Table of contents structure
- Jump link recommendations

**Technical Implementation:**
- WordPress: TOC plugin config + schema plugin setup
- Astro/Static: Component hierarchy + structured data
- URL structure recommendations
- XML sitemap priorities

**Snippet Optimization:**
- List format for featured snippets
- Table structure for comparisons
- Definition boxes for terms
- Step-by-step for processes

Focus on logical flow and scannable content. Create clear information hierarchy for users and search engines.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-technical
description: "Audit technical SEO across crawlability, indexability, security, URLs, mobile, Core Web Vitals, structured data, JavaScript rendering, and related platform signals like robots.txt and AI crawler access."
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
---

# Technical SEO Audit

## When to Use
- Use when the user wants a technical SEO review focused on crawlability, indexability, performance, or rendering.
- Use when auditing robots.txt, canonicalization, JavaScript SEO, Core Web Vitals, or AI crawler access.
- Use when the task is infrastructure- and implementation-oriented rather than content-focused.

## Categories

### 1. Crawlability
- robots.txt: exists, valid, not blocking important resources
- XML sitemap: exists, referenced in robots.txt, valid format
- Noindex tags: intentional vs accidental
- Crawl depth: important pages within 3 clicks of homepage
- JavaScript rendering: check if critical content requires JS execution
- Crawl budget: for large sites (>10k pages), efficiency matters

#### AI Crawler Management

As of 2025-2026, AI companies actively crawl the web to train models and power AI search. Managing these crawlers via robots.txt is a critical technical SEO consideration.

**Known AI crawlers:**

| Crawler | Company | robots.txt token | Purpose |
|---------|---------|-----------------|---------|
| GPTBot | OpenAI | `GPTBot` | Model training |
| ChatGPT-User | OpenAI | `ChatGPT-User` | Real-time browsing |
| ClaudeBot | Anthropic | `ClaudeBot` | Model training |
| PerplexityBot | Perplexity | `PerplexityBot` | Search index + training |
| Bytespider | ByteDance | `Bytespider` | Model training |
| Google-Extended | Google | `Google-Extended` | Gemini training (NOT search) |
| CCBot | Common Crawl | `CCBot` | Open dataset |

**Key distinctions:**
- Blocking `Google-Extended` prevents Gemini training use but does NOT affect Google Search indexing or AI Overviews (those use `Googlebot`)
- Blocking `GPTBot` prevents OpenAI training but does NOT prevent ChatGPT from citing your content via browsing (`ChatGPT-User`)
- ~3-5% of websites now use AI-specific robots.txt rules

**Example, selective AI crawler blocking:**
```
# Allow search indexing, block AI training crawlers
User-agent: GPTBot
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: Bytespider
Disallow: /

# Allow all other crawlers (including Googlebot for search)
User-agent: *
Allow: /
```

**Recommendation:** Consider your AI visibility strategy before blocking. Being cited by AI systems drives brand awareness and referral traffic. Cross-reference the `seo-geo` skill for full AI visibility optimization.

### 2. Indexability
- Canonical tags: self-referencing, no conflicts with noindex
- Duplicate content: near-duplicates, parameter URLs, www vs non-www
- Thin content: pages below minimum word counts per type
- Pagination: rel=next/prev or load-more pattern
- Hreflang: correct for multi-language/multi-region sites
- Index bloat: unnecessary pages consuming crawl budget

### 3. Security
- HTTPS: enforced, valid SSL certificate, no mixed content
- Security headers:
  - Content-Security-Policy (CSP)
  - Strict-Transport-Security (HSTS)
  - X-Frame-Options
  - X-Content-Type-Options
  - Referrer-Policy
- HSTS preload: check preload list inclusion for high-security sites

### 4. URL Structure
- Clean URLs: descriptive, hyphenated, no query parameters for content
- Hierarchy: logical folder structure reflecting site architecture
- Redirects: no chains (max 1 hop), 301 for permanent moves
- URL length: flag >100 characters
- Trailing slashes: consistent usage

### 5. Mobile Optimization
- Responsive design: viewport meta tag, responsive CSS
- Touch targets: minimum 48x48px with 8px spacing
- Font size: minimum 16px base
- No horizontal scroll
- Mobile-first indexing: Google indexes mobile version. **Mobile-first indexing is 100% complete as of July 5, 2024.** Google now crawls and indexes ALL websites exclusively with the mobile Googlebot user-agent.

### 6. Core Web Vitals
- **LCP** (Largest Contentful Paint): target <2.5s
- **INP** (Interaction to Next Paint): target <200ms
  - INP replaced FID on March 12, 2024. FID was fully removed from all Chrome tools (CrUX API, PageSpeed Insights, Lighthouse) on September 9, 2024. Do NOT reference FID anywhere.
- **CLS** (Cumulative Layout Shift): target <0.1
- Evaluation uses 75th percentile of real user data
- Use PageSpeed Insights API or CrUX data if MCP available

### 7. Structured Data
- Detection: JSON-LD (preferred), Microdata, RDFa
- Validation against Google's supported types
- See seo-schema skill for full analysis

### 8. JavaScript Rendering
- Check if content visible in initial HTML vs requires JS
- Identify client-side rendered (CSR) vs server-side rendered (SSR)
- Flag SPA frameworks (React, Vue, Angular) that may cause indexing issues
- Verify dynamic rendering setup if applicable

#### JavaScript SEO: Canonical & Indexing Guidance (December 2025)

Google updated its JavaScript SEO documentation in December 2025 with critical clarifications:

1. **Canonical conflicts:** If a canonical tag in raw HTML differs from one injected by JavaScript, Google may use EITHER one. Ensure canonical tags are identical between server-rendered HTML and JS-rendered output.
2. **noindex with JavaScript:** If raw HTML contains `<meta name="robots" content="noindex">` but JavaScript removes it, Google MAY still honor the noindex from raw HTML. Serve correct robots directives in the initial HTML response.
3. **Non-200 status codes:** Google does NOT render JavaScript on pages returning non-200 HTTP status codes. Any content or meta tags injected via JS on error pages will be invisible to Googlebot.
4. **Structured data in JavaScript:** Product, Article, and other structured data injected via JS may face delayed processing. For time-sensitive structured data (especially e-commerce Product markup), include it in the initial server-rendered HTML.

**Best practice:** Serve critical SEO elements (canonical, meta robots, structured data, title, meta description) in the initial server-rendered HTML rather than relying on JavaScript injection.

### 9. IndexNow Protocol
- Check if site supports IndexNow for Bing, Yandex, Naver
- Supported by search engines other than Google
- Recommend implementation for faster indexing on non-Google engines

## Output

### Technical Score: XX/100

### Category Breakdown
| Category | Status | Score |
|----------|--------|-------|
| Crawlability | pass/warn/fail | XX/100 |
| Indexability | pass/warn/fail | XX/100 |
| Security | pass/warn/fail | XX/100 |
| URL Structure | pass/warn/fail | XX/100 |
| Mobile | pass/warn/fail | XX/100 |
| Core Web Vitals | pass/warn/fail | XX/100 |
| Structured Data | pass/warn/fail | XX/100 |
| JS Rendering | pass/warn/fail | XX/100 |
| IndexNow | pass/warn/fail | XX/100 |

### Critical Issues (fix immediately)
### High Priority (fix within 1 week)
### Medium Priority (fix within 1 month)
### Low Priority (backlog)

## DataForSEO Integration (Optional)

If DataForSEO MCP tools are available, use `on_page_instant_pages` for real page analysis (status codes, page timing, broken links, on-page checks), `on_page_lighthouse` for Lighthouse audits (performance, accessibility, SEO scores), and `domain_analytics_technologies_domain_technologies` for technology stack detection.

## Error Handling

| Scenario | Action |
|----------|--------|
| URL unreachable | Report connection error with status code. Suggest verifying URL, checking DNS resolution, and confirming the site is publicly accessible. |
| robots.txt not found | Note that no robots.txt was detected at the root domain. Recommend creating one with appropriate directives. Continue audit on remaining categories. |
| HTTPS not configured | Flag as a critical issue. Report whether HTTP is served without redirect, mixed content exists, or SSL certificate is missing/expired. |
| Core Web Vitals data unavailable | Note that CrUX data is not available (common for low-traffic sites). Suggest using Lighthouse lab data as a proxy and recommend increasing traffic before re-testing. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: sequence-psychologist
description: "One sentence - what this skill does and when to invoke it"
risk: safe
source: community
date_added: "2026-04-04"
---
You are a **Behavioral Psychologist specializing in persuasion sequencing and relationship psychology**. Your task is to design email nurture sequences and multi-touch communication flows using psychological principles of curiosity loops, reciprocity, commitment, and emotional pacing.

## When to Use
- Use when an email, onboarding, or sales sequence needs a better step-by-step persuasion arc.
- Use when each touchpoint should prepare the next instead of repeating the same appeal.

## CONTEXT GATHERING

Before designing a sequence, establish:

1. **The Target Human** - psychographic profile, awareness stage, and trust stage.
2. **The Objective** - the conversion or relationship milestone.
3. **The Output** - email sequence architecture or nurture flow.
4. **Constraints** - channel, cadence, and ethical limits.

If the sequence goal is unclear, ask before proceeding.

## PSYCHOLOGICAL FRAMEWORK: COMMITMENT-PACING SEQUENCE

### Mechanism
People move when messages create a manageable emotional arc: curiosity, recognition, trust, small commitments, then a larger ask. Email sequences work when they respect autonomy, use reciprocity carefully, and let the reader feel progressive momentum rather than pressure (Cialdini; Zeigarnik effect; mere exposure; Stawarz et al., 2015; Gillison et al., 2019; Sheeran et al., 2020).

### Execution Steps

**Step 1 - Define the emotional arc**
Map each email to a single emotional objective.
*Research basis: persuasive sequences work better when they pace emotion and cognition instead of repeating the same ask (Cialdini; narrative sequence research).*

**Step 2 - Open the loop**
Create a curiosity gap or unresolved question the next email will answer.
*Research basis: open loops increase attention when the promised payoff is real (Zeigarnik effect; curiosity research).*

**Step 3 - Give before asking**
Use useful content, insight, or relief before the ask.
*Research basis: reciprocity and liking increase receptivity when the audience has already received value (Cialdini).*

**Step 4 - Escalate commitment gradually**
Move from low-friction responses to higher-friction decisions.
*Research basis: foot-in-the-door and consistency effects increase compliance when the steps are coherent (Cialdini; behavioral change research).*

**Step 5 - End with a clean decision**
Make the final email simple, concrete, and autonomy-preserving.
*Research basis: choice clarity reduces avoidance and supports follow-through (Fogg; Lavoie & Quick, 2013).*

## DECISION MATRIX

### Variable: sequence length
- If short -> use a compact 3-5 email arc.
- If medium -> use education, proof, objection handling, then ask.
- If long -> use a staged relationship arc with repeated value delivery.

### Variable: audience readiness
- If cold -> lead with relevance and low-pressure value.
- If warm -> blend proof with identity and urgency.
- If hot -> move quickly to the decision.

### Variable: trust stage
- If low -> keep asks small and proof high.
- If moderate -> alternate value and ask.
- If high -> compress and simplify.

## FAILURE MODES - DO NOT DO THESE

**Failure Mode 1**
- Agents typically: send sales-only emails.
- Why it fails psychologically: the sequence feels extractive.
- Instead: give value before asking.

**Failure Mode 2**
- Agents typically: make every email try to close.
- Why it fails psychologically: constant pressure produces fatigue.
- Instead: assign one emotional job per email.

**Failure Mode 3**
- Agents typically: let open loops drag on too long.
- Why it fails psychologically: curiosity turns into annoyance.
- Instead: resolve the loop on schedule.

## ETHICAL GUARDRAILS

This skill must:
- Respect consent and unsubscribe norms.
- Avoid manipulative spam tactics.
- Preserve autonomy throughout the sequence.

The line between persuasion and manipulation is pacing a real relationship toward a real decision versus pressuring people through endless unresolved suspense and hidden agendas. Never cross it.

## SKILL CHAINING

Before invoking this skill, the agent should have completed:
- [ ] `@customer-psychographic-profiler`
- [ ] `@awareness-stage-mapper`
- [ ] `@objection-preemptor`

This skill's output feeds into:
- [ ] `@subject-line-psychologist`
- [ ] `@copywriting-psychologist`
- [ ] `@pitch-psychologist`

## OUTPUT QUALITY CHECK

Before finalizing output, the agent asks:
- [ ] Did I assign one emotional job per email?
- [ ] Did I pace commitment gradually?
- [ ] Did I give value before asking?
- [ ] Did I resolve open loops on time?
- [ ] Does the sequence feel respectful and useful?

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: server-management
description: "Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands."
risk: safe
source: community
date_added: "2026-02-27"
---

# Server Management

> Server management principles for production operations.
> **Learn to THINK, not memorize commands.**

---

## 1. Process Management Principles

### Tool Selection

| Scenario | Tool |
|----------|------|
| **Node.js app** | PM2 (clustering, reload) |
| **Any app** | systemd (Linux native) |
| **Containers** | Docker/Podman |
| **Orchestration** | Kubernetes, Docker Swarm |

### Process Management Goals

| Goal | What It Means |
|------|---------------|
| **Restart on crash** | Auto-recovery |
| **Zero-downtime reload** | No service interruption |
| **Clustering** | Use all CPU cores |
| **Persistence** | Survive server reboot |

---

## 2. Monitoring Principles

### What to Monitor

| Category | Key Metrics |
|----------|-------------|
| **Availability** | Uptime, health checks |
| **Performance** | Response time, throughput |
| **Errors** | Error rate, types |
| **Resources** | CPU, memory, disk |

### Alert Severity Strategy

| Level | Response |
|-------|----------|
| **Critical** | Immediate action |
| **Warning** | Investigate soon |
| **Info** | Review daily |

### Monitoring Tool Selection

| Need | Options |
|------|---------|
| Simple/Free | PM2 metrics, htop |
| Full observability | Grafana, Datadog |
| Error tracking | Sentry |
| Uptime | UptimeRobot, Pingdom |

---

## 3. Log Management Principles

### Log Strategy

| Log Type | Purpose |
|----------|---------|
| **Application logs** | Debug, audit |
| **Access logs** | Traffic analysis |
| **Error logs** | Issue detection |

### Log Principles

1. **Rotate logs** to prevent disk fill
2. **Structured logging** (JSON) for parsing
3. **Appropriate levels** (error/warn/info/debug)
4. **No sensitive data** in logs

---

## 4. Scaling Decisions

### When to Scale

| Symptom | Solution |
|---------|----------|
| High CPU | Add instances (horizontal) |
| High memory | Increase RAM or fix leak |
| Slow response | Profile first, then scale |
| Traffic spikes | Auto-scaling |

### Scaling Strategy

| Type | When to Use |
|------|-------------|
| **Vertical** | Quick fix, single instance |
| **Horizontal** | Sustainable, distributed |
| **Auto** | Variable traffic |

---

## 5. Health Check Principles

### What Constitutes Healthy

| Check | Meaning |
|-------|---------|
| **HTTP 200** | Service responding |
| **Database connected** | Data accessible |
| **Dependencies OK** | External services reachable |
| **Resources OK** | CPU/memory not exhausted |

### Health Check Implementation

- Simple: Just return 200
- Deep: Check all dependencies
- Choose based on load balancer needs

---

## 6. Security Principles

| Area | Principle |
|------|-----------|
| **Access** | SSH keys only, no passwords |
| **Firewall** | Only needed ports open |
| **Updates** | Regular security patches |
| **Secrets** | Environment vars, not files |
| **Audit** | Log access and changes |

---

## 7. Troubleshooting Priority

When something's wrong:

1. **Check if running** (process status)
2. **Check logs** (error messages)
3. **Check resources** (disk, memory, CPU)
4. **Check network** (ports, DNS)
5. **Check dependencies** (database, APIs)

---

## 8. Anti-Patterns

| ❌ Don't | ✅ Do |
|----------|-------|
| Run as root | Use non-root user |
| Ignore logs | Set up log rotation |
| Skip monitoring | Monitor from day one |
| Manual restarts | Auto-restart config |
| No backups | Regular backup schedule |

---

> **Remember:** A well-managed server is boring. That's the goal.

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: service-mesh-expert
description: "Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observability integration, and multi-cluster mesh con"
risk: safe
source: community
date_added: "2026-02-27"
---

# Service Mesh Expert

Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observability integration, and multi-cluster mesh configurations. Use PROACTIVELY for service mesh architecture, zero-trust networking, or microservices communication patterns.

## Do not use this skill when

- The task is unrelated to service mesh expert
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

## Capabilities

- Istio and Linkerd installation, configuration, and optimization
- Traffic management: routing, load balancing, circuit breaking, retries
- mTLS configuration and certificate management
- Service mesh observability with distributed tracing
- Multi-cluster and multi-cloud mesh federation
- Progressive delivery with canary and blue-green deployments
- Security policies and authorization rules

## Use this skill when

- Implementing service-to-service communication in Kubernetes
- Setting up zero-trust networking with mTLS
- Configuring traffic splitting for canary deployments
- Debugging service mesh connectivity issues
- Implementing rate limiting and circuit breakers
- Setting up cross-cluster service discovery

## Workflow

1. Assess current infrastructure and requirements
2. Design mesh topology and traffic policies
3. Implement security policies (mTLS, AuthorizationPolicy)
4. Configure observability (metrics, traces, logs)
5. Set up traffic management rules
6. Test failover and resilience patterns
7. Document operational runbooks

## Best Practices

- Start with permissive mode, gradually enforce strict mTLS
- Use namespaces for policy isolation
- Implement circuit breakers before they're needed
- Monitor mesh overhead (latency, resource usage)
- Keep sidecar resources appropriately sized
- Use destination rules for consistent load balancing

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: service-mesh-observability
description: "Complete guide to observability patterns for Istio, Linkerd, and service mesh deployments."
risk: critical
source: community
date_added: "2026-02-27"
---

# Service Mesh Observability

Complete guide to observability patterns for Istio, Linkerd, and service mesh deployments.

## Do not use this skill when

- The task is unrelated to service mesh observability
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

## Use this skill when

- Setting up distributed tracing across services
- Implementing service mesh metrics and dashboards
- Debugging latency and error issues
- Defining SLOs for service communication
- Visualizing service dependencies
- Troubleshooting mesh connectivity

## Core Concepts

### 1. Three Pillars of Observability

```
┌─────────────────────────────────────────────────────┐
│                  Observability                       │
├─────────────────┬─────────────────┬─────────────────┤
│     Metrics     │     Traces      │      Logs       │
│                 │                 │                 │
│ • Request rate  │ • Span context  │ • Access logs   │
│ • Error rate    │ • Latency       │ • Error details │
│ • Latency P50   │ • Dependencies  │ • Debug info    │
│ • Saturation    │ • Bottlenecks   │ • Audit trail   │
└─────────────────┴─────────────────┴─────────────────┘
```

### 2. Golden Signals for Mesh

| Signal | Description | Alert Threshold |
|--------|-------------|-----------------|
| **Latency** | Request duration P50, P99 | P99 > 500ms |
| **Traffic** | Requests per second | Anomaly detection |
| **Errors** | 5xx error rate | > 1% |
| **Saturation** | Resource utilization | > 80% |

## Templates

### Template 1: Istio with Prometheus & Grafana

```yaml
# Install Prometheus
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus
  namespace: istio-system
data:
  prometheus.yml: |
    global:
      scrape_interval: 15s
    scrape_configs:
      - job_name: 'istio-mesh'
        kubernetes_sd_configs:
          - role: endpoints
            namespaces:
              names:
                - istio-system
        relabel_configs:
          - source_labels: [__meta_kubernetes_service_name]
            action: keep
            regex: istio-telemetry
---
# ServiceMonitor for Prometheus Operator
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: istio-mesh
  namespace: istio-system
spec:
  selector:
    matchLabels:
      app: istiod
  endpoints:
    - port: http-monitoring
      interval: 15s
```

### Template 2: Key Istio Metrics Queries

```promql
# Request rate by service
sum(rate(istio_requests_total{reporter="destination"}[5m])) by (destination_service_name)

# Error rate (5xx)
sum(rate(istio_requests_total{reporter="destination", response_code=~"5.."}[5m]))
  / sum(rate(istio_requests_total{reporter="destination"}[5m])) * 100

# P99 latency
histogram_quantile(0.99,
  sum(rate(istio_request_duration_milliseconds_bucket{reporter="destination"}[5m]))
  by (le, destination_service_name))

# TCP connections
sum(istio_tcp_connections_opened_total{reporter="destination"}) by (destination_service_name)

# Request size
histogram_quantile(0.99,
  sum(rate(istio_request_bytes_bucket{reporter="destination"}[5m]))
  by (le, destination_service_name))
```

### Template 3: Jaeger Distributed Tracing

```yaml
# Jaeger installation for Istio
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    enableTracing: true
    defaultConfig:
      tracing:
        sampling: 100.0  # 100% in dev, lower in prod
        zipkin:
          address: jaeger-collector.istio-system:9411
---
# Jaeger deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: jaeger
  namespace: istio-system
spec:
  selector:
    matchLabels:
      app: jaeger
  template:
    metadata:
      labels:
        app: jaeger
    spec:
      containers:
        - name: jaeger
          image: jaegertracing/all-in-one:1.50
          ports:
            - containerPort: 5775   # UDP
            - containerPort: 6831   # Thrift
            - containerPort: 6832   # Thrift
            - containerPort: 5778   # Config
            - containerPort: 16686  # UI
            - containerPort: 14268  # HTTP
            - containerPort: 14250  # gRPC
            - containerPort: 9411   # Zipkin
          env:
            - name: COLLECTOR_ZIPKIN_HOST_PORT
              value: ":9411"
```

### Template 4: Linkerd Viz Dashboard

```bash
# Install Linkerd viz extension
linkerd viz install | kubectl apply -f -

# Access dashboard
linkerd viz dashboard

# CLI commands for observability
# Top requests
linkerd viz top deploy/my-app

# Per-route metrics
linkerd viz routes deploy/my-app --to deploy/backend

# Live traffic inspection
linkerd viz tap deploy/my-app --to deploy/backend

# Service edges (dependencies)
linkerd viz edges deployment -n my-namespace
```

### Template 5: Grafana Dashboard JSON

```json
{
  "dashboard": {
    "title": "Service Mesh Overview",
    "panels": [
      {
        "title": "Request Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "sum(rate(istio_requests_total{reporter=\"destination\"}[5m])) by (destination_service_name)",
            "legendFormat": "{{destination_service_name}}"
          }
        ]
      },
      {
        "title": "Error Rate",
        "type": "gauge",
        "targets": [
          {
            "expr": "sum(rate(istio_requests_total{response_code=~\"5..\"}[5m])) / sum(rate(istio_requests_total[5m])) * 100"
          }
        ],
        "fieldConfig": {
          "defaults": {
            "thresholds": {
              "steps": [
                {"value": 0, "color": "green"},
                {"value": 1, "color": "yellow"},
                {"value": 5, "color": "red"}
              ]
            }
          }
        }
      },
      {
        "title": "P99 Latency",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.99, sum(rate(istio_request_duration_milliseconds_bucket{reporter=\"destination\"}[5m])) by (le, destination_service_name))",
            "legendFormat": "{{destination_service_name}}"
          }
        ]
      },
      {
        "title": "Service Topology",
        "type": "nodeGraph",
        "targets": [
          {
            "expr": "sum(rate(istio_requests_total{reporter=\"destination\"}[5m])) by (source_workload, destination_service_name)"
          }
        ]
      }
    ]
  }
}
```

### Template 6: Kiali Service Mesh Visualization

```yaml
# Kiali installation
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali
  namespace: istio-system
spec:
  auth:
    strategy: anonymous  # or openid, token
  deployment:
    accessible_namespaces:
      - "**"
  external_services:
    prometheus:
      url: http://prometheus.istio-system:9090
    tracing:
      url: http://jaeger-query.istio-system:16686
    grafana:
      url: http://grafana.istio-system:3000
```

### Template 7: OpenTelemetry Integration

```yaml
# OpenTelemetry Collector for mesh
apiVersion: v1
kind: ConfigMap
metadata:
  name: otel-collector-config
data:
  config.yaml: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
      zipkin:
        endpoint: 0.0.0.0:9411

    processors:
      batch:
        timeout: 10s

    exporters:
      jaeger:
        endpoint: jaeger-collector:14250
        tls:
          insecure: true
      prometheus:
        endpoint: 0.0.0.0:8889

    service:
      pipelines:
        traces:
          receivers: [otlp, zipkin]
          processors: [batch]
          exporters: [jaeger]
        metrics:
          receivers: [otlp]
          processors: [batch]
          exporters: [prometheus]
---
# Istio Telemetry v2 with OTel
apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  tracing:
    - providers:
        - name: otel
      randomSamplingPercentage: 10
```

## Alerting Rules

```yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: mesh-alerts
  namespace: istio-system
spec:
  groups:
    - name: mesh.rules
      rules:
        - alert: HighErrorRate
          expr: |
            sum(rate(istio_requests_total{response_code=~"5.."}[5m])) by (destination_service_name)
            / sum(rate(istio_requests_total[5m])) by (destination_service_name) > 0.05
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "High error rate for {{ $labels.destination_service_name }}"

        - alert: HighLatency
          expr: |
            histogram_quantile(0.99, sum(rate(istio_request_duration_milliseconds_bucket[5m]))
            by (le, destination_service_name)) > 1000
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "High P99 latency for {{ $labels.destination_service_name }}"

        - alert: MeshCertExpiring
          expr: |
            (certmanager_certificate_expiration_timestamp_seconds - time()) / 86400 < 7
          labels:
            severity: warning
          annotations:
            summary: "Mesh certificate expiring in less than 7 days"
```

## Best Practices

### Do's
- **Sample appropriately** - 100% in dev, 1-10% in prod
- **Use trace context** - Propagate headers consistently
- **Set up alerts** - For golden signals
- **Correlate metrics/traces** - Use exemplars
- **Retain strategically** - Hot/cold storage tiers

### Don'ts
- **Don't over-sample** - Storage costs add up
- **Don't ignore cardinality** - Limit label values
- **Don't skip dashboards** - Visualize dependencies
- **Don't forget costs** - Monitor observability costs

## Resources

- [Istio Observability](https://istio.io/latest/docs/tasks/observability/)
- [Linkerd Observability](https://linkerd.io/2.14/features/dashboard/)
- [OpenTelemetry](https://opentelemetry.io/)
- [Kiali](https://kiali.io/)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: setup-help
description: "Walk a user through setup or installation one step at a time with the remaining steps visible."
category: productivity
risk: safe
source: community
source_repo: davidondrej/skills
source_type: community
date_added: "2026-07-07"
author: davidondrej
tags: [setup, onboarding, installation]
tools: [claude, codex]
license: "MIT"
license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
disable-model-invocation: true
---

# setup-help

## When to Use

- Use when the user asks to set up, install, configure, or get something working step by step.
- Use when the setup has multiple steps and benefits from one-at-a-time guidance.

Guide the user through any setup, one step at a time, in plain English.

## Response format (every single response)

1. **Current step** — ONE atomic action. A single click, field, or command — not a checklist. 1–2 lines max. If it needs sub-steps, it's too big: split it and push the rest into "Still remaining". Plain English.
2. A `----` divider.
3. **Still remaining** — a numbered list of the setup steps left after this one. Max 8 items, ever.

Repeat this format for every response until setup is done.

## Rules

- Before the first step, build a complete canonical checklist from the user's outline, repo/docs, current screen, and any discovered prerequisites.
- The **Still remaining** list must never exceed 8 items — more is overwhelming. Track ALL unfinished checklist items internally; if more than 8 remain, show the nearest steps individually and merge the later ones into broader phase-level items so the list stays at 8 or fewer. Never silently drop a required step from internal tracking.
- If a new required step is discovered mid-setup, add it to **Still remaining** immediately in the correct order.
- Before every response, audit the current step plus **Still remaining** against the canonical checklist. If any unfinished step is missing, fix the list before replying.
- Only give instructions for the current step. Do not jump ahead.
- Keep it concise. Short sentences. No filler.
- After the user finishes a step, move the next "remaining" item up to "Current step".
- Update the "Still remaining" list each time as steps get done.
- When nothing remains, say setup is complete instead of showing the list.

## Limitations

- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.


---
name: setup-matt-pocock-skills
description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
disable-model-invocation: true
category: "development"
risk: "safe"
source: "community"
source_repo: "mattpocock/skills"
source_type: "community"
date_added: "2026-06-19"
author: "Matt Pocock"
license: "MIT"
license_source: "https://github.com/mattpocock/skills/blob/main/LICENSE"
tags:
  - engineering
  - workflow
  - coding-agents
tools:
  - claude-code
  - codex-cli
  - cursor
---

# Setup Matt Pocock's Skills

## When to Use

Use when this workflow matches the user request: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

_Source: [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)._

Scaffold the per-repo configuration that the engineering skills assume:

- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
- **Triage labels** — the strings used for the five canonical triage roles
- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

## Process

### 1. Explore

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
- `docs/adr/` and any `src/*/docs/adr/` directories
- `docs/agents/` — does this skill's prior output already exist?
- `.scratch/` — sign that a local-markdown issue tracker convention is already in use

### 2. Present findings and ask

Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.

Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.

**Section A — Issue tracker.**

> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.

Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:

- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose

If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:

> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.

- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.

**Section B — Triage label vocabulary.**

> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.

The five canonical roles:

- `needs-triage` — maintainer needs to evaluate
- `needs-info` — waiting on reporter
- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
- `ready-for-human` — needs human implementation
- `wontfix` — will not be actioned

Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.

**Section C — Domain docs.**

> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.

Confirm the layout:

- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).

### 3. Confirm and edit

Show the user a draft of:

- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`

Let them edit before writing.

### 4. Write

**Pick the file to edit:**

- If `CLAUDE.md` exists, edit it.
- Else if `AGENTS.md` exists, edit it.
- If neither exists, ask the user which one to create — don't pick for them.

Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.

If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.

The block:

```markdown
## Agent skills

### Issue tracker

[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
```

Then write the three docs files using the seed templates in this skill folder as a starting point:

- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
- [triage-labels.md](./triage-labels.md) — label mapping
- [domain.md](./domain.md) — domain doc consumer rules + layout

For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.

### 5. Done

Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

## Limitations

- Requires the upstream tool, account, API key, or local setup when the workflow names one.
- Does not authorize destructive, production, paid, or external-message actions without explicit user approval.
- Validate generated artifacts or recommendations against the user's real sources before treating them as final.


---
name: sexual-health-analyzer
description: Sexual Health Analyzer
risk: safe
source: community
---

# 性健康分析技能

## When to Use
- 需要分析性健康记录、筛查情况、避孕效果或相关风险模式时使用。
- 任务涉及 IIEF-5 评分、STD 筛查管理、性活动统计或跨模块关联分析。
- 用户请求性健康趋势报告或结构化风险分析时使用。

## 技能概述

本技能提供全面的性健康数据分析功能,包括IIEF-5评分分析、STD筛查管理、避孕效果评估、性活动统计以及与用药、慢性病、心理、营养、运动等模块的深度关联分析。

## 医学免责声明

⚠ **重要提示**:本技能提供的数据分析和建议仅供参考,不构成医学诊断或治疗建议。

- 所有性健康问题应由专业医生诊断和治疗
- 分析结果不能替代专业医疗检查
- 紧急情况应立即就医
- 请遵循医生的专业建议

## 核心功能

### 1. IIEF-5 评分分析

#### 1.1 交互式问卷

**问卷结构**:
- 5个问题,每个问题0-5分
- 总分范围:0-25分
- 评估时间范围:过去6个月

**问题详解**:

**问题1**:勃起信心
- 评估用户对获得和维持勃起的信心程度
- 反映心理因素对性功能的影响
- 低分可能提示表现焦虑

**问题2**:勃起获得
- 评估受到性刺激时获得勃起的能力
- 反映血管和神经功能
- 低分可能提示器质性ED

**问题3**:插入能力
- 评估勃起硬度是否足够插入
- 临床相关的勃起质量指标
- 低分通常需要医疗干预

**问题4**:勃起维持
- 评估完成性交过程中维持勃起的能力
- 反映静脉闭塞功能
- 与问题3联合分析可确定ED类型

**问题5**:性交满意度
- 评估性交过程的主观满意度
- 受硬度、持续时间、伴侣满意度等多因素影响
- 综合性功能的最终指标

#### 1.2 ED严重程度评估

| 总分 | ED严重程度 | 临床意义 | 推荐措施 |
|------|-----------|----------|----------|
| 22-25 | 正常 | 勃起功能良好 | 继续健康生活方式 |
| 17-21 | 轻度ED | 轻度功能障碍 | 生活方式调整,定期评估 |
| 12-16 | 轻中度ED | 中度功能障碍 | 建议就医评估 |
| 8-11 | 中度ED | 明显功能障碍 | 需要医疗干预 |
| 5-7 | 重度ED | 严重功能障碍 | 全面医疗评估和治疗 |

#### 1.3 趋势分析

**分析维度**:
- 总分变化趋势(改善/稳定/恶化)
- 各问题得分变化模式
- ED严重程度变化轨迹
- 治疗干预效果评估

**输出内容**:
- IIEF-5评分时间序列图表
- 改善/恶化趋势标识
- 变化速率计算
- 与其他健康指标的相关性分析

#### 1.4 风险因素分析

**生理因素**:
- 年龄:每增加10年,ED风险增加约20%
- 糖尿病:ED风险增加3倍
- 心血管疾病:ED风险增加2-3倍
- 高血压:ED风险增加1.5-2倍
- 肥胖:BMI>30增加ED风险
- 荷尔蒙异常:低睾酮水平

**心理因素**:
- 表现焦虑
- 抑郁症状
- 压力水平
- 伴侣关系问题

**生活方式因素**:
- 吸烟:增加ED风险1.5倍
- 酗酒:长期影响性功能
- 缺乏运动:心血管健康下降
- 睡眠质量:影响荷尔蒙分泌

**药物因素**:
- 抗抑郁药(SSRIs等)
- 抗高血压药(β受体阻滞剂、噻嗪类)
- 抗精神病药
- 激素类药物

#### 1.5 改善建议

**生活方式干预**:
- **戒烟**:显著改善血管健康
- **限酒**:男性每日<2杯
- **减重**:BMI控制在18.5-24.9
- **规律运动**:
  - 每周150分钟中等强度有氧运动
  - 每周2-3次力量训练
  - 每日盆底肌训练(凯格尔运动)
- **健康饮食**:
  - 地中海饮食模式
  - 增加水果蔬菜摄入
  - 减少饱和脂肪和加工食品
  - 适量坚果和全谷物

**心理干预**:
- 性治疗师咨询
- 认知行为疗法
- 伴侣治疗
- 压力管理技术(冥想、瑜伽)

**医疗干预**:
- PDE5抑制剂(需医生处方)
- 睾酮补充疗法(如睾酮低)
- 真空勃起装置
- 阴茎注射疗法
- 手术治疗(血管手术、假体)

### 2. STD 筛查管理

#### 2.1 筛查项目详解

**HIV (艾滋病病毒)**:
- **检测方法**:血液检测(抗体+抗原组合)
- **窗口期**:1-3个月
- **高危人群**:MSM、性工作者、多性伴侣者
- **筛查频率**:高风险每3-6个月,一般风险每年

**梅毒 (Syphilis)**:
- **检测方法**:血液检测(RPR/VDRL+TPPA确认)
- **窗口期**:10-90天
- **分期**:一期、二期、潜伏期、三期
- **治疗**:青霉素有效,早期治愈率高

**衣原体 (Chlamydia)**:
- **检测方法**:尿液检测或拭子
- **窗口期**:1-3周
- **特点**:常无症状,但可导致不孕
- **治疗**:阿奇霉素或多西环素

**淋病 (Gonorrhea)**:
- **检测方法**:尿液检测或拭子
- **窗口期**:1-14天
- **特点**:男性症状明显,女性常无症状
- **治疗**:头孢曲松+阿奇霉素(考虑耐药性)

**HPV (人乳头瘤病毒)**:
- **检测方法**:拭子DNA检测
- **窗口期**:1个月-数年
- **特点**:非常常见,大多数自愈
- **高危型**:HPV 16/18与宫颈癌相关
- **预防**:HPV疫苗有效

**乙肝 (Hepatitis B)**:
- **检测方法**:血液检测(HBsAg+抗HBs)
- **窗口期**:1-6个月
- **预防**:乙肝疫苗有效
- **治疗**:抗病毒药物

**生殖器疱疹 (Herpes)**:
- **检测方法**:拭子PCR或血液抗体
- **窗口期**:2-12天
- **特点**:无治愈方法,可控制症状
- **治疗**:抗病毒药物(阿昔洛韦等)

#### 2.2 风险评估

**行为风险因素**:
- 性伴侣数量(>3个/年 = 高风险)
- 保护措施使用频率
- 性伴侣的STD状况
- 性工作或性工作者接触史
- MSM人群
- 注射吸毒史

**动态风险评分**:
- **低风险**(<10分):单一稳定伴侣,坚持保护
- **中风险**(10-30分):2-3个性伴侣,偶尔保护
- **高风险**(30-50分):多性伴侣,保护不一致
- **极高风险**(>50分):性工作者,MSM,无保护

#### 2.3 筛查频率建议

基于风险等级的个性化筛查计划:

| 风险等级 | HIV/梅毒 | 衣原体/淋病 | HPV | 乙肝 |
|----------|---------|------------|-----|------|
| 低风险 | 每1-2年 | 每1-2年 | 每3年 | 已免疫无需检测 |
| 中风险 | 每年 | 每年 | 每3年 | 每1-2年 |
| 高风险 | 每3-6月 | 每3-6月 | 每年 | 每年 |
| 极高风险 | 每3月 | 每3月 | 每6月 | 每6月 |

#### 2.4 阳性结果管理

**立即行动**:
- 开始治疗(遵医嘱)
- 通知性伴侣并进行检测
- 暂停性生活或严格保护
- 避免传播风险

**治疗追踪**:
- 治疗后检测以确认治愈
- 监测药物副作用
- 评估治疗依从性
- 记录治疗过程和结果

**预防再感染**:
- 性伴侣同时治疗
- 治愈后重新开始保护措施
- 定期复查
- 风险教育

#### 2.5 统计分析

- 筛查频率趋势
- 阳性率变化
- 感染类型分布
- 治愈率统计
- 再感染率分析

### 3. 避孕管理

#### 3.1 避孕方法详细分析

**避孕套 (男/女)**:
- **典型使用有效率**:85%
- **完美使用有效率**:98%
- **优点**:
  - 唯一防孕又防病的方法
  - 无激素副作用
  - 易于获取
  - 即刻起效
- **缺点**:
  - 需要每次使用
  - 可能影响性快感
  - 可能破裂或滑落
- **满意度影响因素**:
  - 尺寸是否合适
  - 润滑剂使用
  - 佩戴技巧
  - 品牌偏好

**口服避孕药**:
- **典型使用有效率**:91%
- **完美使用有效率**:99.7%
- **类型**:
  - 复方避孕药(雌激素+孕激素)
  - 单纯孕激素药(适合哺乳期)
  - 24/4方案 vs 21/7方案
- **优点**:
  - 高效避孕
  - 可调节月经周期
  - 改善痤疮和经前综合症
  - 降低卵巢癌和子宫内膜癌风险
- **缺点**:
  - 需要每日服用
  - 激素副作用
  - 不适合吸烟女性>35岁
  - 不能预防STD
- **副作用追踪**:
  - 恶心、乳房胀痛
  - 情绪变化
  - 性欲改变
  - 体重变化
  - 月经间期出血

**宫内节育器 (IUD)**:
- **有效率**:99%+
- **类型**:
  - 铜IUD(10-12年)
  - 左炔诺孕酮IUD(3-8年)
- **优点**:
  - 长效可逆
  - 即刻起效
  - 可随时取出
  - 激素IUD可减轻月经
- **缺点**:
  - 需要医生放置
  - 放置时不适
  - 可能增加月经量和痛经(铜IUD)
  - 不能预防STD
- **副作用追踪**:
  - 放置后疼痛
  - 月经变化
  - 点滴出血
  - 穿孔风险(罕见)

**皮下埋植**:
- **有效率**:99%+
- **持续时间**:3-5年
- **优点**:
  - 长效可逆
  - 放置简单
  - 可随时取出
  - 隐蔽性好
- **缺点**:
  - 激素副作用
  - 可能导致月经紊乱
  - 放置部位可能瘢痕
  - 不能预防STD

**避孕针**:
- **典型使用有效率**:94%
- **完美使用有效率**:99%+
- **频率**:每3个月一次
- **优点**:
  - 不需要每日服用
  - 隐蔽性好
- **缺点**:
  - 需要定期注射
  - 体重增加常见
  - 生育力恢复可能延迟
  - 不能预防STD

**体外射精**:
- **典型使用有效率**:78%
- **完美使用有效率**:96%
- **风险**:
  - 需要高度自控
  - 射精前可能有精子溢出
  - 增加性焦虑
  - 不能预防STD
- **不推荐**:失败率较高

**安全期法**:
- **典型使用有效率**:76-88%
- **完美使用有效率**:95-99%
- **方法**:
  - 日历法
  - 基础体温法
  - 宫颈黏液法
  - 症状体温法
- **风险**:
  - 月经不规律时不可靠
  - 需要严格记录
  - 排卵期可能不规律
  - 不能预防STD
- **不推荐**:失败率较高

**结扎手术**:
- **有效率**:99%+
- **类型**:
  - 输精管结扎(男性)
  - 输卵管结扎(女性)
- **优点**:
  - 永久性避孕
  - 高效
  - 无激素影响
- **缺点**:
  - 通常不可逆
  - 需要手术
  - 术后恢复期
  - 不能预防STD

#### 3.2 效果评估

**避孕失败率分析**:
- Pearl指数(每100女性年失败数)
- 典型使用 vs 完美使用差异
- 使用错误分析
- 失败原因追踪

**满意度评分**:
- 易用性(1-10分)
- 舒适度(1-10分)
- 对性生活影响(1-10分)
- 副作用可接受度(1-10分)
- 整体满意度(1-10分)

#### 3.3 副作用追踪

**荷尔蒙相关副作用**:
- 月经模式改变
- 情绪波动
- 性欲变化
- 体重变化
- 乳房胀痛

**非荷尔蒙副作用**:
- 疼痛或不适(IUD)
- 过敏反应(避孕套)
- 疤痕形成(埋植、结扎)

**严重副作用**:
- 血栓栓塞风险(激素类)
- 异位妊娠风险(IUD失败时)
- 感染风险(IUD放置)

#### 3.4 切换历史

**切换原因分析**:
- 副作用不耐受
- 效果不满意
- 生活方式改变
- 健康状况变化
- 经济原因
- 伴侣偏好

**切换建议**:
- 基于副作用史选择
- 考虑年龄和生育计划
- 评估健康风险因素
- 伴侣讨论

### 4. 性活动日志

#### 4.1 记录内容

**基础信息**:
- 日期和时间
- 活动类型(性交、口交、手交等)
- 持续时间
- 伴侣类型(固定、新伴侣等)

**保护措施**:
- 避孕方法(避孕套、口服避孕药等)
- 是否正确使用
- 是否破损或失败

**主观体验**:
- 满意度评分(1-10分)
- 性欲水平(1-10分)
- 疼痛或不适(有/无,程度)
- 是否达到高潮

**特殊情况**:
- 异常症状
- 避孕失败
- 意外情况
- 备注

#### 4.2 隐私保护

**数据标记**:
- 敏感数据标记
- 加密建议
- 访问权限设置
- 数据匿名化选项

**用户控制**:
- 可选功能,完全自主决定
- 可随时删除记录
- 可选择性导出数据
- 就医时可选择性展示

#### 4.3 统计分析

**频率统计**:
- 每周/每月/每年性活动次数
- 频率变化趋势
- 与年龄/关系阶段对比

**满意度分析**:
- 平均满意度评分
- 满意度趋势变化
- 影响满意度的因素分析
- 与IIEF-5/FSFI评分相关性

**保护措施统计**:
- 保护措施使用率
- 各避孕方法使用频率
- 避孕失败次数和原因
- 保护措施与满意度关系

**模式识别**:
- 性活动时间模式
- 与生理周期关系(女性)
- 与情绪/压力相关性
- 与药物使用相关性

### 5. 关联分析

#### 5.1 与用药模块的关联

**PDE5抑制剂效果追踪**:
- 药物名称和剂量
- 服用频率和时机
- 效果评分(1-10分)
- 副作用记录
- 效果随时间变化
- 与IIEF-5评分相关性
- 成本效益分析

**抗抑郁药对性功能的影响**:
- 药物类别(SSRIs, SNRIs, TCAs等)
- 性功能副作用类型
- 严重程度评估
- 发生时间(用药初期/长期)
- 与性欲、勃起、高潮的关系
- 换药或加药建议

**降压药对性功能的影响**:
- 药物类别(β受体阻滞剂、噻嗪类等)
- ED发生率
- 性欲影响
- 替代药物选择建议

**激素类药物**:
- 睾酮补充治疗
- 雌激素/孕激素
- 性功能影响
- 剂量调整建议

**其他药物**:
- 抗精神病药
- 抗组胺药
- 化疗药物
- 对性功能的影响

#### 5.2 与慢性病模块的关联

**糖尿病与ED**:
- **病理机制**:
  - 血管内皮损伤
  - 神经病变
  - 荷尔蒙异常
- **血糖控制与ED关系**:
  - HbA1c <7%:ED风险较低
  - HbA1c 7-9%:中度风险
  - HbA1c >9%:高度风险
- **糖尿病病程与ED**:
  - <5年:ED风险增加2倍
  - 5-10年:ED风险增加3倍
  - >10年:ED风险增加4-5倍
- **管理建议**:
  - 严格控制血糖
  - 定期ED筛查
  - 早期干预
  - 综合管理(血压、血脂)

**高血压与性功能**:
- **病理机制**:
  - 血管损伤
  - 内皮功能障碍
- **降压药的影响**:
  - β受体阻滞剂:增加ED风险
  - 噻嗪类利尿剂:可能引起ED
  - ACEI/ARB:中性或有益
  - 钙通道阻滞剂:中性
- **管理建议**:
  - 控制血压至目标值
  - 选择对性功能影响小的药物
  - 定期评估性功能

**心血管疾病与性功能**:
- **ED作为预警信号**:
  - ED可能早于心绞痛症状2-3年
  - ED是心血管疾病的独立预测因子
  - 建议ED患者进行心血管评估
- **性生活安全评估**:
  - 心功能分级评估
  - 运动耐量评估
  - 药物使用(硝酸酯类药物禁用PDE5抑制剂)
- **心肌梗死后性生活指导**:
  - 通常2-4周后可恢复
  - 逐步增加强度
  - 监测症状

**肥胖与性功能**:
- **影响机制**:
  - 荷尔蒙变化(睾酮降低,雌激素升高)
  - 血管内皮功能障碍
  - 心理因素(身体意象)
- **减重效果**:
  - 减重5-10%可显著改善
  - 减重后IIEF-5评分平均提高3-5分
  - 运动结合饮食效果最佳

#### 5.3 与心理健康模块的关联

**焦虑与性功能**:
- **表现焦虑**:
  - 担心性表现
  - 害怕不能满足伴侣
  - 导致勃起困难或早泄
- **广泛性焦虑**:
  - 性欲下降
  - 难以放松享受
  - 分心难以集中
- **干预**:
  - 认知行为疗法
  - 放松训练
  - 感觉集中训练

**抑郁与性功能**:
- **抑郁症状与性欲**:
  - 性欲丧失常见症状
  - 性兴趣显著下降
  - 可能是最早出现的症状之一
- **抗抑郁药的双重影响**:
  - 改善抑郁可能恢复性欲
  - 但药物本身可能引起性功能障碍
- **管理策略**:
  - 选择对性功能影响小的抗抑郁药(安非他酮)
  - 加用药物(如丁螺环酮)
  - 剂量调整
  - 心理治疗

**创伤后应激障碍(PTSD)**:
- 性回避
- 性唤起困难
- 闪回影响
- 需要专业创伤治疗

**身体意象**:
- 对自己身体的不满
- 影响性自信
- 导致回避亲密关系
- 身体积极性训练

**伴侣关系**:
- 关系质量与性生活满意度高度相关
- 沟通问题影响性满足
- 冲突未解决影响性欲
- 伴侣治疗可能有益

#### 5.4 与营养模块的关联

**关键营养素**:

**锌**:
- **功能**:睾酮合成必需元素
- **缺乏表现**:性欲下降,ED
- **推荐摄入**:男性11mg/天
- **食物来源**:牡蛎、牛肉、南瓜子、腰果
- **补充建议**:如缺乏可补充15-30mg/天

**精氨酸**:
- **功能**:促进一氧化氮生成,改善血流
- **对ED的潜在益处**:可能轻度改善勃起功能
- **推荐剂量**:3-5g/天
- **食物来源**:坚果、种子、肉类、鱼类
- **注意事项**:可能与某些药物相互作用

**维生素D**:
- **功能**:支持睾酮合成
- **缺乏表现**:低维生素D水平与ED相关
- **目标水平**:血清25(OH)D >30 ng/mL
- **补充建议**:如缺乏可补充1000-2000 IU/天

**镁**:
- **功能**:支持睾酮合成,改善血流
- **推荐摄入**:男性400-420mg/天
- **食物来源**:绿叶蔬菜、坚果、全谷物
- **补充建议**:如缺乏可补充200-400mg/天

**Omega-3脂肪酸**:
- **功能**:改善心血管健康,间接改善性功能
- **推荐摄入**:1-2g EPA+DHA/天
- **食物来源**:深海鱼类、亚麻籽、核桃

**抗氧化物质**:
- **功能**:保护血管内皮
- **重要抗氧化剂**:维生素C、维生素E、硒、番茄红素
- **食物来源**:水果、蔬菜、坚果

**膳食模式**:

**地中海饮食**:
- **特点**:高水果蔬菜、全谷物、橄榄油、鱼类
- **研究证据**:改善ED,降低心血管风险
- **机制**:改善血管健康,降低炎症

**限制**:
- **饱和脂肪**:减少红肉和全脂乳制品
- **反式脂肪**:避免加工食品
- **添加糖**:控制糖分摄入,特别是糖尿病患者
- **酒精**:男性每日<2杯

**营养状况评估**:
- 评估营养素缺乏
- 提供个性化营养建议
- 推荐补充剂(如需要)
- 监测营养改善效果

#### 5.5 与运动模块的关联

**有氧运动**:
- **类型**:快走、跑步、游泳、骑行
- **推荐量**:每周150分钟中等强度
- **对ED的益处**:
  - 改善心血管健康
  - 增强血流
  - 降低ED风险约40%
  - IIEF-5评分平均提高2-4分
- **机制**:
  - 改善内皮功能
  - 增加一氧化氮生物利用度
  - 降低血压和血糖

**力量训练**:
- **类型**:重量训练、抗阻训练
- **推荐量**:每周2-3次
- **对性功能的益处**:
  - 提高睾酮水平
  - 增强肌肉力量和耐力
  - 改善身体意象和自信
- **注意事项**:
  - 避免过度训练
  - 充分恢复

**盆底肌训练(凯格尔运动)**:
- **功能**:
  - 增强勃起硬度和维持能力
  - 改善射精控制
  - 对ED和早泄均有益
- **方法**:
  - 收缩盆底肌肉(如中断排尿)
  - 保持5秒,放松5秒
  - 每日3组,每组10-15次
- **效果**:
  - 6-12周后显著改善
  - IIEF-5评分平均提高3-5分

**瑜伽**:
- **益处**:
  - 改善身体意象和性自信
  - 增强柔韧性和身体意识
  - 降低压力和焦虑
  - 某些体式增强盆底肌
- **推荐**:
  - 每周2-3次
  - 结合冥想和呼吸练习

**运动与性欲**:
- 适度运动提高性欲
- 过度运动可能降低性欲(女运动员三联征)
- 找到平衡点

**运动处方**:
- 基于年龄、健康状况、兴趣
- 渐进式增加
- 结合有氧、力量、柔韧性训练
- 盆底肌训练作为补充

### 6. 风险评估

#### 6.1 ED风险评分

**风险因素加权**:

| 风险因素 | 权重 | 评分 |
|----------|------|------|
| 年龄 | 15% | <40:0, 40-49:1, 50-59:2, 60+:3 |
| 糖尿病 | 20% | 无:0, 控制:1, 未控制:3 |
| 心血管疾病 | 15% | 无:0, 稳定:1, 不稳定:3 |
| 高血压 | 10% | 无:0, 控制:1, 未控制:2 |
| 吸烟 | 10% | 从不:0, 已戒烟:1, 吸烟:2 |
| 酗酒 | 5% | 无:0, 偶尔:1, 经常:2 |
| 肥胖 | 10% | BMI<25:0, 25-30:1, >30:2 |
| 缺乏运动 | 5% | 规律:0, 偶尔:1, 缺乏:2 |
| 压力/焦虑 | 5% | 无:0, 轻度:1, 中重度:2 |
| 药物副作用 | 5% | 无:0, 轻度:1, 明显:2 |

**风险等级**:
- **低风险**(0-20分):ED可能性低
- **中风险**(21-40分):ED风险增加
- **高风险**(41-60分):ED高度可能
- **极高风险**(>60分):几乎肯定有ED

#### 6.2 STD风险评分

**行为因素**:

| 风险因素 | 评分 |
|----------|------|
| 性伴侣数量 | 单一:0, 2-3:5, 4-10:15, >10:30 |
| 保护措施使用 | 总是:0, 通常:5, 有时:15, 从不:30 |
| 性伴侣类型 | 固定:0, 新伴侣/偶尔:10, 性工作者:30 |
| MSM | 否:0, 是:20 |
| 已知伴侣感染 | 无:0, 有:50 |
| 注射吸毒 | 否:0, 是:30 |
| 既往STD史 | 无:0, 1次:10, >1次:20 |

**风险等级**:
- **低风险**(0-10分):STD可能性低
- **中风险**(11-30分):STD风险增加
- **高风险**(31-50分):STD高度可能
- **极高风险**(>50分):需要立即筛查

### 7. 个性化建议

#### 7.1 基于IIEF-5评分的建议

**正常(22-25分)**:
- 继续健康生活方式
- 定期评估(每年)
- 预防性措施

**轻度ED(17-21分)**:
- 生活方式干预优先
- 压力管理
- 限制酒精和戒烟
- 3-6个月后重新评估

**轻中度ED(12-16分)**:
- 生活方式干预
- 考虑PDE5抑制剂
- 心理因素评估
- 建议就医

**中度ED(8-11分)**:
- 积极医疗干预
- PDE5抑制剂
- 考虑其他治疗选项
- 心理咨询

**重度ED(5-7分)**:
- 全面医疗评估
- 多学科治疗
- 可能需要专科转诊
- 伴侣参与

#### 7.2 基于风险评估的建议

**高风险ED**:
- 定期筛查(每3-6个月)
- 积极控制危险因素
- 预防性干预
- 早期治疗

**高风险STD**:
- 频繁筛查(每3个月)
- PrEP(暴露前预防)考虑
- 疫苗接种(HPV、乙肝)
- 风险降低咨询

#### 7.3 生活方式处方

**运动处方**:
- 有氧运动:每周150分钟
- 力量训练:每周2-3次
- 盆底肌训练:每日
- 灵活性训练:每周2-3次

**饮食处方**:
- 地中海饮食模式
- 增加水果蔬菜至5-9份/天
- 全谷物替代精制谷物
- 每周2次深海鱼类
- 限制加工食品和添加糖

**行为处方**:
- 戒烟计划
- 限酒:男性<2杯/天
- 睡眠改善:7-9小时/天
- 压力管理:每日放松练习
- 体重管理:BMI 18.5-24.9

### 8. 预警系统

#### 8.1 定期检查提醒

**IIEF-5评估**:
- 正常:每年
- 轻度ED:每6个月
- 中度以上:每3-6个月

**STD筛查**:
- 基于风险等级个性化设置
- 高风险:每3个月
- 一般风险:每年
- 低风险:每1-2年

**性健康检查**:
- 40岁以下:每1-2年
- 40岁以上:每年
- 慢性病患者:每年

#### 8.2 问题预警

**IIEF-5评分下降**:
- 连续2次评估下降>3分
- 一个月内下降>5分
- ED严重程度升级

**STD高风险行为**:
- 无保护性行为增加
- 性伴侣数量增加
- 已知暴露后未筛查

**避孕失效**:
- 避孕套破裂>2次/月
- 漏服避孕药>2次/月
- IUD位置异常

#### 8.3 趋势预警

**性欲显著下降**:
- 持续>3个月
- 影响生活质量
- 伴侣关系受影响

**满意度持续降低**:
- 平均满意度<5分
- 持续下降趋势
- 需要专业评估

## 使用场景

### 场景1:定期性健康评估

**用户请求**:分析最近6个月的性健康状况

**分析流程**:
1. 读取最近6个月的所有性健康记录
2. 分析IIEF-5评分变化趋势
3. 评估STD筛查历史
4. 检查避孕方法有效性
5. 分析用药效果
6. 评估生活方式因素

**输出内容**:
- IIEF-5评分变化曲线
- ED严重程度变化
- 主要风险因素
- 改善建议
- 下次检查时间

### 场景2:ED诊断辅助

**用户请求**:我最近勃起困难,IIEF-5评分15分,什么原因?

**分析流程**:
1. 检索最近IIEF-5评分历史
2. 分析用药记录
3. 评估慢性病控制情况
4. 检查心理状态记录
5. 分析生活方式因素
6. 识别主要原因

**输出内容**:
- ED严重程度:轻中度
- 主要风险因素(如糖尿病控制不佳)
- 可修改因素(如吸烟、缺乏运动)
- 药物影响分析
- 个性化改善计划

### 场景3:避孕方法选择

**用户请求**:我想换一种避孕方法,当前口服避孕药有副作用

**分析流程**:
1. 评估当前避孕方法满意度和副作用
2. 分析健康史和风险因素
3. 考虑年龄和生育计划
4. 对比各种避孕方法的优缺点
5. 识别适合的替代方案

**输出内容**:
- 当前方法问题分析
- 适合的替代方案
- 各方案优缺点对比
- 推荐方案及理由
- 切换时间建议

### 场景4:STD风险评估

**用户请求**:我最近有新伴侣,需要STD筛查吗?

**分析流程**:
1. 评估性行为模式
2. 识别风险因素
3. 计算风险评分
4. 确定需要筛查的项目
5. 设置筛查时间表

**输出内容**:
- 当前风险等级
- 推荐筛查项目
- 筛查时间建议
- 风险降低措施
- 随访计划

### 场景5:多学科联合分析

**用户请求**:我有糖尿病,这对性功能有什么影响?

**分析流程**:
1. 读取糖尿病管理数据
2. 分析血糖控制情况
3. 评估性功能状态
4. 分析两者关联性
5. 评估并发症风险
6. 生成联合管理建议

**输出内容**:
- 糖尿病对性功能的影响机制
- 当前血糖控制与ED风险
- 综合管理策略
- 监测指标建议
- 生活方式干预重点

## 数据分析方法

### 定量分析
- 统计描述(均值、中位数、标准差)
- 趋势分析(线性回归、移动平均)
- 相关性分析(Pearson/Spearman相关)
- 风险评分计算(多因素加权)

### 定性分析
- 文本描述分析
- 症状模式识别
- 主诉内容分类
- 满意度评估

### 可视化输出
- IIEF-5评分时间序列图表
- ED严重程度变化图
- STD筛查历史时间线
- 避孕方法效果对比
- 性活动频率统计图
- 风险因素雷达图

## 质量保证

### 数据验证
- 检查数据完整性
- 验证数据一致性
- 识别异常值
- 处理缺失数据

### 结果验证
- 医学逻辑检查
- 与临床指南对照
- 专家审查(如有)
- 用户反馈收集

### 持续改进
- 定期更新分析算法
- 引入新的科学证据
- 优化用户体验
- 扩展功能范围

## 参考资源

### 临床指南
- WHO性健康指南
- EAU(欧洲泌尿协会)ED指南
- AUA(美国泌尿协会)性功能障碍指南
- CDCSTD筛查和治疗指南
- 中华医学会男科学指南

### 评估工具
- IIEF-5(国际勃起功能指数-5)
- FSFI(女性性功能指数)
- SHEF(性健康评估框架)

### 数据源
- 用户记录数据
- 用药模块数据
- 慢性病模块数据
- 心理模块数据
- 营养模块数据
- 运动模块数据

## 局限性

### 系统局限
- 不能替代专业医疗检查
- 不能进行实验室检测
- 不能进行体格检查
- 分析结果受数据质量影响

### 数据局限
- 依赖用户记录准确性
- 可能存在遗漏记录
- 主观评估存在偏差
- 时间跨度可能不足

### 建议局限
- 不能考虑所有个体因素
- 不能预测所有并发症
- 需要结合临床判断
- 不能保证100%准确性

## 未来扩展

### 计划功能
- AI辅助诊断
- 个性化治疗方案生成
- 伴侣健康关联分析
- 生殖健康追踪(生育规划)
- 性教育模块

### 研究方向
- 机器学习预测模型
- 基因风险分析
- 个性化预防策略
- 远程医疗集成

---

**版本**: v1.0.0
**最后更新**: 2025-01-06
**维护者**: WellAlly Tech

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.