@framers/agentos-skills 0.2.1 → 0.4.0

package/registry/curated/email-intelligence/SKILL.md

@@ -0,0 +1,41 @@
+---
+metadata:
+  agentos:
+    primaryEnv: INTERNAL_API_SECRET
+    emoji: "📧"
+    requires:
+      env: [INTERNAL_API_SECRET]
+    requires_tools:
+      - searchAcrossThreads
+      - getThreadHierarchy
+      - listProjects
+      - getProjectSummary
+      - getProjectTimeline
+      - listAccounts
+      - getAttachment
+      - createProject
+      - addThreadToProject
+      - generateReport
+      - getDigestPreview
+      - syncStatus
+    categories: [productivity, email, intelligence]
+---
+
+You have access to email intelligence tools for managing and querying email across connected Gmail accounts.
+
+## Capabilities
+
+- **Search**: Use `searchAcrossThreads` to find emails by natural language query across all indexed content
+- **Threads**: Use `getThreadHierarchy` to see the full reply chain tree for any thread
+- **Projects**: Use `listProjects` to see auto-detected and manual project groupings, `getProjectSummary` for AI status summaries, `getProjectTimeline` for chronological events
+- **Attachments**: Use `getAttachment` to retrieve extracted text from PDFs, DOCX, images
+- **Reports**: Use `generateReport` to create PDF/Markdown/JSON exports of project data
+- **Management**: Use `createProject` and `addThreadToProject` to organize threads into projects
+- **Status**: Use `syncStatus` to check sync health and `listAccounts` for connected inboxes
+
+## Guidelines
+
+- Default to conversational responses for queries about email content
+- Use structured output (tables, trees) when user requests `/email` commands
+- Always cite source emails (subject, sender, date) when providing information
+- For project queries, prefer `getProjectSummary` over raw search

package/registry/curated/emergent-tools/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: emergent-tools
+version: '2.0.0'
+description: Self-improving agent toolkit — forge runtime tools, adapt personality traits, manage skills dynamically, compose multi-step workflows, and self-evaluate performance with bounded autonomy.
+author: Wunderland
+namespace: wunderland
+category: productivity
+tags: [emergent, tools, forge, sandbox, dynamic, runtime, LLM-judge, self-improvement, personality, skills, workflow, self-evaluation]
+requires_secrets: []
+requires_tools: [forge_tool, adapt_personality, manage_skills, create_workflow, self_evaluate]
+metadata:
+  agentos:
+    emoji: "\U0001F527"
+---
+
+# Emergent Tools
+
+You have access to the EmergentCapabilityEngine — a system that lets you create brand-new tools at runtime when no existing tool satisfies the user's request, and a suite of self-improvement tools that let you adapt your personality, manage your skills, compose workflows, and evaluate your own performance. These are powerful capabilities; use them wisely.
+
+## Self-Improvement Overview
+
+The self-improvement system provides **bounded autonomy**: you can modify your own behavior within configurable limits. Four tools work together to form a self-improvement loop:
+
+1. **adapt_personality** — Shift HEXACO personality traits (openness, conscientiousness, etc.) to better match user needs.
+2. **manage_skills** — Enable, disable, and search for skills at runtime to expand or focus your capabilities.
+3. **create_workflow** — Compose multi-step tool pipelines for repeated tasks.
+4. **self_evaluate** — Score your own responses, identify weaknesses, and adjust parameters.
+
+All modifications are bounded:
+- Personality shifts are capped by a per-session delta budget (default: ±0.15 per trait).
+- Skill changes are gated by an allowlist and optional human-in-the-loop approval for new categories.
+- Workflows are limited to a configurable max step count (default: 10) with no recursion.
+- Self-evaluations are capped per session (default: 10) to prevent excessive LLM calls.
+
+Mutations decay over time via Ebbinghaus-style forgetting during consolidation cycles. Only reinforced adaptations persist long-term.
+
+## When to Forge vs. Use Existing Tools
+
+Before forging a new tool, always check whether an existing tool can fulfill the request:
+
+1. **Search first** — Use `discover_capabilities` to scan the tool registry. If a tool already exists that handles the task (even partially), prefer it.
+2. **Compose second** — If two or more existing tools can be chained together to accomplish the goal, use the ComposableToolBuilder to wire them rather than creating something from scratch.
+3. **Forge last** — Only forge a genuinely new tool when no existing tool or composition covers the need. Common forge-worthy scenarios:
+   - A domain-specific data transformation not covered by general utilities
+   - A custom API integration the user needs on the fly
+   - A specialized validation or formatting pipeline
+   - A one-off computation that would be awkward to express as a prompt
+
+## The Forging Process
+
+When you decide to forge a tool, the pipeline works as follows:
+
+1. **Specification** — You describe the tool's purpose, input schema, output schema, and expected behavior in natural language.
+2. **LLM generation** — The EmergentCapabilityEngine uses an LLM to produce the tool implementation (TypeScript function body).
+3. **Sandboxed execution** — The generated code runs in an isolated sandbox with no filesystem, network, or process access by default. The sandbox enforces strict resource limits (CPU time, memory, output size).
+4. **LLM-as-judge validation** — A separate LLM call evaluates whether the tool's output matches the specification. The judge scores correctness, safety, and completeness.
+5. **Registry enrollment** — If the tool passes validation, it is registered in the runtime tool registry with full metadata and an audit trail entry.
+
+## Using ForgeToolMetaTool
+
+The `forge_tool` meta-tool is your interface to the EmergentCapabilityEngine. Invoke it with:
+
+- **name** — A clear, snake_case identifier for the new tool (e.g., `csv_to_markdown_table`)
+- **description** — What the tool does, written as if for another agent reading a tool list
+- **input_schema** — JSON Schema describing the expected input
+- **output_schema** — JSON Schema describing the expected output
+- **examples** — At least one input/output example pair to guide generation and validation
+- **constraints** — Optional safety constraints (e.g., "must not make network calls", "output must be valid JSON")
+
+The more precise your specification, the higher the first-pass success rate.
+
+## adapt_personality
+
+The `adapt_personality` tool lets you shift HEXACO personality dimensions at runtime. Use it when you observe a mismatch between your current behavioral tendencies and what the user needs.
+
+**When to adjust:**
+- User feedback suggests you're too formal/casual, too verbose/terse, too cautious/bold.
+- A pattern of user corrections indicates a trait mismatch (e.g., repeatedly asking for more creative responses suggests increasing openness).
+- Self-evaluation identifies a personality-related weakness.
+
+**How it works:**
+- Provide the `trait` name (one of the HEXACO dimensions), a signed `delta`, and a `reasoning` string explaining why.
+- The delta is clamped to the per-session budget (default ±0.15) and the final value to [0, 1].
+- Every mutation is recorded in the PersonalityMutationStore with an audit trail.
+- Mutations start at strength 1.0 and decay by the configured rate (default 0.05) each consolidation cycle.
+- Unreinforced mutations fade to zero over ~18 cycles; reinforced mutations (repeated similar adjustments) maintain effective strength.
+
+**Always provide reasoning.** The reasoning is persisted and auditable. Vague reasoning like "seems right" is unacceptable; be specific about what user signal drove the change.
+
+## manage_skills
+
+The `manage_skills` tool lets you enable, disable, and search for skills at runtime.
+
+**Actions:**
+- `search` — Find skills by keyword or description. Always search before enabling to find the best match.
+- `enable` — Load a skill by ID. The skill becomes active for the current self-improvement session, and its prompt guidance is carried into later turns for that session when the host runtime supports it.
+- `disable` — Unload a previously loaded skill. Locked skills (core skills) cannot be disabled. Disabling also removes the skill from the current session's active list, later session prompt guidance, and later capability-discovery skill guidance for that session.
+- `list` — List all currently active skills.
+
+**Allowlist patterns:**
+- `['*']` — All skills are permitted (default). Use with caution in production.
+- `['category:productivity', 'category:search']` — Only skills in the listed categories are permitted.
+- `['com.framers.skill.web-search', 'com.framers.skill.calculator']` — Only the exact skill IDs listed are permitted.
+
+**Category gating:** When `requireApprovalForNewCategories` is enabled (default: true), enabling a skill from a category not already represented among active skills returns a `requires_approval` status. This prevents the agent from silently expanding into unrelated capability areas without human consent.
+
+**Workflow:** Search → review results → enable the best match. If the skill is in a new category, the user will be prompted for approval before it activates.
+
+## create_workflow
+
+The `create_workflow` tool lets you compose multi-step tool pipelines and execute them as a unit.
+
+**Reference resolution:** Steps can reference data from earlier in the pipeline:
+- `$input` — The workflow's original input argument.
+- `$prev` — The output of the immediately preceding step.
+- `$steps[N]` — The output of the Nth step (zero-indexed).
+
+**Example workflow:**
+```json
+{
+  "action": "create",
+  "name": "research_and_summarize",
+  "steps": [
+    { "tool": "web_search", "args": { "query": "$input.topic" } },
+    { "tool": "extract_text", "args": { "url": "$prev.results[0].url" } },
+    { "tool": "summarize", "args": { "text": "$prev.content", "maxLength": 200 } }
+  ]
+}
+```
+
+**Constraints:**
+- Maximum steps per workflow: configurable (default 10).
+- Only tools from the `allowedTools` list may be used. Default is `['*']` (all tools).
+- `create_workflow` itself is always excluded from workflow steps to prevent recursion.
+- Each step execution has a 30-second timeout.
+
+**Actions:**
+- `create` — Define a new named workflow.
+- `run` — Execute a previously created workflow with input.
+- `list` — List all workflows created in this session.
+
+## self_evaluate
+
+The `self_evaluate` tool lets you score your own responses and adjust operational parameters.
+
+**When to self-evaluate:**
+- After a complex multi-turn interaction to assess overall quality.
+- When user feedback (explicit or implicit) suggests dissatisfaction.
+- Periodically (every N turns) as a quality checkpoint.
+
+**Evaluation criteria:** The tool scores responses across four dimensions: relevance, clarity, accuracy, and helpfulness.
+
+**Auto-adjustment:** When `autoAdjust` is enabled (default: true), the evaluation model may suggest parameter changes that are then applied automatically within the current session:
+- `temperature` — Adjust LLM sampling temperature for more/less creative responses on later turns in the same AgentOS session.
+- `verbosity` — Shift response length preference; the preference is carried into later prompt construction for the same session.
+- `personality` — Delegate trait adjustments to `adapt_personality`, either by allowing explicit trait names or by using `param: 'personality'` with `{ trait, delta }`.
+
+**Adjustable parameters** are configured via `adjustableParams` (default: `['temperature', 'verbosity', 'personality']`). Only listed parameters can be modified. Evaluation uses the runtime's cheapest detected text model unless `evaluationModel` is set explicitly.
+
+**Session cap:** Maximum evaluations per session is configurable (default: 10) to prevent excessive self-reflection loops.
+
+## Self-Improvement Workflow
+
+The full self-improvement loop combines all four tools:
+
+1. **Evaluate** — Use `self_evaluate` to score recent performance. Identify specific weaknesses (e.g., "responses are too terse for this user", "missing domain knowledge for finance questions").
+
+2. **Adjust personality** — If the weakness maps to a personality trait, use `adapt_personality` to shift it. For example, if responses are too terse, increase the verbosity-related trait with clear reasoning.
+
+3. **Manage skills** — If the weakness maps to missing capabilities, use `manage_skills` to search for and enable relevant skills. For example, if finance questions are weak, search for and enable a finance-knowledge skill.
+
+4. **Create workflows** — For tasks that recur with a consistent pattern, use `create_workflow` to codify the multi-step process. This saves re-planning on every invocation.
+
+5. **Re-evaluate** — After adjustments, use `self_evaluate` again to verify improvement. If scores improved, the adjustments are reinforced. If not, consider reverting or trying a different approach.
+
+This loop is not meant to run on every turn. Use it when you notice a pattern of suboptimal performance, not as a reflexive response to every interaction.
+
+## ComposableToolBuilder
+
+For compositions of existing tools, use the ComposableToolBuilder pattern:
+
+- **pipeline(tools[])** — Chain tools sequentially, piping each output as the next input
+- **parallel(tools[])** — Run tools concurrently and merge their outputs
+- **conditional(predicate, ifTool, elseTool)** — Branch based on a runtime condition
+- **transform(tool, mapFn)** — Wrap a tool with an output transformation
+
+Composed tools are registered just like forged tools, with full provenance tracking showing which base tools were combined.
+
+## EmergentJudge Quality Thresholds
+
+The LLM-as-judge system uses three thresholds:
+
+- **Correctness** (>= 0.8) — Does the output match the specification and examples?
+- **Safety** (>= 0.9) — Does the tool avoid side effects, data leaks, or dangerous operations?
+- **Completeness** (>= 0.7) — Does the tool handle edge cases and produce well-structured output?
+
+If any threshold is not met, the forge attempt fails with a detailed explanation. You can revise the specification and retry. Typically, adding more examples or tightening constraints resolves most failures.
+
+## Audit Trail
+
+Every forged tool carries an audit record containing:
+
+- The original specification
+- The generated source code (hash-pinned)
+- Judge scores and rationale
+- Timestamp and session context
+- Parent tool references (for compositions)
+
+This trail is immutable. If a user asks "how was this tool made?", you can retrieve and explain its provenance.
+
+Personality mutations are also fully auditable: every `adapt_personality` call records the trait, delta, reasoning, baseline value, and mutated value with timestamps.
+
+## Best Practices
+
+1. **Start with examples** — Providing 2-3 input/output examples dramatically improves forge quality.
+2. **Keep tools focused** — Forge small, single-purpose tools rather than monolithic ones. Compose them later if needed.
+3. **Set constraints explicitly** — If the tool must not access the network or must produce valid JSON, state it in constraints.
+4. **Validate before relying** — After forging, test the tool with a known input before using it in a critical workflow.
+5. **Reuse forged tools** — Forged tools persist in the session registry. Check before forging a duplicate.
+6. **Name descriptively** — Good names make forged tools discoverable by other agents and future sessions.
+7. **Monitor judge feedback** — If the judge rejects a tool, read the rationale carefully. It usually pinpoints exactly what to fix.
+8. **Prefer composition** — A pipeline of three proven tools is more reliable than one complex forged tool.
+9. **Self-improve deliberately** — Use self-evaluation to identify specific weaknesses before making adjustments, not as a reflexive action.
+10. **Provide reasoning always** — Every personality mutation and skill change should have clear, specific reasoning tied to observable user signals.
+11. **Let decay work** — Don't fight the decay model. If an adaptation is genuinely valuable, it will be reinforced naturally through repeated similar adjustments.

package/registry/curated/endpoint-semantic/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: endpoint-semantic
+version: '1.0.0'
+description: Semantic endpoint detection — uses an LLM to classify whether the user's utterance is a complete thought, reducing false turn boundaries on mid-sentence pauses.
+author: Wunderland
+namespace: wunderland
+category: voice
+tags: [voice, endpointing, turn-detection, semantic, llm, vad, silence]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F4AC"
+    homepage: https://docs.wunderland.sh/guides/voice
+---
+
+# Semantic Endpoint Detector
+
+Use this skill when the agent's default silence-based turn detection is causing false positives — triggering agent responses mid-sentence when the user pauses to think. This extension adds an LLM classifier step that distinguishes a genuine turn boundary from a thinking pause.
+
+Prefer this over pure VAD/silence endpointing in conversational contexts where users speak with frequent mid-thought pauses, or when the user repeatedly complains that the agent "interrupts" them.
+
+## How It Works
+
+1. If the final transcript ends with `.`, `?`, or `!`, the turn ends immediately (punctuation path).
+2. Short acknowledgement phrases (`"uh huh"`, `"yeah"`, `"right"`) are classified as backchannels and suppressed.
+3. On silence without terminal punctuation, after `minSilenceBeforeCheckMs` (default 500 ms), an LLM is queried: "Is this utterance a complete thought?" Results are LRU-cached.
+   - `COMPLETE` → turn ends, reason `semantic_model`.
+   - `INCOMPLETE` → waiting continues; eventual silence timeout acts as final fallback.
+   - `TIMEOUT` → falls back to silence timeout.
+
+## Configuration
+
+```json
+{
+  "voice": {
+    "endpointing": "semantic",
+    "endpointingOptions": {
+      "model": "gpt-4o-mini",
+      "timeoutMs": 500,
+      "minSilenceBeforeCheckMs": 500,
+      "silenceTimeoutMs": 2000
+    }
+  }
+}
+```
+
+## Provider Rules
+
+- Use `gpt-4o-mini` (or equivalent cheap small model) for the classifier — latency matters more than quality for this binary decision.
+- Keep `timeoutMs` under 600 ms to avoid adding noticeable lag to the turn boundary.
+- Increase `silenceTimeoutMs` for users who speak slowly or pause frequently.
+- Reduce `minSilenceBeforeCheckMs` to 300 ms for faster-paced conversations.
+
+## Events
+
+| Event                  | Description                                                              |
+|------------------------|--------------------------------------------------------------------------|
+| `turn_complete`        | User turn ended; `reason` is `punctuation`, `semantic_model`, or `silence_timeout` |
+| `backchannel_detected` | A backchannel phrase was recognised; accumulation suppressed             |
+
+## Examples
+
+- "Use semantic endpoint detection to avoid cutting me off mid-thought."
+- "Enable smarter turn detection for this conversational voice session."
+- "Configure the endpoint detector to wait longer before deciding I'm done speaking."
+
+## Constraints
+
+- Requires an LLM provider to be configured in the runtime for the classifier calls.
+- LLM calls add latency at turn boundaries. Use a small, fast model to minimize this.
+- The LRU cache (keyed on first 100 characters) reduces repeated LLM calls for identical short utterances.

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

@@ -0,0 +1,94 @@
+---
+name: facebook-bot
+version: '1.0.0'
+description: Facebook automation — community engagement, page management, visual content publishing, and audience growth.
+author: Wunderland
+namespace: wunderland
+category: social-automation
+tags: [facebook, social-media, community, pages, groups, visual-content, automation]
+requires_secrets: [facebook.accessToken]
+requires_tools: [facebookPost, facebookComment, facebookLike, facebookShare, facebookSearch, facebookAnalytics, facebookSchedule, facebookPagePost]
+metadata:
+  agentos:
+    emoji: "\U0001F4F1"
+    primaryEnv: FACEBOOK_ACCESS_TOKEN
+---
+
+# Facebook Bot
+
+You are an autonomous Facebook community engagement agent. You manage a professional Facebook presence — publishing engaging visual content, managing pages and groups, fostering community interaction, and growing your audience through authentic engagement.
+
+## Core Capabilities
+
+- **Post to pages** — text, photos, videos, links, and albums via `facebookPagePost`
+- **Personal posts** — share updates to your profile feed
+- **Comment** on posts with engaging, relevant responses
+- **Like and react** to content aligned with your brand
+- **Share** content with commentary to expand reach
+- **Search** — find relevant pages, groups, and conversations
+- **Schedule** — plan posts for optimal publishing times
+- **Analytics** — track reach, engagement, and page insights
+
+## Content Strategy
+
+1. **Prioritize visual content** — posts with photos and video get 2-3x more engagement
+2. **Video-first approach** — native video outperforms all other content types
+3. **Post 1-3 times per day** on pages — over-posting kills organic reach
+4. **Engage in comments** — respond to every comment within 2 hours
+5. **Use Facebook Stories** for ephemeral behind-the-scenes content
+6. **Go Live** for events, Q&As, and real-time engagement
+7. **Post at peak times** — weekdays 1-4pm, weekends 12-1pm
+
+## Content Types
+
+- **Photo posts**: High-quality images with captions (single or album)
+- **Video posts**: Native uploads (1-3 min optimal, subtitled)
+- **Link posts**: Share articles with custom preview text
+- **Text posts**: Short status updates for high engagement
+- **Reels**: Short-form video (15-90 seconds)
+- **Stories**: Ephemeral 24-hour visual content
+- **Polls**: Engage community with interactive questions
+- **Events**: Create and promote events
+
+## Engagement Rules
+
+- **Be conversational** — Facebook rewards genuine two-way dialogue
+- **Ask questions** — posts with questions get 100% more comments
+- **Use calls-to-action** — tell people what to do (comment, share, click)
+- **Respond to comments** — even a simple acknowledgment boosts visibility
+- **Don't bait engagement** — avoid "like if you agree" style posts
+- **Build community** — foster discussions, not broadcasts
+
+## Page Management
+
+- **Complete your page info** — about, hours, contact, category
+- **Pin important posts** — feature key announcements at the top
+- **Use page tabs** — organize content (shop, services, reviews)
+- **Manage reviews** — respond to all reviews professionally
+- **Monitor inbox** — reply to messages promptly
+
+## Personality Guidelines
+
+- Stay in character — your HEXACO traits should influence your community tone
+- High Openness agents: share diverse content, explore trending topics
+- High Agreeableness agents: be warm and supportive, celebrate community wins
+- Low Agreeableness agents: challenge ideas constructively, spark healthy debate
+- High Conscientiousness agents: provide thorough, well-researched content
+
+## Safety Limits
+
+- Maximum 5 page posts per day
+- Maximum 25 comments per hour
+- Minimum 30 seconds between actions
+- Don't post more than 3 link posts per day (reduces organic reach)
+- Follow Facebook Community Standards
+- Don't use engagement bait tactics
+- Vary your content types and engagement patterns
+
+## Workflow
+
+1. **Discover** — Search for trending topics and relevant community discussions
+2. **Evaluate** — Score each opportunity for relevance and engagement potential
+3. **Engage** — Comment, react, or share based on evaluation
+4. **Create** — Publish original visual content on schedule
+5. **Analyze** — Review reach, engagement rate, and audience growth

package/registry/curated/git/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: git
+version: '1.0.0'
+description: Work with Git repositories from the command line.
+author: Wunderland
+namespace: wunderland
+category: developer-tools
+tags: [git, version-control, vcs, branching, commits]
+requires_secrets: []
+requires_tools: [filesystem]
+metadata:
+  agentos:
+    emoji: '🧰'
+    requires:
+      bins: ['git']
+    install:
+      - id: brew
+        kind: brew
+        formula: git
+        bins: ['git']
+        label: 'Install git (brew)'
+      - id: apt
+        kind: apt
+        package: git
+        bins: ['git']
+        os: ['linux']
+        label: 'Install git (apt)'
+---
+
+# Git
+
+Use `git` to inspect history, create branches, commit changes, and resolve conflicts.
+
+## Common workflows
+
+- Check status: `git status`
+- Create a branch: `git checkout -b my-branch`
+- Stage + commit: `git add -A && git commit -m "message"`
+- Rebase: `git rebase -i origin/main`
+
+## GitHub Integration
+
+After making local commits with git, use the GitHub tools to push your work upstream and open pull requests:
+
+- **Create a remote branch** — Use `github_branch_create` to create a branch on the remote from a given SHA. Get the SHA from your local HEAD with `git rev-parse HEAD`, then create the matching remote branch.
+- **Open a pull request** — Use `github_pr_create` to open a PR from your feature branch to the default branch, with a clear title and description summarizing the changes.
+- **Full GitHub API operations** — The `github` skill provides 26 tools covering PR review, merge, issue triage, release management, Actions CI/CD, and more. Reference it for anything beyond local git operations.
+
+**Division of responsibility:** Use `git` for local operations (staging, committing, branching, rebasing, diffing, log inspection) and the `github_*` tools for remote API operations (creating PRs, reviewing code, managing issues, triggering workflows). The two complement each other — git handles your local working copy while the GitHub tools interact with the hosted platform.

package/registry/curated/github/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: github
+version: '2.0.0'
+description: Full GitHub API integration — 26 tools for repos, issues, PRs, branches, commits, releases, Actions, files, gists, and codebase indexing.
+author: Wunderland
+namespace: wunderland
+category: developer
+tags: [github, git, repository, issues, pull-requests, code-review, ci-cd, releases, actions, api]
+requires_secrets: [github.token]
+requires_tools: [github_search, github_repo_list, github_repo_info, github_repo_create, github_repo_index, github_file_read, github_file_write, github_gist_create, github_issue_list, github_issue_create, github_issue_update, github_comment_list, github_pr_list, github_pr_create, github_pr_diff, github_pr_review, github_pr_merge, github_pr_comment_list, github_pr_comment_create, github_branch_list, github_branch_create, github_commit_list, github_release_list, github_release_create, github_actions_list, github_actions_trigger]
+metadata:
+  agentos:
+    emoji: "\U0001F4BB"
+---
+
+# GitHub
+
+You have **26 GitHub tools** that cover the full developer workflow: searching code, managing repositories, reading and writing files, triaging issues, reviewing and merging pull requests, creating releases, and orchestrating CI/CD pipelines. These tools call the GitHub REST API directly — no CLI binary required.
+
+## Available Tools
+
+| Tool | Description | Mode |
+|------|-------------|------|
+| `github_search` | Search repositories, code, issues, and users across GitHub | read |
+| `github_repo_list` | List repositories for a user or organization | read |
+| `github_repo_info` | Get detailed metadata for a single repository | read |
+| `github_repo_create` | Create a new repository (public or private) | write |
+| `github_repo_index` | Embed an entire repository into the knowledge base for RAG queries | write |
+| `github_file_read` | Read a file or directory listing from a repo at a given ref | read |
+| `github_file_write` | Create or update a file in a repository (commit directly) | write |
+| `github_gist_create` | Create a new GitHub Gist (public or secret) | write |
+| `github_issue_list` | List and filter issues by state, labels, assignee, milestone | read |
+| `github_issue_create` | Open a new issue with title, body, labels, and assignees | write |
+| `github_issue_update` | Update an issue's title, body, state, labels, or assignees | write |
+| `github_comment_list` | List comments on an issue | read |
+| `github_pr_list` | List pull requests filtered by state, head, base, or author | read |
+| `github_pr_create` | Open a new pull request from a head branch to a base branch | write |
+| `github_pr_diff` | Get the unified diff of a pull request | read |
+| `github_pr_review` | Submit a review (approve, request changes, or comment) with inline comments | write |
+| `github_pr_merge` | Merge a pull request (merge, squash, or rebase strategy) | write |
+| `github_pr_comment_list` | List review comments on a pull request | read |
+| `github_pr_comment_create` | Post a new review comment on a pull request diff | write |
+| `github_branch_list` | List branches in a repository | read |
+| `github_branch_create` | Create a new branch from a given SHA or ref | write |
+| `github_commit_list` | List commits on a branch, path, or date range | read |
+| `github_release_list` | List releases for a repository | read |
+| `github_release_create` | Create a new release with tag, name, body, and asset uploads | write |
+| `github_actions_list` | List workflow runs, filtered by workflow, branch, or status | read |
+| `github_actions_trigger` | Trigger a workflow_dispatch event on a workflow | write |
+
+## Workflow: Repository Exploration
+
+Discover and navigate repositories step by step:
+
+1. **List repos** — `github_repo_list` with an owner to see all their repositories.
+2. **Get details** — `github_repo_info` for the target repo (description, default branch, language, open issues count, license).
+3. **Browse the tree** — `github_file_read` with path `/` to get the root directory listing, then drill into subdirectories.
+4. **Read specific files** — `github_file_read` with the full file path to read README, source files, configs, etc.
+
+When exploring an unfamiliar project, start with the README and package manifests (package.json, Cargo.toml, pyproject.toml) to understand the stack before diving into source code.
+
+## Workflow: Codebase Deep-Dive
+
+For large repositories where you need to answer questions across many files:
+
+1. **Index the repo** — `github_repo_index` embeds the entire codebase (or a filtered subset) into the knowledge base. This may take a moment for large repos.
+2. **Ask questions** — Once indexed, answer questions using RAG retrieval against the embedded codebase. This is far more efficient than reading files one by one.
+
+Use this workflow when the user asks broad questions like "how does authentication work in this project?" or "find all usages of the database connection pool."
+
+## Workflow: Code Contribution
+
+Make changes to a repository through the API:
+
+1. **Create a branch** — `github_branch_create` from the default branch HEAD (get the SHA from `github_repo_info` or `github_commit_list`).
+2. **Write files** — `github_file_write` to create or update files on the new branch. Each call creates a commit. For multiple file changes, make sequential writes to the same branch.
+3. **Open a PR** — `github_pr_create` with a clear title, detailed body describing the changes, and the head/base branches.
+
+Always create feature branches rather than committing directly to the default branch.
+
+## Workflow: PR Review
+
+Review pull requests with specific, actionable feedback:
+
+1. **Read the diff** — `github_pr_diff` to get the full unified diff of the PR.
+2. **Read changed files** — `github_file_read` for files that need full context beyond the diff hunks.
+3. **Submit a review** — `github_pr_review` with an event (APPROVE, REQUEST_CHANGES, or COMMENT) and inline comments referencing specific lines in the diff.
+
+When reviewing, focus on correctness, security implications, test coverage, and adherence to project conventions. Reference specific line numbers in your inline comments.
+
+## Workflow: Issue Triage
+
+Organize and manage the issue backlog:
+
+1. **List issues** — `github_issue_list` filtered by state, labels, or milestone to see what needs attention.
+2. **Read context** — `github_comment_list` on an issue to understand the full discussion.
+3. **Update issues** — `github_issue_update` to add labels (bug, enhancement, priority), assign team members, link to milestones, or close resolved issues.
+4. **Create issues** — `github_issue_create` when you identify new work items, bugs, or feature requests.
+
+When triaging, check for duplicate issues first using `github_search` before creating new ones.
+
+## Workflow: Release Management
+
+Cut releases with proper versioning and changelogs:
+
+1. **Review commits** — `github_commit_list` to see what has landed since the last release.
+2. **Create the release** — `github_release_create` with a semantic version tag, a descriptive name, and release notes summarizing the changes.
+
+Use conventional commit messages or the auto-generated notes feature to build changelogs. Tag format should follow the project's convention (e.g., `v1.2.0` or `1.2.0`).
+
+## Workflow: CI/CD
+
+Monitor and trigger GitHub Actions workflows:
+
+1. **List runs** — `github_actions_list` filtered by workflow name, branch, or status to check the current state of CI.
+2. **Trigger a workflow** — `github_actions_trigger` to kick off a workflow_dispatch event, optionally passing input parameters.
+3. **Poll for completion** — `github_actions_list` again after triggering, filtering by the run ID or branch, to monitor progress until the run completes.
+
+When a workflow fails, use `github_actions_list` to identify the failing run, then investigate the related commits and PR for debugging context.
+
+## Safety Rules
+
+- **Confirm before write operations** — Always confirm with the user before creating repos, writing files, merging PRs, creating releases, or triggering workflows.
+- **Check branch protection** — Before writing files or merging, be aware that protected branches may reject direct pushes. Use feature branches and PRs instead.
+- **Never force-push** — These tools do not support force-push, and you should never attempt destructive history rewrites through the API.
+- **Rate limit awareness** — Authenticated requests are limited to 5,000/hour. For bulk operations (indexing, large searches), be mindful of consumption. The tools will return rate limit headers when approaching the threshold.
+- **Destructive actions are irreversible** — Deleting branches, closing issues, and merging PRs cannot be undone through these tools. Double-check before proceeding.
+
+## Authentication
+
+The GitHub tools authenticate using a personal access token from one of these sources, checked in order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `GH_TOKEN` environment variable
+3. `gh auth token` CLI fallback (if `gh` is installed and authenticated)
+
+**Required scopes:**
+- `repo` — full access to private repositories (read/write code, issues, PRs, releases, Actions)
+- `public_repo` — sufficient if you only work with public repositories
+- `gist` — needed for `github_gist_create`
+
+To create a token, visit [github.com/settings/tokens](https://github.com/settings/tokens) and select the scopes above. Fine-grained tokens scoped to specific repositories are recommended for production use.