swarm-report
Generate a cross-project comparative report from your organization's swarm. Use when you need an overview of all connected projects, want to compare activity levels, find shared patterns, or identify collaboration opportunities across teams. Also use when the user asks for a "swarm report", "cross-project analysis", "org overview", or wants to understand how projects relate to each other. Requires an active swarm connection.
Best use case
swarm-report is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Generate a cross-project comparative report from your organization's swarm. Use when you need an overview of all connected projects, want to compare activity levels, find shared patterns, or identify collaboration opportunities across teams. Also use when the user asks for a "swarm report", "cross-project analysis", "org overview", or wants to understand how projects relate to each other. Requires an active swarm connection.
Teams using swarm-report should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/swarm-report/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How swarm-report Compares
| Feature / Agent | swarm-report | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Generate a cross-project comparative report from your organization's swarm. Use when you need an overview of all connected projects, want to compare activity levels, find shared patterns, or identify collaboration opportunities across teams. Also use when the user asks for a "swarm report", "cross-project analysis", "org overview", or wants to understand how projects relate to each other. Requires an active swarm connection.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Swarm Report Generate a structured cross-project report from connected swarm nodes. The report compares projects, surfaces shared patterns, and recommends collaboration opportunities. ## Workflow ### 1. Verify Connectivity ``` swarm_status() ``` If disconnected, inform the user and stop. The swarm must be online to generate a meaningful report. ### 2. Inventory Nodes ``` swarm_nodes() ``` Record each team's project slug, connection status, and capabilities. This becomes the Node Inventory section of the report. ### 3. Gather Cross-Project Data Run multiple searches to build a picture of the organization: ``` # Activity and recent work swarm_search(query="recent changes and refactoring", search_type="all", limit=20) # Shared dependencies and libraries swarm_search(query="shared dependencies and common libraries", search_type="memory", limit=20) # Coding conventions and patterns swarm_search(query="coding conventions and architectural patterns", search_type="memory", limit=20) # Decisions and trade-offs swarm_search(query="architectural decisions and trade-offs", search_type="memory", limit=15) ``` Adapt queries based on what comes back — if a topic yields interesting results, drill deeper with `swarm_fetch`: ``` swarm_fetch(ids=["<chunk-id>"], project_slug="<project>") ``` ### 4. Write the Report Write the report to `oak/insights/cross-project-report.md` using this structure: ```markdown # Cross-Project Report > Generated: YYYY-MM-DD | Nodes: N connected ## Executive Summary 2-3 paragraph overview of the organization's current state — what's active, what themes emerge, and the top recommendations. ## Node Inventory | Project | Status | Capabilities | Notable Activity | |---------|--------|--------------|------------------| | ... | ... | ... | ... | ## Activity Comparison Compare what each project has been working on recently. Highlight: - Projects with high activity vs quiet ones - Overlapping work across teams - Blocked or stalled efforts ## Shared Patterns Patterns that appear across multiple projects: - Common dependencies (same libraries, frameworks, versions) - Similar architectural approaches (service layers, error handling) - Shared conventions (naming, testing, deployment) ## Divergences Where projects have made different choices: - Conflicting dependency versions - Different approaches to the same problem - Inconsistent conventions that could cause friction ## Recommendations Concrete, actionable suggestions: - Opportunities for code sharing or extraction into shared libraries - Projects that should coordinate on version alignment - Teams that would benefit from knowledge sharing on specific topics ``` ### CLI Fallback If MCP tools are unavailable: ```bash oak-dev swarm status oak-dev swarm nodes oak-dev swarm search "recent changes" --type all -n 20 oak-dev swarm search "shared dependencies" --type memory -n 20 oak-dev swarm search "coding conventions" --type memory -n 20 ``` ## Tips - **Quality depends on node count.** With only 1-2 nodes connected, the report will be thin. Let the user know if coverage is limited. - **Search broadly first.** The initial queries cast a wide net. Narrow down based on what comes back rather than starting too specific. - **Fetch selectively.** Only use `swarm_fetch` for results that look particularly relevant — fetching everything is slow and noisy. - **Be honest about gaps.** If a section has insufficient data, say so rather than speculating. A short honest report is more useful than a padded one. ## Deep Dives Consult these reference documents for deeper guidance: - **`references/report-examples.md`** — Good and bad report examples with detailed analysis of what makes a report useful vs useless. Read this before writing the report. - **`references/search-strategies.md`** — How to write effective swarm queries, when to use each search type, and how to correlate results across projects.
Related Skills
swarm
Search across multiple projects in your organization's swarm. Use when you need cross-project patterns, org-level conventions, shared decisions, or want to know how other projects solved a problem. Complements the oak (team) skill which covers single-project knowledge. Also use when the user mentions swarm_search, swarm_fetch, swarm_nodes, swarm_status, or asks about what other teams/projects have done, cross-project dependencies, org-wide patterns, or collective knowledge across the organization.
playwright-cli
Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
project-governance
Create and maintain project constitutions and agent instruction files. Use when establishing coding standards, adding project rules, creating agent guidance files, syncing rules across agents, or improving AI agent consistency. Also supports RFC/ADR documents for formalizing technical decisions that feed into the constitution.
pattern-finder
Find recurring code patterns, architectural decisions, and shared conventions across projects in your organization's swarm. Use when you want to discover what patterns other teams use, find candidates for shared libraries, or standardize approaches across the org. Also use when the user asks to "find patterns across projects", "what conventions do other teams follow", "shared code opportunities", or anything about org-wide code reuse. Requires an active swarm connection.
oak
Find out what happened, what was decided, and what depends on what in your codebase. Use this skill whenever you need to: recall past decisions or discussions ("what did we decide about X?"), check what might break before refactoring ("what depends on this module?"), find conceptually similar code that grep would miss ("all the retry/backoff logic"), look up past bugs, gotchas, or learnings, query session history or agent run costs, store observations about the codebase, or understand how components connect end-to-end. Powered by semantic search, memory lookup, and direct SQL against the Oak CI database (.oak/ci/activities.db). Also use when the user mentions oak_search, oak_context, oak_remember, oak_resolve_memory, or asks to run queries against activities.db or oak.
dependency-audit
Audit dependencies across projects in your organization's swarm. Use when you need to find version conflicts, outdated packages, or security risks across teams. Also use when the user asks for a "dependency audit", "version check across projects", "package alignment", or wants to standardize dependencies org-wide. Requires an active swarm connection.
context-engineering
Design effective prompts and optimize context for AI models and agents. Covers prompt engineering foundations (clarity, examples, chain of thought, XML structure), the four context engineering strategies (Write, Select, Compress, Isolate), agent memory and session patterns, and before/after examples showing measurable improvement. Use when writing system prompts, designing agent workflows, optimizing context windows, building prompt templates, structuring few-shot examples, reducing context rot, or improving AI output quality.
repo-generating-validation-reports
Guidelines for generating validation/audit reports with UUID chains, progressive writing, and UTC+7 timestamps
code-review-swarm
Deploy specialized AI agents to perform comprehensive, intelligent code reviews that go beyond traditional static analysis
tachi-threat-reporting
Domain knowledge for narrative threat report generation — executive summary structure, architecture overview patterns, per-category narrative templates, attack tree construction rules with Mermaid syntax, and reference attack tree examples. Consumed by the threat-report agent during report generation.
tachi-report-assembly
Domain knowledge for PDF security report assembly — artifact detection patterns with tier selection rules, Typst data variable contract with type specifications and image path resolution, and brand asset handling with logo location and fallback rules. Consumed by the report-assembler agent during report generation.
aso-weekly-report
Run Bloom's unattended weekly organic ASO report using Appfigures and DataForSEO. Use when the weekly ASO cron fires, or when asked for an ASO performance report, organic app store report, App Store keyword ranking update, keyword gaps report, or weekly app store growth summary. For interactive audits use aso-audit instead.