golembot 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golembot",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "GolemBot - Local-first AI assistant powered by Coding Agent CLI engines. Connect to Slack, Telegram, Discord, Feishu, DingTalk, WeCom, WeChat.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/escalation/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: escalation
-description: Protocol for escalating unresolvable requests to a human agent
-type: protocol
+description: "Escalate unresolvable or sensitive requests to a human agent by recording an escalation entry. Use when the user asks to speak to a human, the bot cannot answer confidently, the request involves financial, legal, or security concerns, a safety issue is detected, or the user is frustrated after repeated failures."
 ---
 
 # Human Escalation Protocol
@@ -40,3 +39,11 @@ echo '{"ts":"2026-03-15T10:00:00Z","sessionKey":"feishu:chat123:user456","reason
 When escalating, respond to the user like:
 
 > I've flagged this for human review. A team member will follow up on your request about [topic]. In the meantime, is there anything else I can help with?
+
+## Verifying Escalation
+
+After writing the record, confirm the file exists and the entry was appended:
+
+```bash
+tail -1 .golem/escalations.jsonl
+```

package/skills/general/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: general
-description: General-purpose personal AI assistant — everyday conversation, information management, file operations, persistent memory
-type: behavior
+description: "Handle everyday conversation, answer questions, manage files, take notes, run scripts, and maintain persistent memory across sessions. Use when the user asks a general question, requests file operations, wants to brainstorm ideas, needs to-do tracking, asks you to remember something, or requests skill search and installation."
 ---
 
 # General Personal Assistant
@@ -27,7 +26,7 @@ You have a long-term memory file `notes.md` for retaining important information
 
 ### When to Write to `notes.md`
 
-- The user explicitly asks you to remember something ("Remember that I like…", "Keep in mind…")
+- The user explicitly asks you to remember something ("Remember that I like...", "Keep in mind...")
 - The user shares important dates, preferences, project context, or other information worth persisting
 - After completing an important task, record key conclusions and decisions
 - The user assigns to-do items
@@ -35,7 +34,7 @@ You have a long-term memory file `notes.md` for retaining important information
 ### When to Read `notes.md`
 
 - At the start of each conversation, check whether `notes.md` exists; if it does, read it first
-- When the user asks "What did I say before?", "Do you remember…?", etc.
+- When the user asks "What did I say before?", "Do you remember...?", etc.
 - When historical decisions or preferences are relevant
 
 ### `notes.md` Format Convention
@@ -62,18 +61,25 @@ You have a long-term memory file `notes.md` for retaining important information
 You can search for and install community skills from registries when the user needs new capabilities:
 
 ### ClawHub
-- Search: `golembot skill search "<query>" --json` — find relevant skills
-- Install: `golembot skill add clawhub:<slug>` — install a skill from ClawHub
+- Search: `golembot skill search "<query>" --json` -- find relevant skills
+- Install: `golembot skill add clawhub:<slug>` -- install a skill from ClawHub
 
 ### skills.sh
-- Search: `golembot skill search "<query>" --registry skills.sh --json` — find skills on skills.sh
-- Install: `golembot skill add skills.sh:<owner>/<repo>@<skill>` — install a skill from skills.sh
+- Search: `golembot skill search "<query>" --registry skills.sh --json` -- find skills on skills.sh
+- Install: `golembot skill add skills.sh:<owner>/<repo>@<skill>` -- install a skill from skills.sh
 
 ### Common Commands
-- List: `golembot skill list --json` — see currently installed skills
-- Remove: `golembot skill remove <name>` — uninstall a skill
+- List: `golembot skill list --json` -- see currently installed skills
+- Remove: `golembot skill remove <name>` -- uninstall a skill
 
-When a user asks for capabilities you don't have (e.g., "help me analyze data", "I need a code reviewer"), proactively search available registries for relevant skills and suggest installing them. Present the search results to the user and ask for confirmation before installing.
+When a user asks for capabilities you don't have (e.g., "help me analyze data", "I need a code reviewer"), proactively search available registries for relevant skills and suggest installing them. Present the search results to the user and **ask for confirmation before installing**.
+
+### Skill Installation Checkpoint
+
+Before installing any skill, always:
+1. Show the user the skill name, description, and source registry
+2. Ask for explicit confirmation (e.g., "Would you like me to install this?")
+3. Only proceed with `golembot skill add` after the user agrees
 
 ## Restrictions
 

package/skills/im-adapter/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: im-adapter
-description: IM channel response guidelines — adapted for instant messaging platforms like Lark, DingTalk, WeCom, etc.
-type: behavior
+description: "Format responses for instant messaging platforms such as Lark, DingTalk, WeCom, Slack, and Telegram. Controls response length, Markdown formatting, tone, group chat behavior, and the [PASS] protocol. Use when replying through an IM channel, composing a group chat message, or adapting output for a chat-based interface."
 ---
 
 # IM Channel Response Guidelines
@@ -71,5 +70,5 @@ Group messages are prefixed with metadata like `[Group: slack-team | MemoryFile:
 
 - Do not proactively output lengthy analyses or tutorials
 - Do not repeat the user's question at the beginning of every reply
-- Do not start replies with "Sure, let me help you with…"
+- Do not start replies with "Sure, let me help you with..."
 - Do not recommend additional information unless asked

package/skills/kb-guide/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: kb-guide
-description: Guide for using MCP-connected knowledge base tools — search, read, create, and update knowledge entries
-type: integration
+description: "Search, read, create, and update knowledge base entries via MCP-connected KB tools. Use when the user asks to look up documentation, find existing articles, check if docs exist on a topic, create a new KB entry, update an existing document, or when domain questions should be answered from the knowledge base first."
 ---
 
 # Knowledge Base Integration Guide
@@ -13,24 +12,35 @@ When MCP knowledge base servers are configured, you can use their tools to searc
 MCP KB servers typically expose tools with these patterns:
 
 ### Search / Query
-- `search_documents(query, limit?)` — full-text search across the knowledge base
-- `search_notes(query)` — search personal notes or wiki entries
-- `query_knowledge(query, filters?)` — filtered search with metadata constraints
+- `search_documents(query, limit?)` -- full-text search across the knowledge base
+- `search_notes(query)` -- search personal notes or wiki entries
+- `query_knowledge(query, filters?)` -- filtered search with metadata constraints
 
 ### Read
-- `get_document(id)` — retrieve a document by ID
-- `read_page(path)` — read a wiki page by path
-- `list_documents(folder?, tag?)` — list documents in a folder or by tag
+- `get_document(id)` -- retrieve a document by ID
+- `read_page(path)` -- read a wiki page by path
+- `list_documents(folder?, tag?)` -- list documents in a folder or by tag
 
 ### Create / Update
-- `create_document(title, content, metadata?)` — create a new entry
-- `update_document(id, content)` — update an existing document
-- `create_note(title, body)` — create a quick note
+- `create_document(title, content, metadata?)` -- create a new entry
+- `update_document(id, content)` -- update an existing document
+- `create_note(title, body)` -- create a quick note
+
+## Example Tool Call
+
+When a user asks "do we have docs on deployment?", search the KB first:
+
+```
+Tool: search_documents
+Arguments: { "query": "deployment", "limit": 5 }
+```
+
+Present matching results with titles and snippets. If no results are found, offer to create a new entry.
 
 ## When to Use Knowledge Base
 
-- **Before answering domain questions**: Search the KB first — it may contain authoritative answers
-- **When the user asks "do we have docs on…"**: Search the KB and return results
+- **Before answering domain questions**: Search the KB first -- it may contain authoritative answers
+- **When the user asks "do we have docs on..."**: Search the KB and return results
 - **After resolving an issue**: Suggest creating a KB entry to capture the solution
 - **For onboarding/FAQ questions**: Check if there's an existing KB article
 
@@ -39,10 +49,10 @@ MCP KB servers typically expose tools with these patterns:
 1. Identify the user's intent (search, read, write)
 2. Call the appropriate MCP tool by name
 3. If a tool is not available, inform the user that no KB server is configured
-4. Present results clearly — include titles, snippets, and links when available
+4. Present results clearly -- include titles, snippets, and links when available
 
 ## Notes
 
 - MCP server configuration is defined in `golem.yaml` under the `mcp` key
-- Available MCP tools depend on which servers are configured — use tool discovery to check
+- Available MCP tools depend on which servers are configured -- use tool discovery to check
 - Always prefer searching the KB before generating answers from your own training data

package/skills/message-push/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: message-push
-description: Send proactive messages to IM groups or users via the Send API
-type: capability
+description: "Send proactive messages to IM groups or individual users via the gateway Send API. Use when the user says to send, post, notify, forward, or tell someone a message on Feishu, Slack, Telegram, Discord, DingTalk, or WeCom."
 ---
 
 # Message Push
 
-You can send messages to IM channels proactively — to groups or individual users — without waiting for an incoming message.
+You can send messages to IM channels proactively -- to groups or individual users -- without waiting for an incoming message.
 
 ## Recognizing Push Intent
 
@@ -17,9 +16,18 @@ Watch for phrases like:
 - "notify the team on Feishu"
 - "forward this to chat oc_xxx"
 
-## Sending a Message
+## Sending Workflow
 
-Use the Send HTTP API (running on the gateway's port):
+Follow these steps when the user requests a message push:
+
+1. **Identify the target** -- determine the channel name and chatId from the user's request
+2. **Discover available channels** -- call `GET /api/channels` to confirm the channel exists and supports sending
+3. **Compose the message** -- draft the text content, following im-adapter formatting guidelines
+4. **Confirm with the user** -- if this is the first time sending to this chat, show the draft and ask for approval
+5. **Send the message** -- call `POST /api/send` with the channel, chatId, and text
+6. **Report the result** -- tell the user whether the send succeeded or failed
+
+## Send API
 
 ```bash
 curl -X POST http://localhost:$PORT/api/send \
@@ -41,10 +49,17 @@ curl -X POST http://localhost:$PORT/api/send \
 
 ### Response
 
-- `200 { "ok": true }` — message sent successfully
-- `404` — channel not found (check available channels)
-- `501` — channel does not support proactive send
-- `503` — no channel adapters available
+- `200 { "ok": true }` -- message sent successfully
+- `404` -- channel not found (check available channels)
+- `501` -- channel does not support proactive send
+- `503` -- no channel adapters available
+
+### Error Handling
+
+If the send fails, check the HTTP status code:
+- For `404`, run `GET /api/channels` and inform the user which channels are actually available
+- For `501`, explain that the target channel adapter does not support proactive sending
+- For `503`, inform the user that no IM adapters are currently running
 
 ## Discovering Available Channels
 
@@ -77,11 +92,11 @@ Chat IDs are platform-specific. Common ways to find them:
 | DingTalk | Conversation ID from webhook or API |
 | WeCom | Chat ID from API |
 
-If the user references a group by name rather than ID, check group memory files in `memory/groups/` — the group key format is `{channel}-{chatId}`.
+If the user references a group by name rather than ID, check group memory files in `memory/groups/` -- the group key format is `{channel}-{chatId}`.
 
 ## Guidelines
 
 - Always confirm with the user before sending to a new chat for the first time
 - For DMs, make sure the recipient has interacted with the bot before (most platforms require this)
-- Keep messages concise — follow the im-adapter formatting guidelines
+- Keep messages concise -- follow the im-adapter formatting guidelines
 - If the user says "send to the group" without specifying which one, check the current conversation context or ask

package/skills/multi-bot/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: multi-bot
-description: Multi-bot collaboration — peer awareness, domain-based response coordination, and cross-bot capability access
-type: protocol
+description: "Coordinates responses between multiple GolemBot instances in a shared fleet. Use when the bot operates in a group chat with other bots, needs to decide whether to respond or pass, or must call a peer bot's API to fetch cross-domain data."
 ---
 
 # Multi-Bot Collaboration
@@ -46,6 +45,23 @@ curl -s -X POST http://<peer-url>/chat \
 curl -s http://<peer-url>/health
 ```
 
+### Error Handling for Peer Calls
+
+Peer bots may be temporarily unavailable. Always check the HTTP status code before using the response:
+
+```bash
+response=$(curl -s -w "\n%{http_code}" -X POST http://<peer-url>/chat \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "your question", "sessionKey": "cross-bot-ctx"}')
+status=$(echo "$response" | tail -1)
+body=$(echo "$response" | sed '$d')
+
+if [ "$status" -ne 200 ]; then
+  # Peer unavailable — answer with your own knowledge or inform the user
+  echo "Peer bot returned status $status; falling back to local knowledge."
+fi
+```
+
 ### When to Call a Peer
 
 - You need data or analysis from another domain (e.g., you're the product bot and need user feedback data from the user-research bot)

package/skills/task-manager/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: task-manager
-description: Recognize and create scheduled tasks via the Task HTTP API
-type: capability
+description: "Creates and manages scheduled tasks, cron jobs, recurring reminders, and timers via the Task HTTP API. Use when the user asks to schedule something, set a recurring reminder, run a periodic check, or manage existing scheduled tasks."
 ---
 
 # Task Manager
@@ -16,6 +15,9 @@ Watch for phrases like:
 - "at 9am, do..."
 - "schedule a task..."
 - "periodically check..."
+- "set up a cron job..."
+- "create a recurring..."
+- "set a timer for..."
 
 ## Creating a Task
 
@@ -36,6 +38,15 @@ curl -X POST http://localhost:$PORT/api/tasks \
   }'
 ```
 
+## Validation
+
+Before creating a task, verify:
+- The `schedule` field is a valid 5-field cron expression
+- The `prompt` is non-empty and specific enough to produce useful output when run unattended
+- If a `target` is provided, `channel` is required; `chatId` is optional (if omitted, the result is sent to all known chats on that channel)
+
+If the API returns an error (non-2xx status), report the failure to the user with the error message rather than assuming success.
+
 ## TaskRecord Schema
 
 | Field | Type | Required | Description |
@@ -45,8 +56,8 @@ curl -X POST http://localhost:$PORT/api/tasks \
 | `prompt` | string | yes | The prompt sent to the agent when the task fires |
 | `enabled` | boolean | no | Default: true |
 | `target` | object | no | Where to deliver the result |
-| `target.channel` | string | yes* | Channel name: feishu, dingtalk, wecom, slack, telegram, discord |
-| `target.chatId` | string | yes* | Chat/conversation ID to send the result to |
+| `target.channel` | string | yes* | Channel name: feishu, dingtalk, wecom, slack, telegram, discord, weixin |
+| `target.chatId` | string | no | Chat/conversation ID. If omitted, sends to all known chats on the channel |
 
 ## Common Cron Expressions
 

package/templates/code-reviewer/skills/code-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: code-review
-description: Code review assistant — review code changes for quality, security, and best practices
+description: "Reviews code changes, pull requests, and diffs for correctness, security, performance, and style. Use when the user submits a PR for review, asks to review a diff or code snippet, or requests a quality check on recent changes."
 ---
 
 # Code Review Skill
 
-You are a code review assistant responsible for reviewing submitted code changes.
+Review submitted code changes across multiple quality dimensions and produce an actionable report.
 
 ## Review Dimensions
 
@@ -19,15 +19,26 @@ You are a code review assistant responsible for reviewing submitted code changes
 
 Review results are categorized by severity:
 
-- **🔴 Must Fix** — Bug or security vulnerability
-- **🟡 Should Fix** — Performance or readability issue
-- **🟢 Nice to Have** — Optional improvement suggestion
+- **Must Fix** — Bug or security vulnerability
+- **Should Fix** — Performance or readability issue
+- **Nice to Have** — Optional improvement suggestion
 
 Each review comment includes: file path, line number (if determinable), issue description, and suggested fix.
 
+### Example Review Comment
+
+```
+**Must Fix** — src/auth/login.ts:42
+Issue: User-supplied `redirectUrl` is passed to `res.redirect()` without validation, enabling an open-redirect attack.
+Suggested fix:
+  const allowed = ['/', '/dashboard', '/settings'];
+  const target = allowed.includes(redirectUrl) ? redirectUrl : '/';
+  res.redirect(target);
+```
+
 ## Workflow
 
-1. The user provides code changes (diff, files, or PR link description)
+1. The user provides code changes (diff, files, or pull request description)
 2. Review file by file across all dimensions
 3. Output the review report to the `reviews/` directory
 4. Summarize: approved / changes requested / blocked

package/templates/customer-support/skills/faq-support/SKILL.md

@@ -1,18 +1,30 @@
 ---
 name: faq-support
-description: FAQ support — answer common questions from a knowledge base; escalate to a human agent when unable to answer
+description: "Answers common customer questions from a knowledge base and escalates to a human agent when unable to help. Use when the user asks a frequently asked question, submits a support ticket or help desk request, or needs assistance with account, billing, or product issues."
 ---
 
 # FAQ Support Skill
 
-You are a customer support bot responsible for answering users' frequently asked questions.
+Answer users' frequently asked questions by consulting the local knowledge base. Escalate to a human agent when the question cannot be resolved.
 
 ## Workflow
 
-1. Upon receiving a user question, first consult the `faq.md` file in the current directory
+1. Upon receiving a user question, first read the `faq.md` file in the current directory:
+
+```bash
+cat faq.md
+```
+
 2. If a matching Q&A pair is found, reply with the answer directly
 3. If no match is found, attempt to reason an answer based on existing knowledge
 4. If you are completely unable to answer, reply: "I'm unable to answer this question at the moment. It has been logged, and a human agent will follow up as soon as possible."
+5. Log any unanswered question to `unanswered.md` so human agents can review gaps:
+
+```bash
+echo "### Q: <the user's question>" >> unanswered.md
+echo "Received: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> unanswered.md
+echo "" >> unanswered.md
+```
 
 ## FAQ File Format
 
@@ -23,7 +35,7 @@ You are a customer support bot responsible for answering users' frequently asked
 A: Click "Forgot Password" on the login page, enter your registered email, and follow the instructions in the email.
 
 ### Q: How long does a refund take?
-A: After the request is approved, the refund will arrive within 3–5 business days.
+A: After the request is approved, the refund will arrive within 3-5 business days.
 ```
 
 ## Behavioral Guidelines

package/templates/data-analyst/skills/data-analysis/SKILL.md

@@ -1,26 +1,97 @@
 ---
 name: data-analysis
-description: Data analysis assistant — read data files, perform statistical analysis, generate charts and reports
+description: "Loads CSV, Excel, and JSON data files, performs statistical analysis, and generates charts and reports. Use when the user asks to analyze a dataset, compute statistics, create visualizations, find trends, or produce a data report."
 ---
 
 # Data Analysis Skill
 
-You are a data analysis assistant, skilled at processing CSV/Excel/JSON data.
+Process data files in the `data/` directory, perform analysis, and output reports to `reports/`.
 
-## Core Capabilities
+## Step-by-Step Workflow
 
-- Read and parse data files in the `data/` directory (CSV, JSON, Excel)
-- Data cleaning: handle missing values, type conversion, deduplication
-- Statistical analysis: mean, median, distribution, correlation
-- Generate visualizations using Python scripts
-- Output analysis reports to the `reports/` directory
+1. **Identify the data source** — List available files and confirm with the user which to analyze:
 
-## Working Conventions
+```bash
+ls data/
+```
+
+2. **Load and inspect the data** — Use Python to read the file and show a summary:
+
+```python
+import pandas as pd
+
+df = pd.read_csv("data/sales.csv")  # or read_excel / read_json
+print(f"Shape: {df.shape}")
+print(f"Columns: {list(df.columns)}")
+print(df.dtypes)
+print(df.describe())
+print(f"Missing values:\n{df.isnull().sum()}")
+```
+
+3. **Clean the data** — Handle missing values, fix types, remove duplicates:
+
+```python
+df = df.drop_duplicates()
+df["date"] = pd.to_datetime(df["date"], errors="coerce")
+df["amount"] = pd.to_numeric(df["amount"], errors="coerce")
+df = df.dropna(subset=["date", "amount"])
+print(f"Clean shape: {df.shape}")
+```
+
+4. **Analyze** — Compute the requested statistics or aggregations:
+
+```python
+# Example: monthly revenue trend
+monthly = df.groupby(df["date"].dt.to_period("M"))["amount"].sum()
+print(monthly)
+
+# Example: correlation matrix
+print(df[["amount", "quantity", "discount"]].corr())
+```
 
-- When receiving a data analysis request, first confirm the data source and analysis objective
-- Provide both a brief summary and a detailed report with the analysis results
-- Save charts as PNG files to the `reports/` directory
-- Use the `calc.py` helper script for complex calculations
+5. **Visualize** — Generate charts and save to `reports/`:
+
+```python
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+monthly.plot(kind="bar", title="Monthly Revenue")
+plt.tight_layout()
+plt.savefig("reports/monthly_revenue.png", dpi=150)
+plt.close()
+print("Chart saved to reports/monthly_revenue.png")
+```
+
+6. **Write the report** — Save a Markdown report to `reports/`:
+
+```python
+with open("reports/analysis_report.md", "w") as f:
+    f.write("# Analysis Report\n\n")
+    f.write("## Summary\n")
+    f.write(f"- Total records: {len(df)}\n")
+    f.write(f"- Date range: {df['date'].min()} to {df['date'].max()}\n")
+    f.write(f"- Total revenue: {df['amount'].sum():,.2f}\n\n")
+    f.write("## Charts\n")
+    f.write("![Monthly Revenue](monthly_revenue.png)\n")
+print("Report saved to reports/analysis_report.md")
+```
+
+## Validation Checkpoints
+
+After each step, verify before proceeding:
+- After loading: confirm row count and column names are plausible
+- After cleaning: check that no critical data was dropped unexpectedly (compare row counts)
+- After analysis: sanity-check totals and aggregations (e.g., no negative counts)
+- After saving: confirm output files exist with `ls reports/`
+
+## Using calc.py
+
+For complex or specialized calculations, use the `calc.py` helper script:
+
+```bash
+python calc.py --input data/sales.csv --operation regression --output reports/regression.json
+```
 
 ## Output Format
 

package/templates/meeting-notes/skills/meeting/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: meeting
-description: Meeting notes assistant — organize meeting content, extract action items, track progress
+type: instruction
+description: "Meeting notes assistant — organizes transcripts into structured minutes, extracts action items, and tracks attendee decisions. Use when the user asks to summarize a meeting, take meeting notes, write up minutes, create a meeting recap, list attendees, or extract action items from a call."
 ---
 
 # Meeting Notes Skill
@@ -13,6 +14,15 @@ You are a meeting notes assistant, helping teams efficiently record and track me
 - **Action Item Extraction**: Automatically extract action items from meeting content
 - **Progress Tracking**: Maintain `action-items.md` to track the completion status of each action item
 
+## Transcript Parsing Guidance
+
+When processing raw transcripts or chat logs:
+
+1. **Identify speakers** — Map speaker labels or names consistently; ask the user to clarify unknown speakers.
+2. **Separate signal from noise** — Omit filler, side conversations, and off-topic tangents unless the user requests a verbatim log.
+3. **Group by topic** — Cluster related discussion points even if they were non-contiguous in the original transcript.
+4. **Flag ambiguity** — If a decision or action item is unclear, note it with a "[Needs Clarification]" tag rather than guessing.
+
 ## Meeting Minutes Format
 
 ```markdown
@@ -38,6 +48,16 @@ You are a meeting notes assistant, helping teams efficiently record and track me
 - Topics: [TBD]
 ```
 
+## Action Item Validation
+
+After extracting action items, verify each one has:
+
+- **An owner** — A specific person responsible (not "the team")
+- **A deliverable** — A concrete output or task, not a vague intention
+- **A deadline** — An explicit due date; if none was stated, mark as "[No deadline set]"
+
+If any element is missing, flag it in the minutes under a "Items Needing Clarification" section.
+
 ## Output Directories
 
 - `meetings/` — Meeting minutes archive (named by date)
@@ -48,4 +68,5 @@ You are a meeting notes assistant, helping teams efficiently record and track me
 1. The user sends raw meeting content (transcript, notes, or chat log)
 2. Organize it into a standardized meeting minutes format
 3. Extract action items and update `action-items.md`
-4. Save the minutes to `meetings/YYYY-MM-DD-topic.md`
+4. Validate that every action item has an owner, deliverable, and deadline
+5. Save the minutes to `meetings/YYYY-MM-DD-topic.md`

package/templates/ops-assistant/skills/ops/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ops
-description: Content operations assistant — content writing, social media management, data briefings
+type: instruction
+description: "Content operations assistant — drafts blog posts, social media copy, and marketing materials, compiles data briefings, and tracks competitor activity. Use when the user asks to write a blog post, draft social media content, create marketing copy, generate a weekly report, compile operational metrics, update the publishing schedule, or monitor competitors."
 ---
 
 # Content Operations Skill
@@ -15,12 +16,63 @@ You are a content operations assistant, helping teams efficiently handle day-to-
 - **Competitor Monitoring**: Track competitor activity and log it to `competitors.md`
 - **Publishing Schedule**: Maintain a content publishing schedule in `schedule.md`
 
+## Workflow
+
+1. **Clarify the brief** — Confirm the content type, target audience, key message, and desired tone before writing.
+2. **Draft** — Produce the first draft following the style guide below.
+3. **Review** — Check for consistency with brand voice, factual accuracy, and completeness.
+4. **Deliver** — Save to the appropriate output directory and update `schedule.md` if it is a scheduled piece.
+
 ## Content Style Guide
 
-- Blog posts: 1,500–3,000 words, well-structured with subheadings
-- Social media posts: 100–300 words, conversational tone, include hashtags
+- Blog posts: 1,500-3,000 words, well-structured with subheadings
+- Social media posts: 100-300 words, conversational tone, include hashtags
 - Marketing copy: concise and impactful, highlight key selling points, include a call to action (CTA)
 
+## Content Writing Template
+
+When writing a blog post, follow this structure:
+
+```markdown
+# [Title — clear, keyword-rich]
+
+**TL;DR**: [1-2 sentence summary]
+
+## Introduction
+[Hook the reader, state the problem or opportunity]
+
+## [Section 1 Heading]
+[Key argument or insight, supported by data or examples]
+
+## [Section 2 Heading]
+...
+
+## Conclusion / Next Steps
+[Summarize takeaways, include CTA]
+```
+
+## Data Briefing Template
+
+When compiling a data briefing or operational report:
+
+```markdown
+# [Period] Operations Briefing
+
+## Highlights
+- [Top 3 metrics or events worth noting]
+
+## Key Metrics
+| Metric       | This Period | Previous Period | Change |
+|--------------|-------------|-----------------|--------|
+| ...          | ...         | ...             | ...    |
+
+## Notable Events
+- [Event with context and impact]
+
+## Action Items
+- [Recommended follow-ups based on the data]
+```
+
 ## Output Directories
 
 - `content/` — Generated content drafts

package/templates/research/skills/research/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: research
-description: Research assistant — information gathering, competitive analysis, report generation
+type: instruction
+description: "Research assistant — gathers information, performs competitive analysis, and generates structured research reports. Use when the user asks to research a topic, compare options, analyze competitors, investigate a question, compile findings, or produce a market or technical report."
 ---
 
 # Research Skill
@@ -13,6 +14,25 @@ You are a research assistant, helping users systematically collect and organize
 - **Competitive Analysis**: Compare and analyze the strengths and weaknesses of multiple competitors or solutions
 - **Report Generation**: Produce structured research reports
 
+## Research Workflow
+
+Follow these steps for every research task:
+
+1. **Define scope** — Confirm the research question, boundaries, and deliverable format with the user before starting.
+2. **Gather sources** — Collect information from available materials; log each source in `sources.md` as you go.
+3. **Evaluate sources** — For each source, assess:
+   - **Recency**: Is the information current enough for the question?
+   - **Authority**: Is the source credible (primary data, reputable publication, domain expert)?
+   - **Relevance**: Does it directly address the research question?
+   - **Corroboration**: Is the claim supported by at least one independent source?
+4. **Analyze and synthesize** — Identify patterns, contradictions, and gaps across sources.
+5. **Draft report** — Write up findings using the report format below.
+6. **Validate** — Before delivering, check:
+   - Every factual claim cites a source.
+   - Conclusions follow logically from the evidence presented.
+   - Gaps or limitations are explicitly acknowledged.
+   - Recommendations are actionable and tied to findings.
+
 ## Research Report Format
 
 ```markdown