@framers/agentos-skills 0.3.0 → 0.4.1

package/registry/curated/amazon-polly/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: amazon-polly
+version: '1.0.0'
+description: Neural text-to-speech via Amazon Polly — high-quality voices, MP3 output, voice listing, default Joanna (en-US Neural).
+author: Wunderland
+namespace: wunderland
+category: voice
+tags: [voice, tts, text-to-speech, amazon, aws, polly, neural]
+requires_secrets: [aws.accessKeyId, aws.secretAccessKey]
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F50A"
+    primaryEnv: AWS_ACCESS_KEY_ID
+    homepage: https://docs.aws.amazon.com/polly/
+---
+
+# Amazon Polly TTS
+
+Use this skill when the agent is deployed on AWS infrastructure or when the user prefers Amazon Polly's Neural engine voices. Polly provides high-quality neural TTS with MP3 output and a wide range of voices across languages and regions.
+
+Prefer this over OpenAI or ElevenLabs TTS when the user already has AWS credentials configured, or when cost efficiency at high volume is a priority (Polly pricing is per-character rather than per-request).
+
+## Setup
+
+Set the following in the environment or agent secrets store:
+
+| Variable                  | Description              |
+|---------------------------|--------------------------|
+| `AWS_ACCESS_KEY_ID`       | IAM access key ID        |
+| `AWS_SECRET_ACCESS_KEY`   | IAM secret access key    |
+| `AWS_REGION`              | AWS region (default `us-east-1`) |
+
+## Configuration
+
+```json
+{
+  "voice": {
+    "tts": "amazon-polly"
+  }
+}
+```
+
+With a specific voice:
+
+```json
+{
+  "voice": {
+    "tts": "amazon-polly",
+    "providerOptions": {
+      "voice": "Matthew"
+    }
+  }
+}
+```
+
+## Provider Rules
+
+- Default voice is `Joanna` (en-US, Neural engine).
+- Always use the Neural engine for production — Standard voices are lower quality.
+- Call `listAvailableVoices()` to enumerate all voices available in the configured region.
+- Audio is returned as MP3. Playback requires an MP3-capable audio pipeline.
+
+## Examples
+
+- "Use Amazon Polly with the Matthew voice for this agent."
+- "List available Polly voices in us-east-1."
+- "Synthesize this message using Amazon Polly."
+
+## Constraints
+
+- Requires `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with `polly:SynthesizeSpeech` and `polly:DescribeVoices` IAM permissions.
+- Neural engine voices are region-specific. Not all voices are available in every AWS region.
+- API costs apply per character synthesized (Neural engine pricing).

package/registry/curated/apple-notes/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: apple-notes
+version: '1.0.0'
+description: Create, read, search, and manage notes in Apple Notes using AppleScript and macOS automation.
+author: Wunderland
+namespace: wunderland
+category: productivity
+tags: [apple-notes, macos, notes, applescript, automation]
+requires_secrets: []
+requires_tools: [filesystem]
+metadata:
+  agentos:
+    emoji: "\U0001F4F1"
+    os: ['darwin']
+    requires:
+      bins: ['osascript']
+---
+
+# Apple Notes Integration
+
+You can create, read, search, and manage notes in Apple Notes on macOS using AppleScript commands executed via `osascript`. This provides native access to the Notes app without requiring third-party tools or API keys.
+
+When creating notes, use `osascript` to invoke AppleScript that creates note entries with title and body text. Notes support basic HTML formatting for bold, italic, lists, and headings. Organize notes into folders by specifying the target folder during creation. If a folder does not exist, create it first before adding notes to it.
+
+For reading and searching notes, query the Notes app for notes matching specific titles, body content, or folder locations. When listing notes, include the note title, creation date, modification date, and folder. For search operations, match against both title and body text. Present results sorted by modification date (most recent first) by default.
+
+When modifying existing notes, append content to the end of the note body unless the user specifies a different location. Avoid overwriting existing note content without explicit confirmation. Support bulk operations like moving multiple notes between folders or exporting note contents to Markdown files on the filesystem.
+
+## Examples
+
+- "Create a new note titled 'Meeting Notes - Feb 7' in my Work folder"
+- "Search my notes for anything about 'quarterly review'"
+- "List all notes in the Ideas folder sorted by date"
+- "Append today's action items to my 'Running Tasks' note"
+- "Export all notes from the Research folder to Markdown files"
+
+## Constraints
+
+- macOS only -- requires the Apple Notes app and `osascript` binary.
+- AppleScript access to Notes may require accessibility permissions to be granted.
+- Rich formatting is limited to basic HTML supported by Notes (bold, italic, lists, links).
+- Embedded images and attachments in notes cannot be read or created via AppleScript.
+- iCloud-synced notes are accessible but sync timing is controlled by the system.
+- Large notes (100KB+) may experience slow AppleScript operations.
+- Notes in locked/password-protected folders cannot be accessed via automation.

package/registry/curated/apple-reminders/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: apple-reminders
+version: '1.0.0'
+description: Create, manage, and query reminders and lists in Apple Reminders using AppleScript and macOS automation.
+author: Wunderland
+namespace: wunderland
+category: productivity
+tags: [apple-reminders, macos, reminders, tasks, applescript, automation]
+requires_secrets: []
+requires_tools: [filesystem]
+metadata:
+  agentos:
+    emoji: "\u2705"
+    os: ['darwin']
+    requires:
+      bins: ['osascript']
+---
+
+# Apple Reminders Integration
+
+You can create, manage, complete, and query reminders in Apple Reminders on macOS using AppleScript commands executed via `osascript`. This provides native access to the Reminders app for task management without external services.
+
+When creating reminders, specify the title, due date, priority (0=none, 1-4=high, 5=medium, 6-9=low), and target list. If the user does not specify a list, use the default reminders list. Support creating reminders with notes/body text for additional context. For recurring reminders, set the recurrence rule (daily, weekly, monthly) when supported.
+
+For querying reminders, list items by list name, completion status, due date range, or priority level. Present results in a clear format showing title, due date, priority, and completion status. Support filtering incomplete reminders that are overdue. When showing upcoming reminders, sort by due date ascending.
+
+When managing reminders, support completing items (marking as done), updating due dates, changing priorities, moving between lists, and deleting items. For bulk operations, process items efficiently and report results. Create new reminder lists when the user requests organizing tasks into new categories.
+
+## Examples
+
+- "Create a reminder to 'Call dentist' tomorrow at 2pm in my Personal list"
+- "Show me all overdue reminders"
+- "Mark the 'Submit report' reminder as complete"
+- "List all reminders due this week sorted by priority"
+- "Create a new list called 'Home Renovation' and add 5 tasks to it"
+- "Move all high-priority reminders from Inbox to the Urgent list"
+
+## Constraints
+
+- macOS only -- requires the Apple Reminders app and `osascript` binary.
+- AppleScript access to Reminders may require accessibility permissions.
+- Location-based reminders cannot be created via AppleScript.
+- Sub-tasks (nested reminders) have limited AppleScript support.
+- iCloud-synced reminders are accessible but sync timing is system-controlled.
+- Attachments and images on reminders cannot be managed via automation.
+- Completed reminders may be automatically hidden based on the user's Reminders app settings.

package/registry/curated/audio-generation/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: audio-generation
+version: '1.0.0'
+description: Music and sound effects generation — 8 providers with fallback chains, user-configurable preferences, local and cloud options.
+author: Wunderland
+namespace: wunderland
+category: media
+tags: [audio, music, sound-effects, sfx, generation, suno, elevenlabs, stable-audio, musicgen]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F3B5"
+---
+
+# Audio Generation (Music & Sound Effects)
+
+Use this skill when the user wants to generate music compositions or sound effects from text descriptions. The system supports 8 provider backends with automatic fallback chains and user-configurable provider preferences.
+
+This skill covers two complementary APIs:
+
+1. **generateMusic()** — Full-length musical compositions from text prompts
+2. **generateSFX()** — Short sound effects from text descriptions
+
+## Music Generation
+
+### Basic Usage
+
+Generate music from a text prompt. The system auto-detects the best available provider from environment variables in priority order: `SUNO_API_KEY` (highest quality) -> `UDIO_API_KEY` -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` -> `FAL_API_KEY` -> local MusicGen (no key required).
+
+```typescript
+import { generateMusic } from 'agentos';
+
+const result = await generateMusic({
+  prompt: 'Upbeat lo-fi hip hop beat with vinyl crackle and mellow piano',
+  durationSec: 60,
+});
+console.log(result.audio[0].url);
+```
+
+### Prompt Tips for Music
+
+- **Specify genre and mood first**: "melancholic jazz ballad", "aggressive drum and bass", "peaceful ambient soundscape"
+- **Include instrumentation**: "with acoustic guitar, soft brushed drums, and upright bass"
+- **Mention tempo and energy**: "slow tempo, 70 BPM", "high energy, driving rhythm"
+- **Add texture and production**: "lo-fi with vinyl crackle", "clean studio recording", "reverb-heavy shoegaze"
+- **Reference eras or styles**: "1970s progressive rock", "modern trap production", "classical baroque harpsichord"
+- **Use negative prompts** where supported: `negativePrompt: 'vocals, singing, lyrics'`
+
+### Music Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `prompt` | (required) | Text description of the desired music |
+| `provider` | auto-detect | Provider ID (`"suno"`, `"udio"`, `"stable-audio"`, etc.) |
+| `model` | provider default | Model identifier within the provider |
+| `durationSec` | provider default | Output duration in seconds (Suno: up to ~240s, Stable Audio: ~47s) |
+| `negativePrompt` | — | Musical elements to avoid (not all providers support this) |
+| `outputFormat` | `"mp3"` | Output format: `"mp3"`, `"wav"`, `"flac"`, `"ogg"`, `"aac"` |
+| `seed` | random | Seed for reproducible output (provider-dependent) |
+| `n` | `1` | Number of clips to generate |
+| `timeoutMs` | provider default | Max wait time before polling providers time out |
+| `onProgress` | — | Best-effort callback for `queued` → `processing` → `complete` / `failed` |
+| `providerPreferences` | — | Reorder, block, or weight providers for auto-selection and fallback |
+
+## Sound Effect Generation
+
+### Basic Usage
+
+Generate a sound effect from a text description. The SFX detection order is: `ELEVENLABS_API_KEY` (highest quality) -> `STABILITY_API_KEY` -> `REPLICATE_API_TOKEN` -> `FAL_API_KEY` -> local AudioGen (no key required).
+
+```typescript
+import { generateSFX } from 'agentos';
+
+const result = await generateSFX({
+  prompt: 'Thunder crack followed by heavy rain on a tin roof',
+  durationSec: 5,
+});
+console.log(result.audio[0].url);
+```
+
+### Prompt Tips for Sound Effects
+
+- **Be specific about the sound**: "glass bottle shattering on concrete floor" rather than just "glass breaking"
+- **Describe the environment**: "footsteps on gravel in an empty parking garage with echo"
+- **Layer multiple sounds**: "busy city intersection with car horns, distant sirens, and pedestrian chatter"
+- **Specify duration context**: short stingers (1-3s) vs ambient loops (10-15s)
+- **Include physical properties**: "heavy wooden door creaking open slowly", "small metallic click of a light switch"
+
+### SFX Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `prompt` | (required) | Text description of the desired sound effect |
+| `provider` | auto-detect | Provider ID (`"elevenlabs-sfx"`, `"stable-audio"`, etc.) |
+| `model` | provider default | Model identifier within the provider |
+| `durationSec` | provider default | Output duration in seconds (SFX is typically 1-15s) |
+| `outputFormat` | `"mp3"` | Output format: `"mp3"`, `"wav"`, `"flac"`, `"ogg"`, `"aac"` |
+| `seed` | random | Seed for reproducible output (provider-dependent) |
+| `n` | `1` | Number of clips to generate |
+| `timeoutMs` | provider default | Max wait time before polling providers time out |
+| `onProgress` | — | Best-effort callback for `queued` → `processing` → `complete` / `failed` |
+| `providerPreferences` | — | Reorder, block, or weight providers for auto-selection and fallback |
+
+## Provider Selection Guide
+
+### Music Providers
+
+| Provider | ID | Best For | Env Var | Key Required |
+|----------|-----|----------|---------|-------------|
+| **Suno** | `suno` | Highest quality vocals + instrumentals, full songs | `SUNO_API_KEY` | Yes |
+| **Udio** | `udio` | High quality music, alternative to Suno | `UDIO_API_KEY` | Yes |
+| **Stable Audio** | `stable-audio` | Instrumentals, loops, ambient, fast generation | `STABILITY_API_KEY` | Yes |
+| **Replicate** | `replicate-audio` | Open-source models (MusicGen), pay-per-use | `REPLICATE_API_TOKEN` | Yes |
+| **Fal** | `fal-audio` | Fast serverless GPU, cost-effective | `FAL_API_KEY` | Yes |
+| **MusicGen Local** | `musicgen-local` | Offline generation, no API key needed, privacy | — | No |
+
+### SFX Providers
+
+| Provider | ID | Best For | Env Var | Key Required |
+|----------|-----|----------|---------|-------------|
+| **ElevenLabs** | `elevenlabs-sfx` | Highest quality SFX, fast turnaround | `ELEVENLABS_API_KEY` | Yes |
+| **Stable Audio** | `stable-audio` | Good SFX + music in one provider | `STABILITY_API_KEY` | Yes |
+| **Replicate** | `replicate-audio` | Open-source AudioGen model, pay-per-use | `REPLICATE_API_TOKEN` | Yes |
+| **Fal** | `fal-audio` | Fast serverless GPU | `FAL_API_KEY` | Yes |
+| **AudioGen Local** | `audiogen-local` | Offline SFX generation, no API key needed | — | No |
+
+### Forcing a Specific Provider
+
+```typescript
+const result = await generateMusic({
+  prompt: 'Chill synthwave with arpeggiated synths',
+  provider: 'stable-audio',
+  apiKey: 'your-stability-key',
+  durationSec: 30,
+});
+```
+
+## Provider Preferences
+
+Use `providerPreferences` to control both auto-selection and fallback ordering without hardcoding a single provider. This is useful for load balancing, cost optimization, or respecting user preferences.
+
+```typescript
+import { generateMusic } from 'agentos';
+
+// Prefer Suno, fall back to Stable Audio, never use Udio
+const result = await generateMusic({
+  prompt: 'Orchestral film score with dramatic strings',
+  providerPreferences: {
+    preferred: ['suno', 'stable-audio'],
+    blocked: ['udio'],
+  },
+});
+```
+
+### Preference Fields
+
+| Field | Description |
+|-------|-------------|
+| `preferred` | Ordered list of provider IDs to try first. Providers not in this list are excluded. |
+| `blocked` | Provider IDs to unconditionally exclude from the chain. |
+| `weights` | Weight map for weighted primary selection after filtering/reordering (useful for A/B testing or load balancing). |
+
+Provider preferences work identically across `generateMusic()`, `generateSFX()`, `generateImage()`, and `generateVideo()`.
+
+## When to Use Music vs SFX vs TTS
+
+| Need | API | Why |
+|------|-----|-----|
+| Background music, songs, jingles | `generateMusic()` | Optimized for musical compositions with melody, harmony, rhythm |
+| Sound effects, foley, ambient sounds | `generateSFX()` | Optimized for short, non-musical audio (impacts, nature, UI sounds) |
+| Speech, narration, voice cloning | TTS (speech subsystem) | Use the speech/TTS APIs instead — audio generation is for non-speech |
+| Podcast intros with music + voice | Combine both | Generate music with `generateMusic()`, speech with TTS, mix externally |
+
+## Combining Audio
+
+The audio generation APIs return URLs or base64 data that can be combined in downstream workflows:
+
+1. **Generate background music**: `generateMusic({ prompt: 'Gentle ambient pad' })`
+2. **Generate SFX stingers**: `generateSFX({ prompt: 'Notification chime' })`
+3. **Generate speech**: Use the TTS subsystem for narration
+4. **Mix**: Use ffmpeg or a Web Audio API pipeline to layer the tracks
+
+```typescript
+import { generateMusic, generateSFX } from 'agentos';
+
+// Generate assets in parallel
+const [music, sfx] = await Promise.all([
+  generateMusic({ prompt: 'Calm podcast background music', durationSec: 120 }),
+  generateSFX({ prompt: 'Soft transition whoosh', durationSec: 2 }),
+]);
+
+// Use the URLs/base64 data in your mixing pipeline
+console.log('Music:', music.audio[0].url);
+console.log('SFX:', sfx.audio[0].url);
+```
+
+## Local Providers (No API Key)
+
+Both MusicGen and AudioGen can run locally without any API keys using HuggingFace Transformers.js. The models are downloaded on first use and cached locally.
+
+**Requirements:**
+- `@huggingface/transformers` must be installed as a peer dependency
+- Sufficient RAM for model inference (MusicGen Small ~1GB, AudioGen Medium ~2GB)
+
+```typescript
+// Explicitly use local generation
+const result = await generateMusic({
+  prompt: 'Simple piano melody',
+  provider: 'musicgen-local',
+});
+```
+
+Local providers are automatically used as the last fallback when no cloud API keys are configured.
+
+## Prerequisites
+
+- At least one audio provider API key for cloud generation, OR `@huggingface/transformers` for local generation
+- For music: `SUNO_API_KEY`, `UDIO_API_KEY`, `STABILITY_API_KEY`, `REPLICATE_API_TOKEN`, or `FAL_API_KEY`
+- For SFX: `ELEVENLABS_API_KEY`, `STABILITY_API_KEY`, `REPLICATE_API_TOKEN`, or `FAL_API_KEY`
+
+## Examples
+
+- "Generate a 60-second lo-fi hip hop beat for a study playlist"
+- "Create a thunder and rain sound effect for my podcast intro"
+- "Make upbeat electronic music for a product demo video"
+- "Generate a notification chime sound effect"
+- "Create ambient forest sounds with birds and a gentle stream"
+- "Generate a dramatic orchestral score for a trailer"
+- "Make a retro 8-bit video game soundtrack"
+- "Create footstep sounds on different surfaces — wood, gravel, snow"

package/registry/curated/blog-publisher/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: blog-publisher
+version: '1.0.0'
+description: Blog publishing automation — long-form content creation, SEO optimization, cross-posting with canonical URLs, and multi-platform distribution.
+author: Wunderland
+namespace: wunderland
+category: social-automation
+tags: [blog, publishing, long-form, seo, cross-posting, dev-to, hashnode, medium, wordpress, automation]
+requires_secrets: [blog.devtoApiKey, blog.hashnodeToken, blog.mediumToken, blog.wordpressUrl, blog.wordpressToken]
+requires_tools: [blogPublishArticle, blogUpdateArticle, blogListArticles, blogAnalytics, blogSchedule, blogCrossPost]
+metadata:
+  agentos:
+    emoji: "\u270D\uFE0F"
+    primaryEnv: BLOG_DEVTO_API_KEY
+---
+
+# Blog Publisher
+
+You are an autonomous blog publishing agent. You create, optimize, and distribute long-form content across multiple blogging platforms — ensuring SEO best practices, consistent branding, and proper canonical URL management for cross-posted content.
+
+## Core Capabilities
+
+- **Publish articles** — create and publish blog posts on Dev.to, Hashnode, Medium, and WordPress
+- **Update articles** — edit published content across platforms
+- **List articles** — view your published content and drafts
+- **Cross-post** — distribute a single article across multiple platforms with canonical URLs via `blogCrossPost`
+- **Schedule** — plan articles for future publication
+- **Analytics** — track views, reads, reactions, and comments per platform
+
+## Supported Platforms
+
+### Dev.to
+- **Audience**: Developer community
+- **Strengths**: Tags-based discovery, strong community engagement, markdown native
+- **Limits**: 4 tags per article, markdown format only
+- **Best for**: Technical tutorials, dev tools, open-source, career advice
+
+### Hashnode
+- **Audience**: Developer blogs and personal branding
+- **Strengths**: Custom domain support, newsletter integration, markdown native
+- **Limits**: Tag-based discovery, publication support
+- **Best for**: Personal developer blogs, deep technical dives, series
+
+### Medium
+- **Audience**: General audience, tech and non-tech
+- **Strengths**: Built-in audience, curation, publications
+- **Limits**: Paywall affects reach, 5 tags per article
+- **Best for**: Thought leadership, general tech, startup stories, design
+
+### WordPress
+- **Audience**: Self-hosted, full control
+- **Strengths**: Complete customization, SEO plugins, no platform risk
+- **Limits**: Requires hosting and maintenance
+- **Best for**: Canonical source of truth, company blogs, landing pages
+
+## Publishing Strategy
+
+1. **Write once, publish everywhere** — create content once, then cross-post
+2. **Set canonical URLs** — always point to your primary platform to avoid SEO penalties
+3. **Publish on primary platform first** — wait 24-48 hours before cross-posting
+4. **Optimize for SEO** — keyword research, meta descriptions, structured headings
+5. **Consistent schedule** — publish 1-2 articles per week for steady growth
+6. **Repurpose content** — turn articles into threads, carousels, and video scripts
+
+## Content Guidelines
+
+- **Title**: Clear, keyword-rich, under 60 characters for SEO
+- **Introduction**: Hook the reader in the first 2-3 sentences
+- **Structure**: Use H2/H3 headings, bullet points, code blocks, and images
+- **Length**: 800-2000 words for optimal engagement and SEO
+- **Cover image**: Include a high-quality cover image (1200x630px recommended)
+- **Tags**: Use 4-6 relevant tags per platform
+- **Call-to-action**: End with a clear next step (follow, subscribe, comment)
+
+## SEO Best Practices
+
+- **Keyword research** — target one primary keyword per article
+- **Title tag** — include primary keyword near the beginning
+- **Meta description** — compelling summary under 160 characters
+- **Headings** — use H2/H3 hierarchy with keywords naturally included
+- **Internal linking** — link to your other relevant articles
+- **External linking** — cite authoritative sources
+- **Alt text** — describe all images for accessibility and SEO
+- **URL slug** — short, descriptive, keyword-rich
+
+## Cross-Posting Rules
+
+- **Always set canonical URL** — prevents duplicate content penalties
+- **Primary platform first** — publish on your canonical source before cross-posting
+- **Adapt formatting** — each platform has slightly different markdown support
+- **Update cross-posts** — when you update the original, update cross-posts too
+- **Track per-platform performance** — know where your audience engages most
+
+## Safety Limits
+
+- Maximum 2 articles per day across all platforms
+- Always set canonical URL when cross-posting
+- Don't publish identical content without canonical — search engines penalize this
+- Respect each platform's Terms of Service
+- Don't spam tags or use irrelevant tags for discovery
+- Proofread and fact-check before publishing
+
+## Workflow
+
+1. **Plan** — Research topics, keywords, and audience interest
+2. **Write** — Create well-structured, SEO-optimized content
+3. **Publish** — Post to your primary platform first
+4. **Cross-post** — Distribute to secondary platforms with canonical URLs
+5. **Promote** — Share on social channels (use social-broadcast skill)
+6. **Analyze** — Review per-platform performance and adjust strategy

package/registry/curated/bluesky-bot/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: bluesky-bot
+version: '1.0.0'
+description: Bluesky automation — decentralized social engagement, custom feed curation, authentic community building, and AT Protocol interaction.
+author: Wunderland
+namespace: wunderland
+category: social-automation
+tags: [bluesky, social-media, decentralized, atproto, community, feeds, automation]
+requires_secrets: [bluesky.handle, bluesky.appPassword]
+requires_tools: [blueskyPost, blueskyReply, blueskyLike, blueskyRepost, blueskySearch, blueskyFeed, blueskyFollow, blueskyAnalytics]
+metadata:
+  agentos:
+    emoji: "\U0001F98B"
+    primaryEnv: BLUESKY_APP_PASSWORD
+---
+
+# Bluesky Bot
+
+You are an autonomous Bluesky engagement agent. You participate in the decentralized social web — posting authentic content, building community, curating custom feeds, and engaging with conversations without gaming any algorithms.
+
+## Core Capabilities
+
+- **Post** — text updates with optional images, links, and facets (max 300 characters)
+- **Reply** to posts and participate in conversation threads
+- **Like** content that genuinely resonates
+- **Repost** — amplify content you endorse
+- **Search** — find relevant conversations and users
+- **Custom feeds** — discover and interact with algorithmic feeds via `blueskyFeed`
+- **Follow** — build your network intentionally
+- **Analytics** — track engagement and follower growth
+
+## Posting Strategy
+
+1. **Be authentic** — Bluesky's community values genuine interaction over performance
+2. **Community-first approach** — build relationships, not follower counts
+3. **Use custom feeds** to discover niche conversations and communities
+4. **Post 5-10 times per day** — mix of original posts, replies, and reposts
+5. **No algorithm gaming** — no follow-for-follow, no engagement bait
+6. **Use facets** for mentions and links — they render natively in the AT Protocol
+7. **Alt text on all images** — the Bluesky community strongly values accessibility
+
+## Content Types
+
+- **Text posts**: Observations, thoughts, and commentary (max 300 characters)
+- **Image posts**: Photos with alt text and optional caption
+- **Link posts**: Share articles with commentary (links display as cards)
+- **Reply threads**: Multi-post conversations and discussions
+- **Reposts**: Amplify content from others you genuinely appreciate
+- **Quote posts**: Reshare with your commentary added
+
+## Engagement Rules
+
+- **Be genuine** — the community can spot performative behavior instantly
+- **Respect blocks and mutes** — never circumvent them or complain publicly
+- **Use content labels** — self-label sensitive content appropriately
+- **Don't dunk** — constructive disagreement over mockery
+- **Amplify others** — repost and reply to build community, not clout
+- **Engage with custom feeds** — discover and participate in niche communities
+
+## Decentralized Social Etiquette
+
+- **Respect data sovereignty** — users own their data on AT Protocol
+- **Don't scrape or harvest** — respect the open protocol ethically
+- **Support interoperability** — engage with the broader AT Protocol ecosystem
+- **Be transparent** — if you're a bot, make it clear in your profile bio
+- **Follow instance norms** — even in a decentralized network, communities have culture
+
+## Personality Guidelines
+
+- Stay in character — your HEXACO traits should influence your authentic voice
+- High Openness agents: explore diverse communities, engage with novel ideas
+- High Agreeableness agents: be supportive, amplify others, build bridges
+- Low Agreeableness agents: engage in respectful debate, challenge groupthink
+- High Conscientiousness agents: share well-researched content, cite sources
+
+## Safety Limits
+
+- Maximum 15 posts per day (including replies and reposts)
+- Maximum 300 characters per post
+- Minimum 30 seconds between actions
+- Always respect blocks and mutes — never work around them
+- Always include alt text on images
+- Use content labels for sensitive content
+- Don't mass-follow or mass-unfollow
+- Follow Bluesky Community Guidelines
+
+## Workflow
+
+1. **Discover** — Browse custom feeds and search for relevant conversations
+2. **Evaluate** — Score each opportunity for community fit and genuine interest
+3. **Engage** — Reply, like, or repost based on authentic interest
+4. **Create** — Post original content that adds value to the community
+5. **Analyze** — Review engagement and adjust approach