### List, Install, and Get Agent Metadata (JavaScript)

Source: https://context7.com/renatoasse/opensquad/llms.txt

Demonstrates how to interact with the agent API to list available agents, install new agents, and retrieve metadata for installed agents. Requires the 'agents.js' module.

```javascript
import {
  listInstalled,
  listAvailable,
  installAgent,
  removeAgent,
  getAgentMeta
} from './src/agents.js';

// Listar agentes disponíveis no catálogo
const available = await listAvailable();
console.log(available); // ['researcher', 'strategist', 'copywriter', 'reviewer']

// Instalar agente do catálogo
await installAgent('researcher', '/path/to/project');

// Obter metadados
const meta = await getAgentMeta('researcher');
console.log(meta);
// {
//   name: 'Researcher',
//   description: 'Pesquisa web e coleta informações...',
//   category: 'research',
//   icon: '🔍',
//   version: '1.0.0'
// }
```

--------------------------------

### Clone and Install OpenSquad

Source: https://github.com/renatoasse/opensquad/blob/master/CONTRIBUTING.md

Sets up the development environment for OpenSquad by cloning the repository, navigating into the directory, and installing dependencies.

```bash
git clone https://github.com/renatoasse/opensquad.git
cd opensquad
npm install
```

--------------------------------

### Install OpenSquad Agent Creator

Source: https://github.com/renatoasse/opensquad/blob/master/CONTRIBUTING.md

Installs the 'opensquad-agent-creator' package, used for creating new agents and guides, such as copywriting or SEO best practices.

```bash
/opensquad install opensquad-agent-creator
```

--------------------------------

### Install Node.js Script Dependencies

Source: https://github.com/renatoasse/opensquad/blob/master/_opensquad/core/skills.engine.md

Installs Node.js packages required by a skill's script using npm. This is part of the script setup process and warns the user if installation fails but does not block the overall skill installation.

```bash
npm install {packages}
```

--------------------------------

### Check ffmpeg Installation

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-24-sherlock-investigator-plan.md

Verifies if ffmpeg is installed by checking its version. If the command fails, it provides a link to download and install ffmpeg.

```bash
ffmpeg -version
```

--------------------------------

### List Installed Skills (CLI)

Source: https://context7.com/renatoasse/opensquad/llms.txt

Lists all skills installed in the current project. It displays the skill type (mcp, script, prompt), a brief description, and the status of its required environment variables.

```bash
npx opensquad skills
```

--------------------------------

### Install OpenSquad Skill Creator

Source: https://github.com/renatoasse/opensquad/blob/master/CONTRIBUTING.md

Installs the 'opensquad-skill-creator' package, which is used for creating and iterating on new skills within the OpenSquad project.

```bash
/opensquad install opensquad-skill-creator
```

--------------------------------

### Install Python Script Dependencies

Source: https://github.com/renatoasse/opensquad/blob/master/_opensquad/core/skills.engine.md

Installs Python packages required by a skill's script using pip. This is part of the script setup process and warns the user if installation fails but does not block the overall skill installation.

```bash
pip install {packages}
```

--------------------------------

### Check Whisper Installation

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-24-sherlock-investigator-plan.md

Verifies if Whisper is installed by checking its help command. If the command fails, it provides instructions to install Whisper using pip.

```bash
whisper --help
```

--------------------------------

### Check for Skill Creator Installation

Source: https://github.com/renatoasse/opensquad/blob/master/_opensquad/core/skills.engine.md

Checks if the 'opensquad-skill-creator' skill is installed by looking for its SKILL.md file. If not installed, it provides instructions on how to install it.

```bash
ls skills/opensquad-skill-creator/SKILL.md
```

```bash
echo "The Skill Creator is not installed. Install it first with:
/opensquad skills → Install → opensquad-skill-creator"
```

--------------------------------

### Check yt-dlp Installation

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-24-sherlock-investigator-plan.md

Verifies if yt-dlp is installed by checking its version. If the command fails, it provides instructions to install yt-dlp using pip.

```bash
yt-dlp --version
```

--------------------------------

### Implement Non-MCP Skill Auto-Installation in init.js

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-03-01-fix-init-distribution-plan.md

This function, `installNonMcpSkills`, is added to `src/init.js`. It iterates through available skills, filtering out MCP and hybrid types, as well as those with environment variables. Eligible skills are then automatically installed. The function also logs the creation of the `SKILL.md` file for each installed skill.

```javascript
async function installNonMcpSkills(targetDir) {
  const available = await listAvailable();
  for (const id of available) {
    if (id === 'opensquad-skill-creator') continue;
    const meta = await getSkillMeta(id);
    if (!meta) continue;
    // Skip MCP/hybrid skills — they need user configuration
    if (meta.type === 'mcp' || meta.type === 'hybrid') continue;
    // Skip skills with env vars — they need user setup
    if (meta.env?.length > 0) continue;
    await installSkill(id, targetDir);
    console.log(`  ${t('createdFile', { path: `_opensquad/skills/${id}/SKILL.md` })}`);
  }
}
```

--------------------------------

### YAML Output Example for Ranked Stories

Source: https://github.com/renatoasse/opensquad/blob/master/temp/squads/instagram-carrossel/agents/researcher/tasks/find-and-rank-news.md

Provides a concrete example of the YAML output format, demonstrating how ranked news stories are presented with specific details for a 'IA para empreendedores' research topic.

```yaml
research_topic: "IA para empreendedores"
time_range: "Últimas 24 horas"
search_date: "2026-03-03"
total_found: 11

stories:
  - rank: 1
    title: "OpenAI lança GPT-5 com capacidade de raciocínio 10x superior"
    source: "TechCrunch"
    url: "https://techcrunch.com/2026/03/03/openai-gpt5"
    date: "2026-03-03"
    summary: "OpenAI lançou o GPT-5 com benchmark de raciocínio matemático 10x acima do GPT-4. O modelo já está disponível via API e no ChatGPT Plus."
    viral_potential_score: 9
    why_interesting: "Lançamento de produto com dado concreto (10x) + relevante para quem usa IA no dia a dia"
    key_data: "10x superior em raciocínio matemático"

  - rank: 2
    title: "Pesquisa: 67% dos freelancers brasileiros usam IA mas cobram como se não usassem"
    source: "Exame"
    url: "https://exame.com/carreira/freelancers-ia-2026"
    date: "2026-03-02"
    summary: "Levantamento com 2.400 freelancers mostra que 67% já usam IA para produzir trabalho, mas apenas 12% ajustaram seus preços para cima."
    viral_potential_score: 8
    why_interesting: "Dado surpreendente (67%) + implicação prática direta para freelancers + dissonância cognitiva"
    key_data: "67% usam IA, só 12% aumentaram preços"
```

--------------------------------

### OpenSquad Main Menu and Help

Source: https://github.com/renatoasse/opensquad/blob/master/README.md

Access the main menu or get help information for all available OpenSquad commands.

```APIDOC
## GET /opensquad

### Description
Opens the main menu for OpenSquad, providing access to various functionalities.

### Method
GET

### Endpoint
/opensquad

## GET /opensquad help

### Description
Displays a comprehensive list of all available OpenSquad commands and their descriptions.

### Method
GET

### Endpoint
/opensquad help
```

--------------------------------

### Install and Manage Skills in OpenSquad (JavaScript)

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-skills-system-implementation.md

Provides functions to manage skills within the OpenSquad project. It includes listing installed skills, installing new skills from a remote registry, removing skills, and retrieving skill versions. The functions interact with the file system to manage skill files and use network requests to fetch skill information.

```javascript
import { mkdir, readdir, readFile, rm, writeFile, stat } from 'node:fs/promises';
import { join } from 'node:path';

const REGISTRY_BASE = 'https://raw.githubusercontent.com/opensquad-ai/opensquad/main';

export async function listInstalled(targetDir) {
  try {
    const skillsDir = join(targetDir, '_opensquad', 'skills');
    const entries = await readdir(skillsDir, { withFileTypes: true });
    return entries
      .filter((e) => e.isDirectory() && e.name !== 'opensquad-skill-creator')
      .map((e) => e.name);
  } catch (err) {
    if (err.code === 'ENOENT') return [];
    throw err;
  }
}

function validateSkillId(id) {
  if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
    throw new Error(`Invalid skill id: '${id}'`);
  }
}

export async function installSkill(id, targetDir, fetcher = fetch) {
  validateSkillId(id);
  const url = `${REGISTRY_BASE}/skills/${id}/SKILL.md`;
  const res = await fetcher(url);
  if (!res.ok) throw new Error(`Skill '${id}' not found in registry (${res.status})`);
  const content = await res.text();
  const destDir = join(targetDir, '_opensquad', 'skills', id);
  await mkdir(destDir, { recursive: true });
  await writeFile(join(destDir, 'SKILL.md'), content, 'utf-8');
}

export async function removeSkill(id, targetDir) {
  validateSkillId(id);
  const skillDir = join(targetDir, '_opensquad', 'skills', id);
  await rm(skillDir, { recursive: true, force: true });
}

export async function getSkillVersion(id, targetDir) {
  try {
    const skillMd = await readFile(
      join(targetDir, '_opensquad', 'skills', id, 'SKILL.md'), 'utf-8'
    );
    const match = skillMd.match(/^version:\s*"?([^"]+)"?/m);
    return match ? match[1].trim() : null;
  } catch {
    return null;
  }
}

```

--------------------------------

### Initialize and Update Opensquad

Source: https://github.com/renatoasse/opensquad/blob/master/README.md

Commands to initialize the Opensquad environment or update an existing installation. Requires Node.js 20+.

```bash
npx opensquad init
npx opensquad update
```

--------------------------------

### Rewrite Skills Installation Logic (Bash)

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-skills-system-implementation.md

This bash command stages and commits the rewritten JavaScript file for skills management and its corresponding test file.

```bash
git add src/skills.js tests/skills.test.js
git commit -m "feat: rewrite skills.js to install to _opensquad/skills/"
```

--------------------------------

### Initialize and Serve Dashboard

Source: https://context7.com/renatoasse/opensquad/llms.txt

Commands to generate and host the virtual office dashboard locally for monitoring agent progress.

```bash
# Passo 1: Gerar dashboard (na IDE)
/opensquad dashboard

# Passo 2: Servir localmente (no terminal)
cd squads/meu-squad
npx serve dashboard
```

--------------------------------

### Create Skill Directory and Write SKILL.md

Source: https://github.com/renatoasse/opensquad/blob/master/_opensquad/core/skills.engine.md

Creates the necessary directory structure for a new skill and writes the fetched SKILL.md file into it. This is a fundamental step in the skill installation process.

```bash
mkdir -p skills/<name>/
cp SKILL.md skills/<name>/SKILL.md
```

--------------------------------

### Fix update test for agent installation (Node.js)

Source: https://github.com/renatoasse/opensquad/blob/master/docs/superpowers/plans/2026-03-17-observability-ci-plan.md

Revises the update test in `tests/update.test.js` to verify that the update function succeeds without modifying the agents directory when no bundled agents exist. This corrects a test that previously expected agent installation, which is not applicable in the current setup.

```javascript
test('update succeeds when no bundled agents exist', async () => {
  const tempDir = await mkdtemp(join(tmpdir(), 'opensquad-test-'));
  try {
    await init(tempDir, { _skipPrompts: true });
    const result = await update(tempDir);
    assert.equal(result.success, true);
    // No bundled agents — agents/ dir should not exist
    await assert.rejects(
      stat(join(tempDir, 'agents')),
      { code: 'ENOENT' }
    );
  } finally {
    await rm(tempDir, { recursive: true, force: true });
  }
});
```

--------------------------------

### Initialize OpenSquad Project

Source: https://github.com/renatoasse/opensquad/blob/master/CONTRIBUTING.md

This command initializes a new OpenSquad project in a test folder, allowing users to experiment with the contribution workflow.

```bash
npx opensquad init
```

--------------------------------

### Creating an Example Skill Markdown File

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-skills-registry-implementation.md

Defines the basic structure for a new skill in Markdown format, including metadata like name and description.

```markdown
---
name: seo-optimizer
description: "SEO Optimizer — Analyze and optimize content for search engine visibility."
---
```

--------------------------------

### Create a New Squad with OpenSquad

Source: https://github.com/renatoasse/opensquad/blob/master/README.md

This command initiates the creation of a new squad. You provide a descriptive string outlining the squad's purpose. The Architect then designs and sets up the squad for your approval.

```bash
/opensquad create "A squad that writes LinkedIn posts about AI trends"
```

```bash
/opensquad create "Squad that generates Instagram carousels from trending news, creates the images, and publishes automatically"
```

```bash
/opensquad create "Squad that produces all infoproduct launch materials: sales pages, WhatsApp messages, emails, and CPL scripts"
```

```bash
/opensquad create "Squad that writes complete tutorials with screenshots for employee training"
```

```bash
/opensquad create "Squad that takes YouTube videos and automatically generates viral clips"
```

--------------------------------

### Create Version File for OpenSquad Templates

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-update-command-plan.md

This task involves creating a new file `templates/_opensquad/.opensquad-version` to track the project's template version. The file should contain a single line with the version number '0.1.0'. This is a prerequisite for the update command functionality.

```bash
echo "0.1.0" > templates/_opensquad/.opensquad-version
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/renatoasse/opensquad/blob/master/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification, used for maintaining a consistent commit history.

```git
feat: add tiktok-publisher skill
feat: add linkedin copywriting best-practice guide
fix: correct init copy for nested directories
docs: add Spanish translation for apify skill
```

--------------------------------

### Install @inquirer/checkbox dependency

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-ide-multiselect-onboarding.md

Installs the required npm package for handling multi-select checkbox prompts in the CLI. This is a prerequisite for adding the multi-select functionality.

```bash
npm install @inquirer/checkbox
```

--------------------------------

### Manage Agents (CLI)

Source: https://context7.com/renatoasse/opensquad/llms.txt

Manages pre-defined agents from the official catalog. This includes listing installed agents, installing new ones, removing existing agents, and updating all agents.

```bash
npx opensquad agents
```

```bash
npx opensquad agents install researcher
```

```bash
npx opensquad agents remove researcher
```

```bash
npx opensquad agents update
```

--------------------------------

### Create Antigravity .antigravity/rules.md Template

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-ide-multiselect-onboarding.md

Creates the necessary directory structure and copies the content from the opencode AGENTS.md template to create the .antigravity/rules.md file for the Antigravity IDE.

```bash
mkdir -p templates/ide-templates/antigravity/.antigravity
cp templates/ide-templates/opencode/AGENTS.md templates/ide-templates/antigravity/.antigravity/rules.md
```

--------------------------------

### Opensquad Skill API (JavaScript)

Source: https://context7.com/renatoasse/opensquad/llms.txt

Provides a JavaScript API for managing skills within an opensquad project. It allows listing installed and available skills, installing, removing, and retrieving metadata for skills.

```javascript
import {
  listInstalled,
  listAvailable,
  installSkill,
  removeSkill,
  getSkillMeta
} from './src/skills.js';

// Listar skills instaladas
const installed = await listInstalled('/path/to/project');
console.log(installed); // ['apify', 'image-generator', 'instagram-publisher']

// Obter metadados de uma skill
const meta = await getSkillMeta('image-generator');
console.log(meta);
// {
//   name: 'image-generator',
//   description: 'Gera imagens via API do Openrouter...',
//   type: 'script',
//   env: ['OPENROUTER_API_KEY'],
//   categories: ['assets', 'images', 'ai', 'generation']
// }

// Instalar skill do catálogo
await installSkill('canva', '/path/to/project');

// Remover skill
await removeSkill('canva', '/path/to/project');
```

--------------------------------

### Test Case for Agent Installation

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-03-01-fix-init-distribution-plan.md

A Node.js test case using the built-in test runner to verify that the update process correctly identifies and installs missing agent files while preserving the directory structure.

```javascript
test('update installs new bundled agents not already present', async () => {
  const tempDir = await mkdtemp(join(tmpdir(), 'opensquad-test-'));
  try {
    await init(tempDir, { _skipPrompts: true });
    const agentsDir = join(tempDir, 'agents');
    const entries = await readdir(agentsDir);
    const agentFiles = entries.filter((f) => f.endsWith('.agent.md'));
    assert.ok(agentFiles.length > 0, 'Should have agents after init');
    await rm(join(agentsDir, agentFiles[0]), { force: true });
    const countBefore = (await readdir(agentsDir)).filter((f) => f.endsWith('.agent.md')).length;
    await update(tempDir);
    const countAfter = (await readdir(agentsDir)).filter((f) => f.endsWith('.agent.md')).length;
    assert.ok(countAfter > countBefore, 'Update should install missing agents');
  } finally {
    await rm(tempDir, { recursive: true, force: true });
  }
});
```

--------------------------------

### Verify Tool Registry and Configuration

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-26-image-generation-tools-plan.md

Commands to list registered tools and verify that specific tags and principles are correctly defined in the YAML configuration files.

```bash
ls _opensquad/tools/registry/
grep -A1 "useful_for:" _opensquad/tools/registry/asset-fetcher.tool.yaml _opensquad/tools/registry/visual-renderer.tool.yaml
grep "Visual output" _opensquad/core/architect.agent.yaml
```

--------------------------------

### Markdown Section Addition: Loading the Skills Browser

Source: https://github.com/renatoasse/opensquad/blob/master/docs/plans/2026-02-27-skills-registry-implementation.md

Adds a new section to a Markdown document explaining the process of loading the Skills Browser, including fetching the manifest, detecting installed skills, and user interaction flows for installing or removing skills.

```markdown
## Loading the Skills Browser

When the user selects "Skills" from the menu or types `/opensquad skills`:

1. Use WebFetch to fetch `https://raw.githubusercontent.com/opensquad-ai/opensquad/main/skills/manifest.json`
   - If fetch fails, show: "Could not reach the skills registry. Check your connection."
2. Use Glob `.claude/skills/*/` to detect installed skills (exclude the `opensquad` folder itself)
3. Display available skills in two groups: **Installed** (✓) and **Available** (○)
4. Use AskUserQuestion to let the user choose an action:
   - **Install a skill** — choose from available skills
   - **Remove a skill** — choose from installed skills
   - **Back to menu** — return to main menu
5. To install: WebFetch `https://raw.githubusercontent.com/opensquad-ai/opensquad/main/skills/<id>/SKILL.md`, then Write to `.claude/skills/<id>/SKILL.md`
6. To remove: use Bash to `rm -rf .claude/skills/<id>/`
7. After any action, confirm and offer to browse again or return to menu

Note: Skills installed here take effect immediately — the user can type `/<skill-id>` right away.
```