Optimize skill files for AI agent use with progressive disclosure
- Fix marketplace.json: add 2 missing skills (content-strategy, product-marketing-context) - Refactor 10 skills over 500 lines to use references/ folders: - email-sequence: 926 → 291 lines - social-content: 809 → 276 lines - competitor-alternatives: 750 → 253 lines - pricing-strategy: 712 → 226 lines - programmatic-seo: 628 → 235 lines - referral-program: 604 → 239 lines - schema-markup: 598 → 175 lines - free-tool-strategy: 576 → 176 lines - paywall-upgrade-cro: 572 → 224 lines - marketing-ideas: 566 → 165 lines Each skill now has core workflow in SKILL.md (<500 lines) with detailed content in references/ folder for progressive disclosure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Corey Haines
@@ -14,19 +14,11 @@ If `.claude/product-marketing-context.md` exists, read it before asking question
|
||||
|
||||
Before implementing schema, understand:
|
||||
|
||||
1. **Page Type**
|
||||
- What kind of page is this?
|
||||
- What's the primary content?
|
||||
- What rich results are possible?
|
||||
1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?
|
||||
|
||||
2. **Current State**
|
||||
- Any existing schema?
|
||||
- Errors in current implementation?
|
||||
- Which rich results are already appearing?
|
||||
2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?
|
||||
|
||||
3. **Goals**
|
||||
- Which rich results are you targeting?
|
||||
- What's the business value?
|
||||
3. **Goals** - Which rich results are you targeting? What's the business value?
|
||||
|
||||
---
|
||||
|
||||
@@ -56,435 +48,56 @@ Before implementing schema, understand:
|
||||
|
||||
## Common Schema Types
|
||||
|
||||
### Organization
|
||||
**Use for**: Company/brand homepage or about page
|
||||
| Type | Use For | Required Properties |
|
||||
|------|---------|-------------------|
|
||||
| Organization | Company homepage/about | name, url |
|
||||
| WebSite | Homepage (search box) | name, url |
|
||||
| Article | Blog posts, news | headline, image, datePublished, author |
|
||||
| Product | Product pages | name, image, offers |
|
||||
| SoftwareApplication | SaaS/app pages | name, offers |
|
||||
| FAQPage | FAQ content | mainEntity (Q&A array) |
|
||||
| HowTo | Tutorials | name, step |
|
||||
| BreadcrumbList | Any page with breadcrumbs | itemListElement |
|
||||
| LocalBusiness | Local business pages | name, address |
|
||||
| Event | Events, webinars | name, startDate, location |
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- url
|
||||
|
||||
**Recommended properties**:
|
||||
- logo
|
||||
- sameAs (social profiles)
|
||||
- contactPoint
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com",
|
||||
"logo": "https://example.com/logo.png",
|
||||
"sameAs": [
|
||||
"https://twitter.com/example",
|
||||
"https://linkedin.com/company/example",
|
||||
"https://facebook.com/example"
|
||||
],
|
||||
"contactPoint": {
|
||||
"@type": "ContactPoint",
|
||||
"telephone": "+1-555-555-5555",
|
||||
"contactType": "customer service"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSite (with SearchAction)
|
||||
**Use for**: Homepage, enables sitelinks search box
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- url
|
||||
|
||||
**For search box**:
|
||||
- potentialAction with SearchAction
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "WebSite",
|
||||
"name": "Example",
|
||||
"url": "https://example.com",
|
||||
"potentialAction": {
|
||||
"@type": "SearchAction",
|
||||
"target": {
|
||||
"@type": "EntryPoint",
|
||||
"urlTemplate": "https://example.com/search?q={search_term_string}"
|
||||
},
|
||||
"query-input": "required name=search_term_string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Article / BlogPosting
|
||||
**Use for**: Blog posts, news articles
|
||||
|
||||
**Required properties**:
|
||||
- headline
|
||||
- image
|
||||
- datePublished
|
||||
- author
|
||||
|
||||
**Recommended properties**:
|
||||
- dateModified
|
||||
- publisher
|
||||
- description
|
||||
- mainEntityOfPage
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Article",
|
||||
"headline": "How to Implement Schema Markup",
|
||||
"image": "https://example.com/image.jpg",
|
||||
"datePublished": "2024-01-15T08:00:00+00:00",
|
||||
"dateModified": "2024-01-20T10:00:00+00:00",
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": "Jane Doe",
|
||||
"url": "https://example.com/authors/jane"
|
||||
},
|
||||
"publisher": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"logo": {
|
||||
"@type": "ImageObject",
|
||||
"url": "https://example.com/logo.png"
|
||||
}
|
||||
},
|
||||
"description": "A complete guide to implementing schema markup...",
|
||||
"mainEntityOfPage": {
|
||||
"@type": "WebPage",
|
||||
"@id": "https://example.com/schema-guide"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Product
|
||||
**Use for**: Product pages (e-commerce or SaaS)
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- image
|
||||
- offers (with price and availability)
|
||||
|
||||
**Recommended properties**:
|
||||
- description
|
||||
- sku
|
||||
- brand
|
||||
- aggregateRating
|
||||
- review
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
"name": "Premium Widget",
|
||||
"image": "https://example.com/widget.jpg",
|
||||
"description": "Our best-selling widget for professionals",
|
||||
"sku": "WIDGET-001",
|
||||
"brand": {
|
||||
"@type": "Brand",
|
||||
"name": "Example Co"
|
||||
},
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"url": "https://example.com/products/widget",
|
||||
"priceCurrency": "USD",
|
||||
"price": "99.99",
|
||||
"availability": "https://schema.org/InStock",
|
||||
"priceValidUntil": "2024-12-31"
|
||||
},
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.8",
|
||||
"reviewCount": "127"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SoftwareApplication
|
||||
**Use for**: SaaS product pages, app landing pages
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- offers (or free indicator)
|
||||
|
||||
**Recommended properties**:
|
||||
- applicationCategory
|
||||
- operatingSystem
|
||||
- aggregateRating
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "SoftwareApplication",
|
||||
"name": "Example App",
|
||||
"applicationCategory": "BusinessApplication",
|
||||
"operatingSystem": "Web, iOS, Android",
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"price": "0",
|
||||
"priceCurrency": "USD"
|
||||
},
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.6",
|
||||
"ratingCount": "1250"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### FAQPage
|
||||
**Use for**: Pages with frequently asked questions
|
||||
|
||||
**Required properties**:
|
||||
- mainEntity (array of Question/Answer)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "FAQPage",
|
||||
"mainEntity": [
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "What is schema markup?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
|
||||
}
|
||||
},
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "How do I implement schema?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### HowTo
|
||||
**Use for**: Instructional content, tutorials
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- step (array of HowToStep)
|
||||
|
||||
**Recommended properties**:
|
||||
- image
|
||||
- totalTime
|
||||
- estimatedCost
|
||||
- supply/tool
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "HowTo",
|
||||
"name": "How to Add Schema Markup to Your Website",
|
||||
"description": "A step-by-step guide to implementing JSON-LD schema",
|
||||
"totalTime": "PT15M",
|
||||
"step": [
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Choose your schema type",
|
||||
"text": "Identify the appropriate schema type for your page content...",
|
||||
"url": "https://example.com/guide#step1"
|
||||
},
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Write the JSON-LD",
|
||||
"text": "Create the JSON-LD markup following schema.org specifications...",
|
||||
"url": "https://example.com/guide#step2"
|
||||
},
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Add to your page",
|
||||
"text": "Insert the script tag in your page's head section...",
|
||||
"url": "https://example.com/guide#step3"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### BreadcrumbList
|
||||
**Use for**: Any page with breadcrumb navigation
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "BreadcrumbList",
|
||||
"itemListElement": [
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 1,
|
||||
"name": "Home",
|
||||
"item": "https://example.com"
|
||||
},
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 2,
|
||||
"name": "Blog",
|
||||
"item": "https://example.com/blog"
|
||||
},
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 3,
|
||||
"name": "SEO Guide",
|
||||
"item": "https://example.com/blog/seo-guide"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### LocalBusiness
|
||||
**Use for**: Local business location pages
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- address
|
||||
- (Various by business type)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "LocalBusiness",
|
||||
"name": "Example Coffee Shop",
|
||||
"image": "https://example.com/shop.jpg",
|
||||
"address": {
|
||||
"@type": "PostalAddress",
|
||||
"streetAddress": "123 Main Street",
|
||||
"addressLocality": "San Francisco",
|
||||
"addressRegion": "CA",
|
||||
"postalCode": "94102",
|
||||
"addressCountry": "US"
|
||||
},
|
||||
"geo": {
|
||||
"@type": "GeoCoordinates",
|
||||
"latitude": "37.7749",
|
||||
"longitude": "-122.4194"
|
||||
},
|
||||
"telephone": "+1-555-555-5555",
|
||||
"openingHoursSpecification": [
|
||||
{
|
||||
"@type": "OpeningHoursSpecification",
|
||||
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
|
||||
"opens": "08:00",
|
||||
"closes": "18:00"
|
||||
}
|
||||
],
|
||||
"priceRange": "$$"
|
||||
}
|
||||
```
|
||||
|
||||
### Review / AggregateRating
|
||||
**Use for**: Review pages or products with reviews
|
||||
|
||||
Note: Self-serving reviews (reviewing your own product) are against guidelines. Reviews must be from real customers.
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
"name": "Example Product",
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.5",
|
||||
"bestRating": "5",
|
||||
"worstRating": "1",
|
||||
"ratingCount": "523"
|
||||
},
|
||||
"review": [
|
||||
{
|
||||
"@type": "Review",
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": "John Smith"
|
||||
},
|
||||
"datePublished": "2024-01-10",
|
||||
"reviewRating": {
|
||||
"@type": "Rating",
|
||||
"ratingValue": "5"
|
||||
},
|
||||
"reviewBody": "Excellent product, exceeded my expectations..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Event
|
||||
**Use for**: Event pages, webinars, conferences
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- startDate
|
||||
- location (or eventAttendanceMode for online)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Event",
|
||||
"name": "Annual Marketing Conference",
|
||||
"startDate": "2024-06-15T09:00:00-07:00",
|
||||
"endDate": "2024-06-15T17:00:00-07:00",
|
||||
"eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
|
||||
"eventStatus": "https://schema.org/EventScheduled",
|
||||
"location": {
|
||||
"@type": "VirtualLocation",
|
||||
"url": "https://example.com/conference"
|
||||
},
|
||||
"image": "https://example.com/conference.jpg",
|
||||
"description": "Join us for our annual marketing conference...",
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"url": "https://example.com/conference/tickets",
|
||||
"price": "199",
|
||||
"priceCurrency": "USD",
|
||||
"availability": "https://schema.org/InStock",
|
||||
"validFrom": "2024-01-01"
|
||||
},
|
||||
"performer": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company"
|
||||
},
|
||||
"organizer": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)
|
||||
|
||||
---
|
||||
|
||||
## Multiple Schema Types on One Page
|
||||
## Quick Reference
|
||||
|
||||
You can (and often should) have multiple schema types:
|
||||
### Organization (Company Page)
|
||||
Required: name, url
|
||||
Recommended: logo, sameAs (social profiles), contactPoint
|
||||
|
||||
### Article/BlogPosting
|
||||
Required: headline, image, datePublished, author
|
||||
Recommended: dateModified, publisher, description
|
||||
|
||||
### Product
|
||||
Required: name, image, offers (price + availability)
|
||||
Recommended: sku, brand, aggregateRating, review
|
||||
|
||||
### FAQPage
|
||||
Required: mainEntity (array of Question/Answer pairs)
|
||||
|
||||
### BreadcrumbList
|
||||
Required: itemListElement (array with position, name, item)
|
||||
|
||||
---
|
||||
|
||||
## Multiple Schema Types
|
||||
|
||||
You can combine multiple schema types on one page using `@graph`:
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@graph": [
|
||||
{
|
||||
"@type": "Organization",
|
||||
"@id": "https://example.com/#organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com"
|
||||
},
|
||||
{
|
||||
"@type": "WebSite",
|
||||
"@id": "https://example.com/#website",
|
||||
"url": "https://example.com",
|
||||
"name": "Example",
|
||||
"publisher": {
|
||||
"@id": "https://example.com/#organization"
|
||||
}
|
||||
},
|
||||
{
|
||||
"@type": "BreadcrumbList",
|
||||
"itemListElement": [...]
|
||||
}
|
||||
{ "@type": "Organization", ... },
|
||||
{ "@type": "WebSite", ... },
|
||||
{ "@type": "BreadcrumbList", ... }
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -500,57 +113,25 @@ You can (and often should) have multiple schema types:
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Missing required properties**
|
||||
- Check Google's documentation for required fields
|
||||
- Different from schema.org minimum requirements
|
||||
**Missing required properties** - Check Google's documentation for required fields
|
||||
|
||||
**Invalid values**
|
||||
- Dates must be ISO 8601 format
|
||||
- URLs must be fully qualified
|
||||
- Enumerations must use exact values
|
||||
**Invalid values** - Dates must be ISO 8601, URLs fully qualified, enumerations exact
|
||||
|
||||
**Mismatch with page content**
|
||||
- Schema doesn't match visible content
|
||||
- Ratings for products without reviews shown
|
||||
- Prices that don't match displayed prices
|
||||
**Mismatch with page content** - Schema doesn't match visible content
|
||||
|
||||
---
|
||||
|
||||
## Implementation Patterns
|
||||
## Implementation
|
||||
|
||||
### Static Sites
|
||||
- Add JSON-LD directly in HTML template
|
||||
- Use includes/partials for reusable schema
|
||||
|
||||
### Dynamic Sites (React, Next.js, etc.)
|
||||
### Dynamic Sites (React, Next.js)
|
||||
- Component that renders schema
|
||||
- Server-side rendered for SEO
|
||||
- Serialize data to JSON-LD
|
||||
|
||||
```jsx
|
||||
// Next.js example
|
||||
export default function ProductPage({ product }) {
|
||||
const schema = {
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
name: product.name,
|
||||
// ... other properties
|
||||
};
|
||||
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
<script
|
||||
type="application/ld+json"
|
||||
dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
|
||||
/>
|
||||
</Head>
|
||||
{/* Page content */}
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### CMS / WordPress
|
||||
- Plugins (Yoast, Rank Math, Schema Pro)
|
||||
- Theme modifications
|
||||
@@ -570,9 +151,6 @@ export default function ProductPage({ product }) {
|
||||
}
|
||||
```
|
||||
|
||||
### Placement Instructions
|
||||
Where to add the code and how
|
||||
|
||||
### Testing Checklist
|
||||
- [ ] Validates in Rich Results Test
|
||||
- [ ] No errors or warnings
|
||||
@@ -587,7 +165,7 @@ Where to add the code and how
|
||||
2. What rich results are you hoping to achieve?
|
||||
3. What data is available to populate the schema?
|
||||
4. Is there existing schema on the page?
|
||||
5. What's your tech stack for implementation?
|
||||
5. What's your tech stack?
|
||||
|
||||
---
|
||||
|
||||
@@ -595,4 +173,3 @@ Where to add the code and how
|
||||
|
||||
- **seo-audit**: For overall SEO including schema review
|
||||
- **programmatic-seo**: For templated schema at scale
|
||||
- **analytics-tracking**: For measuring rich result impact
|
||||
|
||||
Reference in New Issue
Block a user