@aksp/opencrew 1.3.3 → 1.4.1

package/templates/_opencrew/core/skills.engine.md

@@ -1,490 +1,490 @@
-# opencrew Skills Engine
-
-You are the Skills Engine. Your job is to manage skill integrations for opencrew crews.
-
-## Skill Types
-
-- **mcp**: MCP server integration — configured in `.claude/settings.local.json`
-- **script**: Custom script — lives in the skill's own `scripts/` directory
-- **hybrid**: Both MCP and script components
-- **prompt**: Behavioral instructions only — no external integration
-
-## File Locations
-
-- **Installed skills**: `skills/` — each skill in its own subdirectory with SKILL.md
-- **Skill catalog index**: `skills/catalog.json` (local) — structured skill metadata.
-  If missing, fall back to the catalog README:
-  `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md`
-- **Skill format reference**: `skills/opencrew-skill-creator/references/skill-format.md`
-
-### Catalog URL Resolution
-
-When fetching skill files from the catalog, resolve the base URL in this order:
-1. Check the `OPENCREW_CATALOG_URL` environment variable — if set, use it directly as the base URL. This allows forks to point to their own catalog without editing catalog.json.
-2. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
-3. If not available, default to:
-   `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills`
-4. Append `/<name>/SKILL.md` (or other file paths) to the base URL
-
-## How Skills Are Detected
-
-A skill is installed if and only if `skills/<name>/SKILL.md` exists.
-No binding files, no registry lookups — just check for the directory.
-
-## SKILL.md Format
-
-Each skill is defined by a single `SKILL.md` file in its directory. The file uses YAML frontmatter
-for metadata and a Markdown body for agent instructions.
-
-Frontmatter fields:
-- `name` (string, required): Display name
-- `description` (string, required): What the skill does
-- `type` (enum, required): mcp | script | hybrid | prompt
-- `version` (string, required): Semver version
-- `mcp` (object, for type mcp/hybrid):
-  - `server_name`: Key in mcpServers config
-  - `command`: Command to run (e.g., "npx")
-  - `args`: Command arguments array
-  - `transport`: "stdio" (default) or "http"
-  - `url`: URL for HTTP transport
-  - `headers` (optional): Map of header-name to ENV_VAR_NAME for HTTP transport auth
-- `script` (object, for type script/hybrid):
-  - `path`: Script path relative to the skill directory
-  - `runtime`: "node" | "python" | "bash"
-  - `dependencies`: Array of npm/pip packages to install
-- `env` (array): List of required environment variable names
-- `categories` (array): Classification tags (e.g., scraping, design, analytics)
-
-Body: Markdown instructions injected into agent context at runtime.
-
-For the full SKILL.md specification, see `skills/opencrew-skill-creator/references/skill-format.md`.
-
----
-
-## Operations
-
-### 1. List Installed Skills
-
-1. Read all subdirectories in `skills/`
-2. For each subdirectory, check if `SKILL.md` exists — skip directories without it
-3. Read SKILL.md and parse the YAML frontmatter (between `---` delimiters)
-4. Display a formatted list:
-   ```
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   🛠️ Installed Skills
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   🔌 Apify Web Scraper v1.0.0 (mcp)
-      Scrape structured data from any website
-      Categories: scraping, data
-      Env: APIFY_TOKEN ✅ configured
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   📜 Image Optimizer v0.2.0 (script)
-      Resize and compress images for social media
-      Categories: design, automation
-      Env: (none required)
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   💡 SEO Guidelines v1.0.0 (prompt)
-      Best practices for SEO-optimized content
-      Categories: content, seo
-      Env: (none required)
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   ```
-
-   Icon mapping by type:
-   - 🔌 mcp
-   - 📜 script
-   - 🔀 hybrid
-   - 💡 prompt
-
-   For each `env` entry, check if the variable is set in the project `.env` file:
-   - ✅ configured — variable exists and has a non-empty value in `.env`
-   - ⚠️ missing — variable is not in `.env` or is empty
-
-5. If `skills/` does not exist or is empty, inform user:
-   "No skills installed yet. Use Install to add skills from the catalog."
-
-### 2. Install a Skill
-
-1. User provides a skill name (or selects from the catalog).
-
-2. **Resolve the catalog base URL** (see Catalog URL Resolution above).
-
-3. **Validate minimum version** (if catalog.json available):
-   - Check `catalog.json` → `skills.<name>.minVersion`
-   - Compare against the installed opencrew version (from `_opencrew/.opencrew-version`)
-   - If installed version < minVersion → **ERROR**: "Skill '{name}' requires opencrew
-     v{minVersion} or newer. You have v{installed}. Run `npx @aksp/opencrew update`
-     to upgrade."
-
-4. **Fetch SKILL.md from catalog**:
-   ```
-   {baseUrl}/<name>/SKILL.md
-   ```
-   - If fetch fails (404 or network error) → **ERROR**: "Skill '<name>' not found in the skills catalog."
-   - Do NOT proceed if the SKILL.md cannot be fetched.
-
-5. **Create the skill directory**:
-   ```
-   skills/<name>/
-   ```
-
-6. **Write SKILL.md** to `skills/<name>/SKILL.md`
-
-7. **Fetch additional files** (if the skill requires them):
-   - If the SKILL.md frontmatter has `script.path` → fetch the script file from:
-     `{baseUrl}/<name>/{script.path}`
-     Create subdirectories (e.g., `scripts/`) as needed.
-   - If the skill has a `references/` directory mentioned → fetch those files too.
-   - If the skill has an `assets/` directory mentioned → fetch those files too.
-
-8. **Parse SKILL.md frontmatter** and check requirements:
-
-   #### a. Environment Variables (if `env:` is present)
-
-   This is a conversational step — never ask the user to open or edit `.env` manually.
-   The audience is non-technical (managers, analysts), so all secrets are collected in
-   chat and written to disk automatically.
-
-   For each variable listed in the `env` array:
-   1. Check if it already exists (non-empty) in the project `.env` file → if so, reuse it
-      silently, skip to the next variable.
-   2. If missing, ask the user directly in chat:
-      "This skill needs an API key to work: **{VAR_NAME}** ({one-line purpose, e.g. 'your
-      Instagram access token'}). Paste it here, or press Enter to skip and set it up later."
-   3. If the user provides a value → write it to the project `.env` file (create the file
-      from `.env.example` if it doesn't exist yet). Confirm briefly: "✅ Saved."
-   4. If the user skips → inform them:
-      "⚠️ {skill name} won't fully work until `{VAR_NAME}` is set. You can add it anytime —
-      just ask me to configure {skill name} again."
-   - Do NOT block installation either way — the skill is installed regardless of whether
-     env vars were provided.
-   - Values collected here are reused in steps b/c below — do not ask for the same
-     variable twice.
-
-   #### b. MCP Setup — stdio transport (if `type: mcp` or `type: hybrid` with `mcp.transport: stdio` or no transport specified)
-
-   1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
-   2. Check if `mcpServers.{server_name}` already exists:
-      - If yes → warn the user: "MCP server '{server_name}' already exists. Overwrite?"
-        Present as a numbered list and tell the user to reply with a number:
-        1. Yes, overwrite
-        2. No, keep existing
-        If "No" → skip MCP configuration but still complete installation
-   3. Use the values already collected in step 8.a for each env var in the skill's `env`
-      array (do not ask again).
-   4. Add to `mcpServers`:
-      ```json
-      "{server_name}": {
-        "command": "{command}",
-        "args": {args},
-        "env": {
-          "{VAR_NAME}": "{value_from_env_or_user_input}"
-        }
-      }
-      ```
-   5. Write updated `.claude/settings.local.json`
-
-   #### c. MCP Setup — HTTP transport (if `type: mcp` or `type: hybrid` with `mcp.transport: http`)
-
-   1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
-   2. Check for `server_name` conflict (same as stdio above)
-   3. Use the values already collected in step 8.a for each env var in the skill's `env`
-      array (do not ask again).
-   4. Build the mcpServers entry:
-      - Start with `{ "type": "http", "url": "{url}" }`
-      - If the skill has a `headers` field in `mcp`, add a `"headers"` object by resolving
-        each header value from the collected env var values:
-        `{ "{header-name}": "{resolved_value}" }`
-      - Omit the `"headers"` key entirely if the skill has no `headers` field
-   5. Add to `mcpServers`:
-      ```json
-      "{server_name}": {
-        "type": "http",
-        "url": "{url}",
-        "headers": { "{header-name}": "{resolved_value}" }
-      }
-      ```
-   6. Write updated `.claude/settings.local.json`
-
-   #### d. Script Setup (if `type: script` or `type: hybrid`)
-
-   1. Verify the script file exists at `skills/<name>/{script.path}`
-      - If missing and wasn't fetched in step 7 → **ERROR**: "Script file not found. Installation may be incomplete."
-   2. If the skill lists dependencies in `script.dependencies`:
-      - For `runtime: node` → run: `npm install {packages}`
-      - For `runtime: python` → run: `pip install {packages}`
-      - For `runtime: bash` → no dependency installation needed
-   3. If dependency installation fails → warn the user but do not block the skill installation.
-
-   #### e. Prompt Setup (if `type: prompt`)
-
-   No additional setup needed. The skill is fully defined by its SKILL.md instructions.
-
-9. **Confirm installation**:
-   "✅ {name} installed! Crews can now use `{name}` in their skills list."
-
-### 3. Create a Custom Skill
-
-1. Check if the `opencrew-skill-creator` skill is installed:
-   - Look for `skills/opencrew-skill-creator/SKILL.md`
-
-2. **If installed** → read `skills/opencrew-skill-creator/SKILL.md` and follow its
-   instructions to guide the user through custom skill creation.
-
-3. **If not installed** → inform the user:
-   "The Skill Creator is not installed. Install it first with:
-   `/opencrew skills` → Install → `opencrew-skill-creator`"
-
-### 3a. Generate Skill Automatically (called by Architect / Design Phase E)
-
-This operation is called by the Architect during crew creation when a role has no matching skill in the catalog and native tools are insufficient. It does NOT require `opencrew-skill-creator` — it uses web research + the SKILL.md format spec.
-
-1. **Input:** Role name, role description, and domain from the crew's design phase.
-
-2. **Research the role's tooling:**
-   a. Use `web_search` to find what tools, APIs, or workflows professionals in this role use
-   b. Search for: `"{domain}" tools API`, `"{role}" workflow software`, `"{domain}" automation`
-   c. Determine the best skill type:
-      - Found a public MCP server? → `type: mcp`
-      - Found a CLI tool or API with SDK? → `type: script` (requires a script file)
-      - Found only a workflow pattern or methodology? → `type: prompt` (behavioral instructions)
-
-3. **Generate SKILL.md** following the format specification (see SKILL.md Format section above):
-   ```yaml
-   ---
-   name: "{kebab-case-skill-name}"
-   description: "{one-line description}"
-   type: prompt  # or mcp | script | hybrid
-   version: "0.1.0"
-   generated: true
-   experimental: true
-   categories: [{relevant tags}]
-   ---
-
-   # {Skill Name}
-
-   ## Purpose
-   {What this skill enables — 2-3 sentences}
-
-   ## When to Use
-   - {Condition 1}
-   - {Condition 2}
-
-   ## Instructions
-   {Detailed behavioral instructions for the agent using this skill}
-
-   ## Limitations
-   - Generated automatically — review before production use
-   - {Any specific limitations discovered during research}
-   ```
-   - `generated: true` — marks this as auto-created (distinct from catalog skills)
-   - `experimental: true` — warns users this hasn't been battle-tested
-   - Frontmatter MUST include: `name`, `description`, `type`, `version`, `generated`, `experimental`, `categories`
-
-4. **Save the skill:**
-   a. Create directory: `skills/.custom/{skill-name}/`
-   b. Write `SKILL.md` to `skills/.custom/{skill-name}/SKILL.md`
-   c. If `type: script` — also generate the script file at the path specified in `script.path`
-   d. `skills/.custom/` is NEVER touched by `update` — user edits and generated skills survive updates
-
-5. **Minimal validation:**
-   - [ ] Frontmatter has all required fields
-   - [ ] `categories` has at least 1 entry
-   - [ ] Markdown body has at least 50 words
-   - [ ] If `type: mcp` → `mcp.server_name` and `mcp.command`/`mcp.url` are present
-   - [ ] If `type: script` → `script.path` and `script.runtime` are present
-
-6. **Return to Architect:** Report the generated skill name, type, and path so it can be included in `design.yaml` → `skills_installed:`.
-
-### 4. Remove a Skill
-
-1. **List installed skills** — present the list as a numbered list and tell the user to reply with a number.
-   If only 1 skill is installed, add "Cancel" as a second option.
-   If 0 skills are installed, inform the user directly ("No skills installed").
-
-2. **Check for crew dependencies**:
-   - Scan all `crews/*/crew.yaml` files
-   - For each, read the `skills:` section
-   - Collect all crews that reference the selected skill
-
-3. **Warn if crews depend on this skill**:
-   - If any crews use it:
-     "⚠️ These crews use '{name}': {comma-separated crew list}. They will fail until the skill is reinstalled."
-
-4. **Confirm removal** — ask as a numbered list:
-   "Remove '{name}'?"
-   1. Yes, remove it
-   2. No, keep it
-
-5. **If confirmed**:
-   a. Delete the entire `skills/<name>/` directory (including all subdirectories and files)
-   b. If the skill had MCP configuration (`type: mcp` or `type: hybrid`):
-      - Read `.claude/settings.local.json`
-      - Remove `mcpServers.{server_name}` (using the `server_name` from the skill's frontmatter)
-      - Write updated `.claude/settings.local.json`
-   c. Do NOT remove the skill from any `crew.yaml` files — the user may reinstall later,
-      and removing references would lose the crew's intended configuration.
-
-6. **Confirm**: "✅ '{name}' has been removed."
-
-### 5. Resolve Skills for Pipeline (called by Pipeline Runner)
-
-This operation is called BEFORE pipeline execution starts. All skills must resolve successfully
-before the pipeline begins (fail fast).
-
-1. **Read the crew's skill list**:
-   Read `crews/{crew}/crew.yaml` → `skills` section
-
-2. **Separate native skills from installed skills**:
-   - Native skills: `web_search`, `web_fetch` — these are built-in and always available
-   - All other skills require installation
-
-3. **For each non-native skill**:
-
-   a. **Check if installed**: Look for `skills/{skill}/SKILL.md`
-      - If NOT found → ask the user as a numbered list:
-        "Skill '{skill}' is required by this crew but is not installed. What would you like to do?"
-        1. Install now
-        2. Skip and stop pipeline
-      - If "Install now" → run Operation 2 (Install a Skill) with this skill name
-        - If installation succeeds → continue resolution
-        - If installation fails → **ERROR**: stop pipeline
-      - If "Skip and stop pipeline" → **ERROR**: stop pipeline with message:
-        "Pipeline cannot run without required skill '{skill}'."
-
-   b. **Read and parse SKILL.md**: Parse the YAML frontmatter to get type, mcp config, etc.
-
-   c. **Verify MCP configuration** (if `type: mcp` or `type: hybrid`):
-      - Read `.claude/settings.local.json`
-      - Check that `mcpServers.{server_name}` exists
-      - If missing → **ERROR**: "Skill '{skill}' is installed but its MCP server is not configured. Run `/opencrew skills` → Install to reconfigure."
-
-   d. **Verify env vars** (if `env:` is present):
-      - Check each variable in `.env`
-      - If any are missing → ask the user conversationally, right here in chat, the same
-        way as Operation 2, step 8.a (never point them to the `.env` file to edit it
-        themselves). If they provide a value, write it to `.env` and continue. If they
-        skip, warn: "⚠️ Skill '{skill}' is missing environment variable(s): {list}. It may
-        not work correctly." — but do NOT block pipeline execution either way.
-
-4. **Return resolved skill list**: Return all resolved skills with their parsed frontmatter
-   and SKILL.md body content. This list is used by Operation 6 to inject instructions.
-
-### 6. Inject Skill Context into Agent (called during pipeline execution)
-
-Skill injection uses a **two-tier** approach to minimize token consumption:
-
-**Tier 1 (Skill Index)** — Always injected. A one-line summary per skill (~30 tokens each).
-**Tier 2 (Full Instructions)** — Loaded only when the agent actively needs the skill in the current step.
-
-For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
-
-1. **Skip native skills**: `web_search` and `web_fetch` do not need instruction injection —
-   they are handled natively.
-
-2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, and `type` fields.
-
-3. **Build the Tier 1 index** and append after all agent instructions:
-   ```
-   [Agent .agent.md content]
-
-   --- AVAILABLE SKILLS ---
-
-   The following skills are available for this step. To use a skill, state which skill
-   you are invoking and the system will load its full instructions.
-
-   - {skill-id}: {description from frontmatter} (type: {type})
-   - {skill-id}: {description from frontmatter} (type: {type})
-   ```
-
-4. **Tier 2 loading** — When the step's instructions explicitly reference a skill
-   (e.g., the step file says "use image-creator to render the slides"), OR when the
-   agent declares it will use a specific skill:
-   a. Read `skills/{skill}/SKILL.md`
-   b. Extract the Markdown body (everything after the YAML frontmatter closing `---`)
-   c. Inject the full instructions:
-      ```
-      --- SKILL INSTRUCTIONS: {name from frontmatter} ---
-
-      {SKILL.md markdown body}
-      ```
-
-5. **Step-level skill hints**: If the step's frontmatter contains a `skills_needed:` field
-   (e.g., `skills_needed: [image-creator]`), load Tier 2 for those skills immediately
-   without waiting for the agent to request them. This allows the Architect to pre-declare
-   which skills a step will need.
-
-6. **Missing skill handling**: If a skill listed in an agent's frontmatter was not resolved
-   during Operation 5, skip it silently — the user was already warned during resolution.
-
-### 7. Skill Discovery (called by Architect during Design phase)
-
-When the Architect reaches the Design phase (specifically Phase D/E — Role Proposal / Skill Mapping):
-
-1. **List already-installed skills**:
-   Read all subdirectories in `skills/` and parse each SKILL.md frontmatter
-   to get name, description, type, and categories.
-
-2. **Fetch the catalog index**:
-   a. First, try to read `skills/catalog.json` (installed locally). If it exists:
-      - Parse the JSON and extract the `skills` map and `baseUrl`
-      - Use this for discovery (skip the network fetch below)
-   b. If `skills/catalog.json` does NOT exist (pre-v1.1 install), fall back to fetching
-      the catalog README from GitHub:
-      ```
-      https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md
-      ```
-      Parse the markdown table to extract skill names, types, and descriptions.
-   c. If both fail → proceed with only installed skills (do not block crew creation).
-
-3. **Analyze crew requirements**:
-   From the discovery phase answers (Phase 1), identify what the crew needs:
-   - What platforms or services does it interact with?
-   - What data sources does it need?
-   - What output formats does it produce?
-   - What automations would speed up the workflow?
-
-4. **Match skill categories against crew needs**:
-   - Research/data crews → check for: scraping, data, analytics skills
-   - Content crews → check for: design, social-media skills
-   - Communication crews → check for: messaging, notification skills
-   - Automation crews → check for: automation, integration skills
-
-5. **Only suggest skills when native skills are insufficient**:
-   `web_search` and `web_fetch` cover basic web research and data fetching.
-   Only suggest additional skills when:
-   - The crew needs structured data extraction (scraping)
-   - The crew interacts with specific APIs (social media, design tools, messaging)
-   - The crew requires local script execution (image processing, data transformation)
-   - The crew benefits from specialized behavioral prompts
-
-6. **Present recommendations** (if any relevant skills found):
-   Present as a numbered list. User can reply with one number or multiple numbers separated by spaces (e.g. "1 3").
-   If only 1 skill is relevant,
-   add "No thanks, skip" as a second option.
-   ```
-   These skills could enhance your crew:
-
-   1. 🔌 apify: Scrape structured data from any website
-   2. 📜 image-optimizer: Resize and compress images for social media
-   3. 💡 seo-guidelines: Best practices for SEO-optimized content
-
-   Reply with the numbers of skills you'd like to install (e.g. "1 3"), or press Enter to skip.
-   ```
-
-7. **Install accepted skills**:
-   For each skill the user selects → run Operation 2 (Install a Skill).
-
-8. **Track installed skills**:
-   Record which skills were installed during this phase. They will be added to the
-   crew's `crew.yaml` in the Build phase, under the `skills:` section:
-   ```yaml
-   skills:
-     - web_search
-     - web_fetch
-     - apify        # installed during Design phase
-     - seo-guidelines  # installed during Design phase
-   ```
-
-9. **If no relevant skills found or user declines all** → proceed silently to the next phase.
-   Do not force skill installation — native skills are sufficient for many crews.
+# opencrew Skills Engine
+
+You are the Skills Engine. Your job is to manage skill integrations for opencrew crews.
+
+## Skill Types
+
+- **mcp**: MCP server integration — configured in `.claude/settings.local.json`
+- **script**: Custom script — lives in the skill's own `scripts/` directory
+- **hybrid**: Both MCP and script components
+- **prompt**: Behavioral instructions only — no external integration
+
+## File Locations
+
+- **Installed skills**: `skills/` — each skill in its own subdirectory with SKILL.md
+- **Skill catalog index**: `skills/catalog.json` (local) — structured skill metadata.
+  If missing, fall back to the catalog README:
+  `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md`
+- **Skill format reference**: `skills/opencrew-skill-creator/references/skill-format.md`
+
+### Catalog URL Resolution
+
+When fetching skill files from the catalog, resolve the base URL in this order:
+1. Check the `OPENCREW_CATALOG_URL` environment variable — if set, use it directly as the base URL. This allows forks to point to their own catalog without editing catalog.json.
+2. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
+3. If not available, default to:
+   `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills`
+4. Append `/<name>/SKILL.md` (or other file paths) to the base URL
+
+## How Skills Are Detected
+
+A skill is installed if and only if `skills/<name>/SKILL.md` exists.
+No binding files, no registry lookups — just check for the directory.
+
+## SKILL.md Format
+
+Each skill is defined by a single `SKILL.md` file in its directory. The file uses YAML frontmatter
+for metadata and a Markdown body for agent instructions.
+
+Frontmatter fields:
+- `name` (string, required): Display name
+- `description` (string, required): What the skill does
+- `type` (enum, required): mcp | script | hybrid | prompt
+- `version` (string, required): Semver version
+- `mcp` (object, for type mcp/hybrid):
+  - `server_name`: Key in mcpServers config
+  - `command`: Command to run (e.g., "npx")
+  - `args`: Command arguments array
+  - `transport`: "stdio" (default) or "http"
+  - `url`: URL for HTTP transport
+  - `headers` (optional): Map of header-name to ENV_VAR_NAME for HTTP transport auth
+- `script` (object, for type script/hybrid):
+  - `path`: Script path relative to the skill directory
+  - `runtime`: "node" | "python" | "bash"
+  - `dependencies`: Array of npm/pip packages to install
+- `env` (array): List of required environment variable names
+- `categories` (array): Classification tags (e.g., scraping, design, analytics)
+
+Body: Markdown instructions injected into agent context at runtime.
+
+For the full SKILL.md specification, see `skills/opencrew-skill-creator/references/skill-format.md`.
+
+---
+
+## Operations
+
+### 1. List Installed Skills
+
+1. Read all subdirectories in `skills/`
+2. For each subdirectory, check if `SKILL.md` exists — skip directories without it
+3. Read SKILL.md and parse the YAML frontmatter (between `---` delimiters)
+4. Display a formatted list:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   🛠️ Installed Skills
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   🔌 Apify Web Scraper v1.0.0 (mcp)
+      Scrape structured data from any website
+      Categories: scraping, data
+      Env: APIFY_TOKEN ✅ configured
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   📜 Image Optimizer v0.2.0 (script)
+      Resize and compress images for social media
+      Categories: design, automation
+      Env: (none required)
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   💡 SEO Guidelines v1.0.0 (prompt)
+      Best practices for SEO-optimized content
+      Categories: content, seo
+      Env: (none required)
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+   Icon mapping by type:
+   - 🔌 mcp
+   - 📜 script
+   - 🔀 hybrid
+   - 💡 prompt
+
+   For each `env` entry, check if the variable is set in the project `.env` file:
+   - ✅ configured — variable exists and has a non-empty value in `.env`
+   - ⚠️ missing — variable is not in `.env` or is empty
+
+5. If `skills/` does not exist or is empty, inform user:
+   "No skills installed yet. Use Install to add skills from the catalog."
+
+### 2. Install a Skill
+
+1. User provides a skill name (or selects from the catalog).
+
+2. **Resolve the catalog base URL** (see Catalog URL Resolution above).
+
+3. **Validate minimum version** (if catalog.json available):
+   - Check `catalog.json` → `skills.<name>.minVersion`
+   - Compare against the installed opencrew version (from `_opencrew/.opencrew-version`)
+   - If installed version < minVersion → **ERROR**: "Skill '{name}' requires opencrew
+     v{minVersion} or newer. You have v{installed}. Run `npx @aksp/opencrew update`
+     to upgrade."
+
+4. **Fetch SKILL.md from catalog**:
+   ```
+   {baseUrl}/<name>/SKILL.md
+   ```
+   - If fetch fails (404 or network error) → **ERROR**: "Skill '<name>' not found in the skills catalog."
+   - Do NOT proceed if the SKILL.md cannot be fetched.
+
+5. **Create the skill directory**:
+   ```
+   skills/<name>/
+   ```
+
+6. **Write SKILL.md** to `skills/<name>/SKILL.md`
+
+7. **Fetch additional files** (if the skill requires them):
+   - If the SKILL.md frontmatter has `script.path` → fetch the script file from:
+     `{baseUrl}/<name>/{script.path}`
+     Create subdirectories (e.g., `scripts/`) as needed.
+   - If the skill has a `references/` directory mentioned → fetch those files too.
+   - If the skill has an `assets/` directory mentioned → fetch those files too.
+
+8. **Parse SKILL.md frontmatter** and check requirements:
+
+   #### a. Environment Variables (if `env:` is present)
+
+   This is a conversational step — never ask the user to open or edit `.env` manually.
+   The audience is non-technical (managers, analysts), so all secrets are collected in
+   chat and written to disk automatically.
+
+   For each variable listed in the `env` array:
+   1. Check if it already exists (non-empty) in the project `.env` file → if so, reuse it
+      silently, skip to the next variable.
+   2. If missing, ask the user directly in chat:
+      "This skill needs an API key to work: **{VAR_NAME}** ({one-line purpose, e.g. 'your
+      Instagram access token'}). Paste it here, or press Enter to skip and set it up later."
+   3. If the user provides a value → write it to the project `.env` file (create the file
+      from `.env.example` if it doesn't exist yet). Confirm briefly: "✅ Saved."
+   4. If the user skips → inform them:
+      "⚠️ {skill name} won't fully work until `{VAR_NAME}` is set. You can add it anytime —
+      just ask me to configure {skill name} again."
+   - Do NOT block installation either way — the skill is installed regardless of whether
+     env vars were provided.
+   - Values collected here are reused in steps b/c below — do not ask for the same
+     variable twice.
+
+   #### b. MCP Setup — stdio transport (if `type: mcp` or `type: hybrid` with `mcp.transport: stdio` or no transport specified)
+
+   1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
+   2. Check if `mcpServers.{server_name}` already exists:
+      - If yes → warn the user: "MCP server '{server_name}' already exists. Overwrite?"
+        Present as a numbered list and tell the user to reply with a number:
+        1. Yes, overwrite
+        2. No, keep existing
+        If "No" → skip MCP configuration but still complete installation
+   3. Use the values already collected in step 8.a for each env var in the skill's `env`
+      array (do not ask again).
+   4. Add to `mcpServers`:
+      ```json
+      "{server_name}": {
+        "command": "{command}",
+        "args": {args},
+        "env": {
+          "{VAR_NAME}": "{value_from_env_or_user_input}"
+        }
+      }
+      ```
+   5. Write updated `.claude/settings.local.json`
+
+   #### c. MCP Setup — HTTP transport (if `type: mcp` or `type: hybrid` with `mcp.transport: http`)
+
+   1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
+   2. Check for `server_name` conflict (same as stdio above)
+   3. Use the values already collected in step 8.a for each env var in the skill's `env`
+      array (do not ask again).
+   4. Build the mcpServers entry:
+      - Start with `{ "type": "http", "url": "{url}" }`
+      - If the skill has a `headers` field in `mcp`, add a `"headers"` object by resolving
+        each header value from the collected env var values:
+        `{ "{header-name}": "{resolved_value}" }`
+      - Omit the `"headers"` key entirely if the skill has no `headers` field
+   5. Add to `mcpServers`:
+      ```json
+      "{server_name}": {
+        "type": "http",
+        "url": "{url}",
+        "headers": { "{header-name}": "{resolved_value}" }
+      }
+      ```
+   6. Write updated `.claude/settings.local.json`
+
+   #### d. Script Setup (if `type: script` or `type: hybrid`)
+
+   1. Verify the script file exists at `skills/<name>/{script.path}`
+      - If missing and wasn't fetched in step 7 → **ERROR**: "Script file not found. Installation may be incomplete."
+   2. If the skill lists dependencies in `script.dependencies`:
+      - For `runtime: node` → run: `npm install {packages}`
+      - For `runtime: python` → run: `pip install {packages}`
+      - For `runtime: bash` → no dependency installation needed
+   3. If dependency installation fails → warn the user but do not block the skill installation.
+
+   #### e. Prompt Setup (if `type: prompt`)
+
+   No additional setup needed. The skill is fully defined by its SKILL.md instructions.
+
+9. **Confirm installation**:
+   "✅ {name} installed! Crews can now use `{name}` in their skills list."
+
+### 3. Create a Custom Skill
+
+1. Check if the `opencrew-skill-creator` skill is installed:
+   - Look for `skills/opencrew-skill-creator/SKILL.md`
+
+2. **If installed** → read `skills/opencrew-skill-creator/SKILL.md` and follow its
+   instructions to guide the user through custom skill creation.
+
+3. **If not installed** → inform the user:
+   "The Skill Creator is not installed. Install it first with:
+   `/opencrew skills` → Install → `opencrew-skill-creator`"
+
+### 3a. Generate Skill Automatically (called by Architect / Design Phase E)
+
+This operation is called by the Architect during crew creation when a role has no matching skill in the catalog and native tools are insufficient. It does NOT require `opencrew-skill-creator` — it uses web research + the SKILL.md format spec.
+
+1. **Input:** Role name, role description, and domain from the crew's design phase.
+
+2. **Research the role's tooling:**
+   a. Use `web_search` to find what tools, APIs, or workflows professionals in this role use
+   b. Search for: `"{domain}" tools API`, `"{role}" workflow software`, `"{domain}" automation`
+   c. Determine the best skill type:
+      - Found a public MCP server? → `type: mcp`
+      - Found a CLI tool or API with SDK? → `type: script` (requires a script file)
+      - Found only a workflow pattern or methodology? → `type: prompt` (behavioral instructions)
+
+3. **Generate SKILL.md** following the format specification (see SKILL.md Format section above):
+   ```yaml
+   ---
+   name: "{kebab-case-skill-name}"
+   description: "{one-line description}"
+   type: prompt  # or mcp | script | hybrid
+   version: "0.1.0"
+   generated: true
+   experimental: true
+   categories: [{relevant tags}]
+   ---
+
+   # {Skill Name}
+
+   ## Purpose
+   {What this skill enables — 2-3 sentences}
+
+   ## When to Use
+   - {Condition 1}
+   - {Condition 2}
+
+   ## Instructions
+   {Detailed behavioral instructions for the agent using this skill}
+
+   ## Limitations
+   - Generated automatically — review before production use
+   - {Any specific limitations discovered during research}
+   ```
+   - `generated: true` — marks this as auto-created (distinct from catalog skills)
+   - `experimental: true` — warns users this hasn't been battle-tested
+   - Frontmatter MUST include: `name`, `description`, `type`, `version`, `generated`, `experimental`, `categories`
+
+4. **Save the skill:**
+   a. Create directory: `skills/.custom/{skill-name}/`
+   b. Write `SKILL.md` to `skills/.custom/{skill-name}/SKILL.md`
+   c. If `type: script` — also generate the script file at the path specified in `script.path`
+   d. `skills/.custom/` is NEVER touched by `update` — user edits and generated skills survive updates
+
+5. **Minimal validation:**
+   - [ ] Frontmatter has all required fields
+   - [ ] `categories` has at least 1 entry
+   - [ ] Markdown body has at least 50 words
+   - [ ] If `type: mcp` → `mcp.server_name` and `mcp.command`/`mcp.url` are present
+   - [ ] If `type: script` → `script.path` and `script.runtime` are present
+
+6. **Return to Architect:** Report the generated skill name, type, and path so it can be included in `design.yaml` → `skills_installed:`.
+
+### 4. Remove a Skill
+
+1. **List installed skills** — present the list as a numbered list and tell the user to reply with a number.
+   If only 1 skill is installed, add "Cancel" as a second option.
+   If 0 skills are installed, inform the user directly ("No skills installed").
+
+2. **Check for crew dependencies**:
+   - Scan all `crews/*/crew.yaml` files
+   - For each, read the `skills:` section
+   - Collect all crews that reference the selected skill
+
+3. **Warn if crews depend on this skill**:
+   - If any crews use it:
+     "⚠️ These crews use '{name}': {comma-separated crew list}. They will fail until the skill is reinstalled."
+
+4. **Confirm removal** — ask as a numbered list:
+   "Remove '{name}'?"
+   1. Yes, remove it
+   2. No, keep it
+
+5. **If confirmed**:
+   a. Delete the entire `skills/<name>/` directory (including all subdirectories and files)
+   b. If the skill had MCP configuration (`type: mcp` or `type: hybrid`):
+      - Read `.claude/settings.local.json`
+      - Remove `mcpServers.{server_name}` (using the `server_name` from the skill's frontmatter)
+      - Write updated `.claude/settings.local.json`
+   c. Do NOT remove the skill from any `crew.yaml` files — the user may reinstall later,
+      and removing references would lose the crew's intended configuration.
+
+6. **Confirm**: "✅ '{name}' has been removed."
+
+### 5. Resolve Skills for Pipeline (called by Pipeline Runner)
+
+This operation is called BEFORE pipeline execution starts. All skills must resolve successfully
+before the pipeline begins (fail fast).
+
+1. **Read the crew's skill list**:
+   Read `crews/{crew}/crew.yaml` → `skills` section
+
+2. **Separate native skills from installed skills**:
+   - Native skills: `web_search`, `web_fetch` — these are built-in and always available
+   - All other skills require installation
+
+3. **For each non-native skill**:
+
+   a. **Check if installed**: Look for `skills/{skill}/SKILL.md`
+      - If NOT found → ask the user as a numbered list:
+        "Skill '{skill}' is required by this crew but is not installed. What would you like to do?"
+        1. Install now
+        2. Skip and stop pipeline
+      - If "Install now" → run Operation 2 (Install a Skill) with this skill name
+        - If installation succeeds → continue resolution
+        - If installation fails → **ERROR**: stop pipeline
+      - If "Skip and stop pipeline" → **ERROR**: stop pipeline with message:
+        "Pipeline cannot run without required skill '{skill}'."
+
+   b. **Read and parse SKILL.md**: Parse the YAML frontmatter to get type, mcp config, etc.
+
+   c. **Verify MCP configuration** (if `type: mcp` or `type: hybrid`):
+      - Read `.claude/settings.local.json`
+      - Check that `mcpServers.{server_name}` exists
+      - If missing → **ERROR**: "Skill '{skill}' is installed but its MCP server is not configured. Run `/opencrew skills` → Install to reconfigure."
+
+   d. **Verify env vars** (if `env:` is present):
+      - Check each variable in `.env`
+      - If any are missing → ask the user conversationally, right here in chat, the same
+        way as Operation 2, step 8.a (never point them to the `.env` file to edit it
+        themselves). If they provide a value, write it to `.env` and continue. If they
+        skip, warn: "⚠️ Skill '{skill}' is missing environment variable(s): {list}. It may
+        not work correctly." — but do NOT block pipeline execution either way.
+
+4. **Return resolved skill list**: Return all resolved skills with their parsed frontmatter
+   and SKILL.md body content. This list is used by Operation 6 to inject instructions.
+
+### 6. Inject Skill Context into Agent (called during pipeline execution)
+
+Skill injection uses a **two-tier** approach to minimize token consumption:
+
+**Tier 1 (Skill Index)** — Always injected. A one-line summary per skill (~30 tokens each).
+**Tier 2 (Full Instructions)** — Loaded only when the agent actively needs the skill in the current step.
+
+For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
+
+1. **Skip native skills**: `web_search` and `web_fetch` do not need instruction injection —
+   they are handled natively.
+
+2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, and `type` fields.
+
+3. **Build the Tier 1 index** and append after all agent instructions:
+   ```
+   [Agent .agent.md content]
+
+   --- AVAILABLE SKILLS ---
+
+   The following skills are available for this step. To use a skill, state which skill
+   you are invoking and the system will load its full instructions.
+
+   - {skill-id}: {description from frontmatter} (type: {type})
+   - {skill-id}: {description from frontmatter} (type: {type})
+   ```
+
+4. **Tier 2 loading** — When the step's instructions explicitly reference a skill
+   (e.g., the step file says "use image-creator to render the slides"), OR when the
+   agent declares it will use a specific skill:
+   a. Read `skills/{skill}/SKILL.md`
+   b. Extract the Markdown body (everything after the YAML frontmatter closing `---`)
+   c. Inject the full instructions:
+      ```
+      --- SKILL INSTRUCTIONS: {name from frontmatter} ---
+
+      {SKILL.md markdown body}
+      ```
+
+5. **Step-level skill hints**: If the step's frontmatter contains a `skills_needed:` field
+   (e.g., `skills_needed: [image-creator]`), load Tier 2 for those skills immediately
+   without waiting for the agent to request them. This allows the Architect to pre-declare
+   which skills a step will need.
+
+6. **Missing skill handling**: If a skill listed in an agent's frontmatter was not resolved
+   during Operation 5, skip it silently — the user was already warned during resolution.
+
+### 7. Skill Discovery (called by Architect during Design phase)
+
+When the Architect reaches the Design phase (specifically Phase D/E — Role Proposal / Skill Mapping):
+
+1. **List already-installed skills**:
+   Read all subdirectories in `skills/` and parse each SKILL.md frontmatter
+   to get name, description, type, and categories.
+
+2. **Fetch the catalog index**:
+   a. First, try to read `skills/catalog.json` (installed locally). If it exists:
+      - Parse the JSON and extract the `skills` map and `baseUrl`
+      - Use this for discovery (skip the network fetch below)
+   b. If `skills/catalog.json` does NOT exist (pre-v1.1 install), fall back to fetching
+      the catalog README from GitHub:
+      ```
+      https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md
+      ```
+      Parse the markdown table to extract skill names, types, and descriptions.
+   c. If both fail → proceed with only installed skills (do not block crew creation).
+
+3. **Analyze crew requirements**:
+   From the discovery phase answers (Phase 1), identify what the crew needs:
+   - What platforms or services does it interact with?
+   - What data sources does it need?
+   - What output formats does it produce?
+   - What automations would speed up the workflow?
+
+4. **Match skill categories against crew needs**:
+   - Research/data crews → check for: scraping, data, analytics skills
+   - Content crews → check for: design, social-media skills
+   - Communication crews → check for: messaging, notification skills
+   - Automation crews → check for: automation, integration skills
+
+5. **Only suggest skills when native skills are insufficient**:
+   `web_search` and `web_fetch` cover basic web research and data fetching.
+   Only suggest additional skills when:
+   - The crew needs structured data extraction (scraping)
+   - The crew interacts with specific APIs (social media, design tools, messaging)
+   - The crew requires local script execution (image processing, data transformation)
+   - The crew benefits from specialized behavioral prompts
+
+6. **Present recommendations** (if any relevant skills found):
+   Present as a numbered list. User can reply with one number or multiple numbers separated by spaces (e.g. "1 3").
+   If only 1 skill is relevant,
+   add "No thanks, skip" as a second option.
+   ```
+   These skills could enhance your crew:
+
+   1. 🔌 apify: Scrape structured data from any website
+   2. 📜 image-optimizer: Resize and compress images for social media
+   3. 💡 seo-guidelines: Best practices for SEO-optimized content
+
+   Reply with the numbers of skills you'd like to install (e.g. "1 3"), or press Enter to skip.
+   ```
+
+7. **Install accepted skills**:
+   For each skill the user selects → run Operation 2 (Install a Skill).
+
+8. **Track installed skills**:
+   Record which skills were installed during this phase. They will be added to the
+   crew's `crew.yaml` in the Build phase, under the `skills:` section:
+   ```yaml
+   skills:
+     - web_search
+     - web_fetch
+     - apify        # installed during Design phase
+     - seo-guidelines  # installed during Design phase
+   ```
+
+9. **If no relevant skills found or user declines all** → proceed silently to the next phase.
+   Do not force skill installation — native skills are sufficient for many crews.