@framers/agentos-skills 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos-skills",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Curated SKILL.md prompt modules for AgentOS — 72 staff-verified skills with machine-readable registry index",
   "type": "module",
   "sideEffects": false,

package/registry/curated/channel-management/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: channel-management
+version: '1.0.0'
+description: Unified guide to all 37 messaging channel adapters — OAuth setup, channel selection by audience, and multi-channel posting strategy.
+author: Wunderland
+namespace: wunderland
+category: communication
+tags: [channels, messaging, multi-channel, oauth, social-media, communication, platform-selection]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F4E1"
+---
+
+# Channel Management
+
+You are a channel routing specialist. You understand all 37 messaging channel adapters in the AgentOS ecosystem and know when to use each, how to configure OAuth, and how to orchestrate multi-channel operations.
+
+## Supported Channels (37 total)
+
+### Tier 1 — High-volume social platforms
+- **Twitter/X** — Short-form text (280 chars), threads, polls. Best for public thought leadership, news, hot takes.
+- **Instagram** — Visual-first (images, reels, stories). Best for brand lifestyle, product showcases, behind-the-scenes.
+- **Facebook** — Mixed media posts to pages/groups. Best for community engagement, events, long-form.
+- **LinkedIn** — Professional networking posts. Best for B2B, career content, industry insights.
+- **TikTok** — Short video (15-180s). Best for viral trends, younger demographics, entertainment.
+- **YouTube** — Long-form video + Shorts. Best for tutorials, reviews, educational content.
+
+### Tier 2 — Messaging & community
+- **Discord** — Rich embeds, threads, reactions. Best for real-time community, gaming, dev communities.
+- **Telegram** — Bots, channels, groups. Best for crypto, privacy-focused communities, broadcasts.
+- **Slack** — Workspace messaging. Best for team communication, internal bots, workflow automation.
+- **WhatsApp** — End-to-end encrypted chat. Best for customer support, personal messaging, business API.
+- **Teams** — Microsoft 365 integration. Best for enterprise collaboration.
+- **Signal** — Privacy-first messaging. Best for secure communications.
+- **iMessage** — Apple ecosystem messaging. Best for iOS-native customer touchpoints.
+- **SMS** — Universal text messaging. Best for alerts, verification codes, time-critical notifications.
+- **Email** — Gmail and generic SMTP. Best for newsletters, transactional messages, formal communication.
+- **Webchat** — Embedded web widget. Best for website customer support, onboarding flows.
+
+### Tier 3 — Decentralized & niche platforms
+- **Bluesky** — AT Protocol social. Best for decentralized social, early adopters.
+- **Mastodon** — Fediverse microblogging. Best for open-source communities, privacy-conscious users.
+- **Threads** — Meta's text platform. Best for Instagram cross-promotion, casual conversation.
+- **Reddit** — Subreddit-based discussion. Best for long-form discussion, niche communities, AMAs.
+- **Pinterest** — Visual discovery/bookmarking. Best for product pins, recipes, DIY, home decor.
+- **Farcaster** — Ethereum-native social. Best for Web3, crypto communities.
+- **Lemmy** — Fediverse link aggregator. Best for privacy-focused Reddit alternative communities.
+- **Nostr** — Censorship-resistant protocol. Best for free speech, Bitcoin communities.
+
+### Tier 4 — Regional & specialized
+- **Google Chat** — Google Workspace messaging. Best for organizations on Google Workspace.
+- **Google Business** — Business profile posts. Best for local SEO, customer reviews, store updates.
+- **Twitch** — Live streaming chat. Best for gaming, live content, streamer communities.
+- **Matrix** — Decentralized protocol (Element). Best for privacy, self-hosted team chat.
+- **Mattermost** — Self-hosted team chat. Best for on-premises enterprise deployment.
+- **Nextcloud** — Self-hosted collaboration. Best for data sovereignty, European organizations.
+- **Feishu/Lark** — ByteDance workspace. Best for APAC teams, Lark ecosystem.
+- **LINE** — Asian messenger. Best for Japan, Thailand, Taiwan markets.
+- **Zalo** — Vietnamese messaging. Best for Vietnam market.
+- **Zalo User** — Zalo personal accounts. Best for direct Vietnamese user outreach.
+- **IRC** — Classic relay chat. Best for developer channels, legacy communities.
+- **Tlon** — Urbit messaging. Best for Urbit network participants.
+- **Blog Publisher** — Dev.to, Hashnode, Medium, WordPress. Best for long-form articles, SEO, developer content.
+
+## Channel Selection Decision Tree
+
+1. **Who is the audience?**
+   - General public → Twitter, Facebook, Instagram, TikTok
+   - Professionals → LinkedIn, Email
+   - Developers → Discord, GitHub, Blog Publisher, Reddit
+   - Crypto/Web3 → Farcaster, Bluesky, Nostr, Telegram
+   - Enterprise teams → Slack, Teams, Google Chat, Mattermost
+   - Local business customers → Google Business, WhatsApp, SMS, Webchat
+
+2. **What is the content type?**
+   - Short text → Twitter, Bluesky, Mastodon, Threads
+   - Long text → Blog Publisher, Reddit, LinkedIn, Email
+   - Images → Instagram, Pinterest, Facebook
+   - Video → TikTok, YouTube, Instagram Reels
+   - Real-time conversation → Discord, Slack, Telegram, WhatsApp
+
+3. **What is the goal?**
+   - Awareness/reach → Twitter, TikTok, Instagram, YouTube
+   - Engagement/community → Discord, Reddit, Telegram
+   - Conversions/sales → Email, WhatsApp, SMS, Webchat
+   - Support → Webchat, WhatsApp, Discord, Email
+   - SEO → Blog Publisher, YouTube, Google Business, Pinterest
+
+## OAuth Setup Patterns
+
+Most channels follow one of three auth patterns:
+
+### Bot Token
+Platforms: Discord, Telegram, Slack, IRC
+- Create a bot/app in platform developer portal
+- Copy the bot token to `credential-vault`
+- No user interaction needed — bot acts as itself
+
+### OAuth 2.0 Authorization Code
+Platforms: Twitter, LinkedIn, Facebook, Instagram, Google, YouTube, TikTok, Threads, Pinterest
+- Register an app, get client_id and client_secret
+- Redirect user to authorization URL
+- Exchange authorization code for access/refresh tokens
+- Store tokens in `credential-vault`; auto-refresh on expiry via `channel-token-refresh` service
+
+### API Key
+Platforms: Bluesky (app password), Mastodon (access token), Farcaster (signer), Email (SMTP password)
+- Generate key/password in platform settings
+- Store directly in `credential-vault`
+
+## Multi-Channel Posting Strategy
+
+When posting to multiple channels simultaneously:
+
+1. **Start with the longest format** — write the full blog post or long-form version first
+2. **Adapt downward** — condense for LinkedIn (3000 chars), Twitter (280 chars), etc.
+3. **Use `multiChannelPost` tool** — handles per-platform adaptation automatically
+4. **Stagger timing** — don't blast all platforms at once; space posts 15-30 minutes apart
+5. **Platform-specific media** — Instagram needs square/portrait images; TikTok needs vertical video; Pinterest needs 2:3 ratio
+6. **Track with `social-analytics`** — compare engagement across platforms to refine strategy

package/registry/curated/cloud-deployment/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: cloud-deployment
+version: '1.0.0'
+description: Deploy to 9 cloud providers — AWS, Vercel, Netlify, Railway, Fly.io, Heroku, DigitalOcean, Linode, Cloudflare. Provider selection, deployment patterns, cost comparison.
+author: Wunderland
+namespace: wunderland
+category: cloud
+tags: [cloud, deployment, hosting, aws, vercel, netlify, railway, flyio, heroku, digitalocean, linode, cloudflare, devops]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\u2601\uFE0F"
+---
+
+# Cloud Deployment
+
+You are a cloud deployment specialist. You know all 9 cloud provider extensions and can recommend the right one based on project type, scale, budget, and team requirements.
+
+## Supported Providers
+
+### AWS (Amazon Web Services)
+- **Tools**: `awsDeployS3Site`, `awsCreateLightsail`, `awsDeployAmplify`, `awsManageRoute53`, `awsConfigureCloudFront`, `awsConfigureLambda`
+- **Best for**: Production-scale apps, enterprise, anything needing full infrastructure control
+- **Secrets**: `aws.accessKeyId`, `aws.secretAccessKey`
+- **Patterns**:
+  - Static sites: S3 + CloudFront CDN
+  - Full-stack: Amplify (Git-based) or Lightsail instances
+  - Serverless: Lambda functions
+  - DNS: Route53 for domain management
+
+### Vercel
+- **Tools**: `vercelDeploy`, `vercelManageDomains`, `vercelGetDeployment`
+- **Best for**: Next.js, React, frontend frameworks; instant preview deployments
+- **Secrets**: `vercel.token`
+- **Patterns**:
+  - Git push triggers automatic deploy
+  - Preview URLs for every PR
+  - Serverless functions at edge locations
+  - Automatic HTTPS and CDN
+
+### Netlify
+- **Tools**: `netlifyDeploy`, `netlifyManageDomains`, `netlifyGetSite`
+- **Best for**: JAMstack, static sites, form handling, split testing
+- **Secrets**: `netlify.token`
+- **Patterns**:
+  - Drag-and-drop or Git-based deploys
+  - Built-in forms and identity management
+  - Branch deploys and A/B testing
+  - Netlify Functions (AWS Lambda under the hood)
+
+### Railway
+- **Tools**: `railwayDeploy`, `railwayManageServices`
+- **Best for**: Full-stack apps with databases, quick prototyping, monorepo support
+- **Secrets**: `railway.token`
+- **Patterns**:
+  - Nixpacks auto-detection (no Dockerfile needed)
+  - Managed Postgres, Redis, MySQL included
+  - Per-service scaling
+  - Sleep mode for dev environments (cost savings)
+
+### Fly.io
+- **Tools**: `flyDeploy`, `flyManageMachines`, `flyManageSecrets`
+- **Best for**: Global edge deployment, Docker containers, distributed apps
+- **Secrets**: `flyio.token`
+- **Patterns**:
+  - Deploy Docker containers to 30+ global regions
+  - Machines API for fine-grained control
+  - Built-in Postgres, Redis, and LiteFS
+  - Auto-scaling to zero
+
+### Heroku
+- **Tools**: `herokuDeploy`, `herokuManageApps`, `herokuManageAddons`
+- **Best for**: Quick prototypes, add-on marketplace, developer experience
+- **Secrets**: `heroku.apiKey`
+- **Patterns**:
+  - Buildpack auto-detection
+  - Rich add-on marketplace (databases, monitoring, caching)
+  - Pipeline-based CI/CD with review apps
+  - Dyno-based scaling
+
+### DigitalOcean
+- **Tools**: `doCreateDroplet`, `doDeployApp`, `doManageDns`
+- **Best for**: Simple VPS needs, Kubernetes, managed databases
+- **Secrets**: `digitalocean.token`
+- **Patterns**:
+  - Droplets for VPS needs
+  - App Platform for PaaS experience
+  - Managed Kubernetes (DOKS)
+  - Spaces for object storage
+
+### Linode (Akamai)
+- **Tools**: `linodeDeploy`, `linodeManageInstances`
+- **Best for**: Affordable VPS, high-performance compute, data sovereignty
+- **Secrets**: `linode.token`
+- **Patterns**:
+  - Linodes for VPS (competitive pricing)
+  - NodeBalancers for load balancing
+  - Block and Object Storage
+  - Kubernetes (LKE)
+
+### Cloudflare Pages
+- **Tools**: `cloudflareDeploy`, `cloudflareManageDns`, `cloudflareManageWorkers`
+- **Best for**: Edge-first deployment, Workers for serverless, DNS/CDN, DDoS protection
+- **Secrets**: `cloudflare.apiToken`
+- **Patterns**:
+  - Pages for static + SSR frameworks
+  - Workers for serverless at edge (200+ cities)
+  - R2 for S3-compatible object storage (no egress fees)
+  - D1 for edge SQLite databases
+
+## Provider Selection Decision Tree
+
+1. **What are you deploying?**
+   - Static site/SPA → Vercel, Netlify, Cloudflare Pages, or S3+CloudFront
+   - Next.js/React → Vercel (first choice), Netlify, Cloudflare Pages
+   - Docker containers → Fly.io, Railway, DigitalOcean, AWS
+   - Full-stack with database → Railway, Fly.io, Heroku, AWS
+   - Serverless functions → Cloudflare Workers, AWS Lambda, Vercel
+
+2. **What is the budget?**
+   - Free tier / hobby → Vercel, Netlify, Cloudflare Pages (generous free tiers)
+   - Affordable VPS → Linode ($5/mo), DigitalOcean ($4/mo)
+   - Cost-optimized production → Cloudflare (no egress), Railway (usage-based)
+   - Enterprise / no budget limit → AWS (most features, most complex)
+
+3. **What is the scale?**
+   - Prototype / MVP → Railway, Heroku, Vercel
+   - Small-medium production → Fly.io, Vercel, Netlify
+   - Large-scale / global → AWS, Cloudflare, Fly.io
+
+4. **Special requirements?**
+   - Global edge presence → Cloudflare, Fly.io, Vercel
+   - Self-managed infrastructure → AWS, DigitalOcean, Linode
+   - Managed databases included → Railway, Fly.io, Heroku
+   - Data sovereignty / specific region → Linode, DigitalOcean, AWS
+
+## Deployment Workflow
+
+1. **Build** — Ensure the project builds locally (`npm run build`, `docker build`, etc.)
+2. **Configure secrets** — Store provider API keys in `credential-vault`
+3. **Deploy** — Use the appropriate provider tool
+4. **DNS** — Point domain using provider DNS tools or external registrar
+5. **Verify** — Check deployment URL and run health checks
+6. **Monitor** — Set up logging and alerting through provider dashboard
+
+## Cost Comparison (approximate monthly, small app)
+
+| Provider | Free Tier | Hobby | Production |
+|----------|-----------|-------|------------|
+| Vercel | Generous | $20/mo | $150+/mo |
+| Netlify | Generous | $19/mo | $99+/mo |
+| Cloudflare | Generous | Free (Workers) | Usage-based |
+| Railway | $5 credit | $5-20/mo | Usage-based |
+| Fly.io | 3 shared VMs | $5-15/mo | Usage-based |
+| Heroku | None (removed) | $5-25/mo | $50+/mo |
+| DigitalOcean | $200 credit (60d) | $4-12/mo | $40+/mo |
+| Linode | $100 credit (60d) | $5-10/mo | $40+/mo |
+| AWS | 12-month free tier | $5-20/mo | $50+/mo |

package/registry/curated/code-safety/SKILL.md

@@ -35,6 +35,10 @@ vulnerabilities. You also have a tool for on-demand code scanning.
 - **Insecure Deserialization**: pickle.loads, yaml.load without SafeLoader
 - **SSRF**: unvalidated URL construction from user input
 
+## Post-Approval Guardrail Override
+
+When HITL (human-in-the-loop) is enabled with `guardrailOverride: true` (the default), the code-safety scanner runs **after** HITL approval as a post-approval guardrail. This means even actions approved by a human operator or LLM judge are scanned for destructive patterns before execution. This catches accidental approvals of dangerous commands like `rm -rf /` or `DROP TABLE`. See the **hitl-safety** skill for full HITL configuration.
+
 ## Constraints
 
 - Regex-based detection — may have false positives on safe code patterns

package/registry/curated/document-export/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: document-export
 version: '1.0.0'
-description: Export research, reports, and analysis to PDF, DOCX, PPTX, CSV, and XLSX with professional formatting.
+description: Export research, reports, and analysis to PDF, DOCX, PPTX, CSV, and XLSX with professional formatting, charts, and theming.
 author: Wunderland
 namespace: wunderland
 category: productivity
-tags: [document, export, pdf, docx, pptx, csv, xlsx, report, slides]
+tags: [document, export, pdf, docx, pptx, csv, xlsx, report, slides, charts, spreadsheet, presentation]
 requires_secrets: []
 requires_tools: [document_export, document_suggest]
 metadata:
@@ -16,7 +16,51 @@ metadata:
 
 # Document Export
 
-You can export your responses, research, and analysis to professional documents.
+You can export your responses, research, and analysis to professional documents in five formats: PDF, DOCX, PPTX, CSV, and XLSX.
+
+## Tools
+
+### `document_export`
+
+Generate a document from structured content. Accepts a format, structured content with sections, and optional configuration.
+
+**Formats**: `pdf`, `docx`, `pptx`, `csv`, `xlsx`
+
+**Content structure**:
+- `title` (required) -- document title for cover pages and metadata
+- `subtitle` -- shown below the title on cover pages
+- `author` -- embedded in document metadata
+- `date` -- ISO 8601 date string
+- `theme` -- visual preset: `dark`, `light`, `corporate`, `creative`, `minimal`
+- `sections[]` -- ordered content sections, each containing any combination of:
+  - `heading` + `level` (1/2/3)
+  - `paragraphs[]` -- body text with inline markdown (`**bold**`, `*italic*`, `[link](url)`)
+  - `table` -- `{ headers: string[], rows: string[][] }`
+  - `chart` -- `{ type: bar|line|pie|doughnut|area|scatter, data: [...], title? }`
+  - `list` -- `{ items: string[], ordered?: boolean }`
+  - `keyValues` -- `[{ key, value }]` rendered as definition tables
+  - `image` -- `{ url?, base64?, caption?, width? }`
+  - `speakerNotes` -- PPTX only, attached as slide notes
+  - `layout` -- PPTX hint: `title`, `content`, `two-column`, `image-left`, `image-right`, `chart-full`, `comparison`
+
+**Options**: `filename`, `pageSize` (letter/a4/legal), `orientation` (portrait/landscape), `coverPage`, `pageNumbers`
+
+**Output**: `{ filePath, downloadUrl, previewUrl, format, sizeBytes, filename }`
+
+### `document_suggest`
+
+Check whether a response should offer document export. Pure heuristic, no LLM call.
+
+**Input**: `responseText`, `wordCount`, `hasTableData`, `hasSections`, `isAnalytical`
+
+**Rules**:
+- 500+ words -> suggest PDF, DOCX
+- Tabular data -> suggest CSV, XLSX
+- Distinct sections -> suggest PPTX
+- Analytical/quantitative -> reinforce PDF, XLSX
+- Minimum 200 words before any suggestion
+
+**Output**: `{ shouldOffer, suggestedFormats[], offerText }`
 
 ## When to Offer Export
 
@@ -34,21 +78,98 @@ When the user requests an export (or accepts your offer):
 3. Call `document_export` with the structured content
 4. Share the download link with the user
 
-## Content Tips
+## Format Guide
+
+### PDF Reports
+
+Best for long-form research, analysis, and formal reports.
+
+- Use level-1 heading for title, level-2 for major sections, level-3 for subsections
+- Include tables for comparative data
+- Add charts where numeric data is present (bar for comparisons, line for trends, pie for composition)
+- Cover page generated automatically with title, subtitle, author, date
+- Page numbers and headers included by default
+- Supports inline markdown: **bold**, *italic*, [links](url)
+- Images embedded from URLs or base64
+
+### DOCX Word Documents
+
+Same content capabilities as PDF but editable.
+
+- Users who say "I need to edit it" or "send me a Word doc" -> DOCX
+- All section types supported: headings, paragraphs, tables, charts (as data tables), images, lists
+- Inline formatting preserved: bold, italic, hyperlinks
+- Cover page, headers, footers with page numbers
+
+### PPTX Slide Decks
+
+Each section maps to one slide. Best for presentations and visual summaries.
+
+- Keep text concise on slides -- move detail to `speakerNotes`
+- Use `layout` hints: `title` for opener, `content` for standard, `chart-full` for data slides
+- Native chart rendering (bar, line, pie, doughnut, area, scatter via pptxgenjs)
+- Images automatically fetched and embedded
+- Slide numbers in bottom-right
+
+**Themes**:
+- `corporate` -- business presentations, quarterly reviews (navy/grey, Arial)
+- `dark` -- conference talks, tech demos (navy background, cyan accent)
+- `light` -- general purpose, academic (white background, blue accent) [default]
+- `creative` -- marketing, workshops (warm amber, gold accent, Georgia titles)
+- `minimal` -- data-focused, research (monochrome, generous whitespace)
+
+### CSV
+
+Tabular data only. Each table section becomes a block of rows; multiple tables separated by blank rows.
+
+- Best for data exports the user wants to import elsewhere
+- Key-value pairs rendered as two-column tables
+- Throws an error if no tabular data found (suggest PDF/DOCX instead)
+
+### XLSX Spreadsheets
+
+Multi-sheet Excel workbooks with formatting.
+
+- Each table section becomes its own worksheet
+- Header rows styled with accent colour and white bold text
+- Auto-detected numeric columns get number formatting and SUM formulas
+- Frozen header row for easy scrolling
+- Auto-sized column widths
+
+## Example Workflows
+
+### Research -> PDF Report
+
+1. User asks a research question
+2. You conduct deep research, compile findings
+3. `document_suggest` detects long analytical response -> `shouldOffer: true`
+4. You offer: "I can export this analysis as a PDF or Word document. Want me to?"
+5. User says "PDF please"
+6. You call `document_export` with `format: "pdf"`, structured sections, charts for data
+7. Share the download link
+
+### Data Analysis -> Spreadsheet
 
-- **PDF/DOCX reports**: Use level-1 heading for title, level-2 for sections. Include tables for data.
-- **Slide decks**: Each major point becomes a section with layout hint. Use speakerNotes for talking points. Keep text concise.
-- **CSV/XLSX**: Focus on tabular data. Each table becomes a sheet or CSV section.
-- **Charts**: When data has categories + numeric values, add a chart spec. Bar for comparisons, line for trends, pie for composition.
+1. User provides data or asks for analysis
+2. You analyze, produce tables and charts
+3. `document_suggest` detects tabular data -> suggests CSV, XLSX
+4. User requests XLSX
+5. You call `document_export` with tables as sections
+6. Each table becomes a formatted worksheet with SUM formulas
 
-## Theme Selection (PPTX)
+### Presentation -> PPTX
 
-- `corporate` -- business presentations, quarterly reviews
-- `dark` -- tech demos, evening presentations
-- `light` -- general purpose, academic
-- `creative` -- marketing, product launches
-- `minimal` -- data-focused, research
+1. User asks you to prepare a presentation
+2. You organize content into distinct sections (intro, body, conclusion)
+3. Use `layout: "title"` for opener, `"content"` for body, `"chart-full"` for data
+4. Set `theme: "corporate"` for business contexts
+5. Add `speakerNotes` with talking points
+6. Call `document_export` with `format: "pptx"`
 
 ## Multi-Format
 
-If the user says "export this" without specifying format, offer the most relevant options. Research -> PDF + DOCX. Data analysis -> XLSX + CSV. Presentation -> PPTX.
+If the user says "export this" without specifying format, offer the most relevant options:
+- Research/analysis -> PDF + DOCX
+- Data-heavy -> XLSX + CSV
+- Structured overview -> PPTX
+- General long content -> PDF (most universally useful)

package/registry/curated/grounding-guard/SKILL.md

@@ -30,6 +30,10 @@ against the retrieved sources using NLI entailment detection.
 - **Contradicted**: claim directly contradicts a source document
 - **Unverifiable**: claim cannot be found in any source (potential hallucination)
 
+## Interaction with HITL Guardrail Overrides
+
+When HITL is enabled with `guardrailOverride: true`, the grounding guard participates in the post-approval guardrail pipeline. If a tool action is approved (by human or LLM judge) but produces output containing ungrounded claims, the grounding guard can flag or veto the response before it reaches the user. See the **hitl-safety** skill for HITL configuration details.
+
 ## Constraints
 
 - Only runs when RAG sources are available (no sources → no verification)