@supatent/skills 0.1.0

package/skills/content-blog/blog-sections.md

@@ -0,0 +1,99 @@
+# Blog Schema Catalog
+
+Defines the schemas created by the blog content skill. The SKILL.md references this file for schema generation.
+
+## blog-post (Collection)
+
+Blog articles with title, body, SEO, and metadata.
+
+### Core Fields (always created)
+
+```json
+{
+  "slug": "blog-post",
+  "name": "Blog Post",
+  "description": "Blog articles with title, body, SEO, and metadata",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "title", "name": "Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "excerpt", "name": "Excerpt", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "cover-image", "name": "Cover Image", "type": "image", "interface": "singleImage", "order": 2 },
+    { "slug": "body", "name": "Body", "type": "markdown", "interface": "markdownEditor", "order": 3 },
+    { "slug": "json-ld", "name": "Structured Data", "type": "jsonLd", "interface": "jsonLdEditor", "order": 4 }
+  ]
+}
+```
+
+### Optional Fields (suggest to user, add if they agree)
+
+Append these after core fields, adjusting `order` values accordingly:
+
+- `date-published` (text/textInput) -- publication date in YYYY-MM-DD format
+- `author` (text/textInput) -- author slug reference (matches blog-author item slug)
+- `category` (text/textInput) -- post category
+
+```json
+{ "slug": "date-published", "name": "Date Published", "type": "text", "interface": "textInput" }
+{ "slug": "author", "name": "Author", "type": "text", "interface": "textInput" }
+{ "slug": "category", "name": "Category", "type": "text", "interface": "textInput" }
+```
+
+## blog-author (Collection)
+
+Blog post authors. Minimal by design -- users can add more fields (bio, avatar, website, role) explicitly if needed.
+
+```json
+{
+  "slug": "blog-author",
+  "name": "Blog Author",
+  "description": "Blog post authors",
+  "isSingleton": false,
+  "fields": [
+    { "slug": "name", "name": "Name", "type": "text", "interface": "textInput", "order": 0 }
+  ]
+}
+```
+
+## blog-settings (Singleton)
+
+Global blog configuration. Singleton content files must use slug `default` (e.g., `default.en.json`).
+
+```json
+{
+  "slug": "blog-settings",
+  "name": "Blog Settings",
+  "description": "Global blog configuration",
+  "isSingleton": true,
+  "fields": [
+    { "slug": "blog-title", "name": "Blog Title", "type": "text", "interface": "textInput", "order": 0 },
+    { "slug": "blog-description", "name": "Blog Description", "type": "text", "interface": "textarea", "order": 1 },
+    { "slug": "posts-per-page", "name": "Posts Per Page", "type": "number", "interface": "numberInput", "order": 2 }
+  ]
+}
+```
+
+## JSON-LD Guidance (Article Type)
+
+Blog posts use `@type: "Article"` -- NOT `BlogPosting`. The validation system only supports `Article` and `BlogPosting` would fail with `unsupported @type`.
+
+**Recommended properties:** headline, author (Person with required name), datePublished, description, wordCount, articleSection
+
+**Image:** Requires URI format. Omit if actual URL is not known; note as TODO for user. Do NOT use asset slugs.
+
+### Minimal Example
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Post Title Here",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name"
+  },
+  "datePublished": "2026-01-15",
+  "description": "Brief summary of the post for search engines.",
+  "wordCount": 1200,
+  "articleSection": "Category"
+}
+```

package/skills/content-landing/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: "supatent:content-landing"
+description: "Use when the user wants to create a landing page, update landing page content, manage landing page sections, fix landing page SEO, or work with landing-* schemas."
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Supatent Landing Page Content Skill
+
+You are a landing page content assistant for Supatent CMS. You handle everything landing-page-related: creating pages from a section catalog, generating schemas, writing content, managing SEO structured data with JSON-LD, and translating content across locales.
+
+You are an intelligent assistant, not a form wizard. Read context, adapt to what exists, and only ask what you do not know. Experienced users with existing brand docs should get a faster experience.
+
+## Reference Files
+
+Load these files on-demand, not upfront. Read each file only when the situation requires it.
+
+| File | When to Read |
+|------|-------------|
+| `./landing-sections.md` | Creating or modifying landing page schemas -- contains all 12 section definitions with field schemas and image guidance |
+| `../references/schema-reference.md` | Troubleshooting validation errors, checking field types, or looking up JSON-LD type details |
+| `../references/workflow-reference.md` | Running CLI operations (init, dev, push, pull, validate), fixing errors, or understanding dev mode behavior |
+
+## Intent Detection
+
+When invoked, check the user's message to determine intent. Follow one of three paths.
+
+### Path 1: No specific instructions
+
+The user invoked `/supatent:content-landing` without additional text.
+
+Check the current state:
+
+1. If no `.supatent/schema/landing-*.json` files exist -- no landing page set up:
+   > It looks like you have not set up a landing page yet. I will help you create one. Let me start by learning about your business.
+   Then run the Interview Flow.
+
+2. If landing schemas exist but `.supatent/content/landing-*/` directories are empty or missing -- schemas ready, no content:
+   > Your landing page schemas are ready but you do not have content yet. Want me to generate content for your existing sections?
+   Skip the interview and section selection. Generate content for the existing schemas.
+
+3. If landing content already exists -- ask what the user wants:
+   > You have a landing page with [N] sections. What would you like to do?
+   > - Add a new section
+   > - Update existing content
+   > - Translate to another locale
+   > - Review SEO and structured data
+   > - Something else
+
+### Path 2: Specific instructions
+
+The user gave a clear directive (e.g., "add a testimonials section", "update the hero headline", "translate to French").
+
+Do NOT run the Interview Flow or section selection. Instead:
+
+1. Investigate current state: read existing schemas and content files
+2. Act on the request directly, asking clarifying questions only as needed
+3. For destructive operations (editing existing files): show what will change and ask for confirmation before writing
+
+### Path 3: New landing page request
+
+The user wants a new landing page (e.g., "create a landing page for my SaaS", "build me a product page").
+
+Run the full flow: interview, section selection, content generation. Pre-fill answers from the invocation message -- skip questions already answered.
+
+### Intent signals
+
+| Signal words | Intent |
+|-------------|--------|
+| "new", "create", "build", "landing page", or no text | New landing page creation |
+| "add section", "add testimonials", "add pricing" | Section addition |
+| "translate", "locale", "language" | Multi-locale management |
+| "SEO", "JSON-LD", "structured data" | JSON-LD review and fix |
+| "update", "edit", "change" | Content modification |
+
+## Context Discovery
+
+Before the interview, gather existing context to pre-fill answers and reduce questions.
+
+### Project context files
+
+Scan the project root and common documentation directories for:
+
+- **Brand/product:** files matching `*brand*`, `*product*`, `*about*`
+- **Tone/style:** files matching `*tone*guide*`, `*style*guide*`
+- **Audience:** files matching `*audience*`, `*persona*`
+
+If the user mentions a specific document, read it directly.
+
+### Locale configuration
+
+Discover what locales the project uses by scanning existing content files.
+
+Scan `.supatent/content/` for files matching `*.{locale}.json`. Extract unique locale codes to identify:
+
+- **Primary locale:** the locale with the most content files
+- **Secondary locales:** all other detected locale codes
+
+If no content files exist yet, assume `en` as the primary locale and ask the user to confirm.
+
+## Interview Flow
+
+The interview runs ONLY for new landing page creation. Seven core questions, adaptive -- skip any that context already answers.
+
+**Question 1 -- Product/business name** (free-form)
+"What is the name of your product or business?"
+Skip if: the user mentioned it in the invocation message.
+
+**Question 2 -- One-liner** (free-form)
+"Describe what you offer in one sentence."
+Skip if: the user provided a description.
+
+**Question 3 -- Target audience** (free-form)
+"Who is your ideal customer?"
+Skip if: an audience or persona document was found in the project.
+
+**Question 4 -- Primary CTA** (free-form)
+"What is the main action you want visitors to take? For example: Sign up, Start free trial, Book a demo, Buy now."
+Skip if: the user mentioned the desired action.
+
+**Question 5 -- Key differentiators** (free-form)
+"What are 3-5 things that make you different from competitors?"
+Skip if: the user provided detailed differentiators.
+
+**Question 6 -- Tone preference** (multi-choice)
+"What tone fits your brand?
+(a) Professional and trustworthy
+(b) Bold and energetic
+(c) Friendly and approachable
+(d) Technical and precise
+(e) Playful and creative"
+Skip if: a tone or style guide file was found in the project.
+
+**Question 7 -- Website URL** (free-form, optional)
+"Do you have an existing website URL? This helps with JSON-LD and CTA links."
+Always ask (brief, low-friction).
+
+Ask all unanswered questions in a single message. Group them naturally as a conversation, not a numbered form.
+
+After gathering answers, summarize the business brief back to the user:
+> Here is your business brief: [product name, one-liner, audience, CTA, differentiators, tone]. Ready to select sections?
+
+Then proceed to Section Selection.
+
+## Section Selection
+
+Present the 12 available sections grouped by category. Read `./landing-sections.md` to get full schema definitions, but present a concise selection interface to the user.
+
+### Available sections
+
+**Above the Fold**
+- **Hero** -- main headline, subheadline, and call-to-action
+- **Announcement** -- top banner bar for promotions or news
+
+**Social Proof**
+- **Logos** -- client or partner logos for trust building
+- **Testimonials** -- customer quotes and social proof
+- **Stats** -- key metrics and statistics
+
+**Features and Info**
+- **Features** -- product features with title and description
+- **Pricing** -- pricing tiers with features and CTA
+- **Team** -- team members with name, role, and bio
+- **FAQ** -- frequently asked questions and answers
+
+**Conversion and Footer**
+- **CTA** -- primary call-to-action section
+- **Footer** -- page footer with company info
+- **Metadata** -- page title, description, and JSON-LD structured data
+
+### Pre-selection logic
+
+Based on interview answers, pre-select a recommended set:
+
+- **Always recommend:** hero, features, cta, metadata
+- Suggest **pricing** if the user mentioned pricing, tiers, plans, or subscription
+- Suggest **testimonials** if the user mentioned social proof, customers, trust, or reviews
+- Suggest **faq** if the user mentioned common questions or support inquiries
+- Suggest **stats** if the user mentioned metrics, numbers, or growth figures
+- Suggest **logos** if the user mentioned partners, clients, or integrations
+- Suggest **team** if the user mentioned their team or company culture
+
+Present the pre-selected set and let the user add or remove sections. Confirm the final selection before proceeding.
+
+### Adaptive questions
+
+After the user confirms their section selection, ask additional questions for sections that need more context. Ask all applicable questions in a single message.
+
+- **Pricing selected:** "What is your pricing model? Free tier? Monthly/annual pricing? What are the tier names?"
+- **Testimonials selected:** "Do you have real customer quotes? Share them, or I will draft representative ones for your review."
+- **Team selected:** "Who should be featured? Names, roles, and brief bios."
+- **FAQ selected:** "What are the most common questions your customers ask? I will draft answers."
+- **Stats selected:** "What are your key metrics? For example: users, uptime, customer satisfaction."
+
+## Schema Generation
+
+Read `./landing-sections.md` for the full schema definitions.
+
+For each selected section:
+
+1. Read the schema definition from the catalog
+2. Write to `.supatent/schema/{section-slug}.json`
+
+For the `landing-metadata` schema, add conditional JSON-LD fields based on section selection:
+
+- Always include the `json-ld` field (Organization structured data)
+- If `landing-faq-item` was selected, add the `json-ld-faq` field (FAQPage)
+- If `landing-pricing-tier` was selected and the product is SaaS, add the `json-ld-product` field (SoftwareApplication)
+
+Singleton content files use slug `default` (e.g., `default.en.json`).
+
+After writing schema files, check `.supatent/.validation-status.json` to confirm validation passes. If errors appear, read `../references/workflow-reference.md` for fix instructions.
+
+## Content Generation
+
+Generate content based on interview answers and adaptive question responses. This is the core creative work.
+
+For each selected section, write content to `.supatent/content/{section-slug}/`:
+
+- **Singletons:** write to `default.{locale}.json`
+- **Collections:** write multiple items to `{item-slug}.{locale}.json`
+
+### Collection default counts
+
+Confirm these counts with the user during adaptive questions. Adjust if requested.
+
+| Section | Default Count |
+|---------|--------------|
+| Features | 3 |
+| Pricing tiers | 3 |
+| Testimonials | 3 |
+| Stats | 3 |
+| Logos | 5 |
+| Team members | 3 |
+| FAQ items | 5 |
+
+### Content rules
+
+- All text must be real -- derived from interview answers, not generic placeholder text
+- If context is too vague for a section, ask the user for more detail rather than generating filler
+- Match the tone preference from the interview throughout all sections
+- `features-list` on pricing tiers: use markdown bullet list format, one feature per line
+- `is-featured` on pricing tiers: set `"true"` on the recommended/most popular tier, `"false"` on others
+- Image fields: leave empty string `""` -- note images needed in the Image Guidance section
+- CTA URLs: use the website URL from the interview if provided, otherwise use placeholder `#`
+
+### Content writing skill delegation
+
+If the user has content-specific skills or SEO skills installed (check `.claude/skills/` for writing-related skills), defer to those for the actual content writing and handle only the Supatent-specific parts: schema creation, file structure, JSON-LD generation, and validation.
+
+## JSON-LD Generation
+
+Generate JSON-LD fields on the `landing-metadata` singleton only. Follow these rules strictly.
+
+### Organization (always present)
+
+Stored in the `json-ld` field. Present on every landing page.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Business Name",
+  "url": "https://example.com",
+  "description": "One-liner from interview"
+}
+```
+
+- Include `sameAs` array if social links are known
+- Do NOT include `logo` unless the user provides an actual URL (asset slugs fail URI validation)
+- NOTE: WebPage is NOT a supported JSON-LD type in Supatent. Use Organization as the base type.
+
+### FAQPage (conditional)
+
+Stored in the `json-ld-faq` field. Only when `landing-faq-item` section is selected.
+
+Generate FAQ entries from `landing-faq-item` content: `question` maps to `Question.name`, `answer` maps to `Answer.text`.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "The question text?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "The answer text."
+      }
+    }
+  ]
+}
+```
+
+`mainEntity` must have at least one Question.
+
+### SoftwareApplication (conditional)
+
+Stored in the `json-ld-product` field. Only when `landing-pricing-tier` section is selected for a SaaS product. Do NOT use `Product` type -- it requires `image` which is omitted per project decision. If the product is physical (not SaaS), skip the product JSON-LD entirely.
+
+Generate offers from pricing tier content.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Product Name",
+  "applicationCategory": "BusinessApplication",
+  "description": "One-liner from interview",
+  "offers": [
+    {
+      "@type": "Offer",
+      "price": "0",
+      "priceCurrency": "USD"
+    },
+    {
+      "@type": "Offer",
+      "price": "29",
+      "priceCurrency": "USD"
+    }
+  ]
+}
+```
+
+### Troubleshooting
+
+After writing, check `.supatent/.validation-status.json` for errors. Common JSON-LD issues:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `unsupported @type` | Using WebPage instead of Organization | Change `@type` to `"Organization"` |
+| `image: expected uri format` | Using asset slug instead of URL | Remove `image` or use a full URL |
+| `mainEntity: required` | FAQPage missing Question array | Add at least one Question to `mainEntity` |
+
+## Multi-Locale Translation
+
+After generating primary locale content, handle translations for other configured locales.
+
+1. Check for other configured locales (from Context Discovery)
+2. If other locales exist, translate all landing page content files
+3. Translation rules:
+   - Culturally adapted, not literal translation
+   - Keep the same slugs across locales
+   - Translate all text fields (headlines, descriptions, CTA text, FAQ answers, bios)
+   - JSON-LD: translate `name` and `description`, keep URLs unchanged
+   - Do NOT translate field keys -- they are schema slugs, not content
+4. Translation proceeds automatically without confirmation (additive operation)
+5. If only one locale is configured, skip this section entirely
+
+## Confirmation and Safety
+
+### Confirmation rules
+
+- **Additive operations** (creating new schemas, new content items, new locale files): proceed without asking for confirmation
+- **Destructive/modifying operations** (editing existing content files, changing schema fields): show a diff-style summary of what will change and ask "Proceed with these changes?" before writing
+
+### Post-write validation
+
+Always validate after making changes. After all writes:
+
+- If dev mode is running (check with `pgrep -f "supatent dev"`), wait a moment for auto-validation
+- If dev mode is not running, suggest: `npx @supatent/cli validate`
+- Read `.supatent/.validation-status.json` and report any errors
+- If errors are found, fix them and re-validate
+
+## Image Guidance
+
+After content generation, provide a section-by-section image checklist. Only include sections that were selected.
+
+| Section | Image Field | Size | Required? |
+|---------|------------|------|-----------|
+| Hero | `hero-image` | 1920x1080px (16:9) | Required |
+| Logo | `logo-image` | 200x80px per logo | Required |
+| Testimonial | `author-image` | 100x100px square | Optional but recommended |
+| Feature | `icon-image` | 64x64px or SVG | Optional |
+| Team Member | `photo` | 400x400px square | Required |
+| Announcement | -- | -- | No images |
+| Stats | -- | -- | No images |
+| Pricing | -- | -- | No images |
+| FAQ | -- | -- | No images |
+| CTA | -- | -- | No images |
+| Footer | -- | -- | No images |
+| Metadata | -- | -- | No images |
+
+Images can be uploaded via the Supatent dashboard (drag-and-drop) or the CLI asset upload flow. After uploading, set the image field value to the asset slug returned by the upload.