component-management

Files (5)

• SKILL.md
• install.md · references/
• runtime-switch.md · references/
• uninstall.md · references/
• upgrade.md · references/

SKILL.md (first lines)

# Component Management

Guidelines for installing, upgrading, and managing zylos components.

## CLI

`zylos` is a **global npm command** (installed via `npm install -g zylos`).
Run it directly as `zylos`, NOT as `~/zylos/zylos` or `./zylos`.

## General Principles

1. **Always confirm before executing** - User must explicitly approve install/upgrade/uninstall
2. **Guide interactively** - Never just tell user to "manually edit files"
3. **Read SKILL.md** - Each component declares its requirements in SKILL.md frontmatter
4. **Detect execution mode** - Handle both Claude session and C4 channels differently
5. **CLI = mechanical, Claude = intelligent** - CLI handles downloads, backups, file sync. Claude handles config, hooks, service management, user interaction.

## Workflows

Detailed step-by-step workflows for each operation (Session + C4 modes):

- **[Install](references/install.md)** — Add new components
- **[Upgrade](references/upgrade.md)** — Upgrade components and zylos-core (self-upgrade)
- **[Uninstall](references/uninstall.md)** — Remove components with data options

## Quick Commands

```bash
# Check zylos-core version
zylos --version

# List installed components (with versions)
zylos list

# Search available components
zylos search <keyword>

# Component status
zylos status

# Check for zylos-core updates
zylos upgrade --self --check

# Check for beta/prerelease updates
zylos upgrade --self --check --beta

# Check all components for updates
zylos upgrade --all --check
```

## SKILL.md Config Format

Components declare their configuration requirements in SKILL.md frontmatter:

```yaml
---
name: my-component
version: 1.0.0
description: Component description

config:
  required:
    - name: ENV_VAR_NAME
      description: Human-readable description
      sensitive: true  # Optional: marks as secret
  optional:
    - name: OPTIONAL_VAR
      description: Optional setting
      default: "default-value"
---
```

When `sensitive: true`, the value should be handled carefully and not logged.

New components may declare a non-interactive configure hook:

```yaml
lifecycle:
  hooks:
    configure: hooks/configure.js
```

When present, collect `config.required` values and pipe them as stdin JSON to the hook. The component owns how those values are stored, usually in `~/zylos/components/<name>/config.json`. Components without `hooks.configure` are legacy-compatible and still receive collected values through `~/zylos/.env`.

---

## C4 Mode (IM Channels)

When user sends requests via C4 comm-bridge (Telegram, Lark, etc.), use streamlined flows with two-step confirmation. Replies must be plain text (no markdown).

### Detecting C4 Mode

The request is from C4 when the message arrives via a communication channel
(e.g., `<user> said: ...` with a `reply via:` instruction).

### C4 Reply Formatting

All `--json` outputs include structured data and a `reply` field (pre-formatted fallback).

**Preferred**: Use the JSON data fields to craft a clear, user-friendly plain text reply.
**Fallback**: If you're unsure how to format the reply, use the `reply` field directly.

### C4 Command Mapping

**CRITICAL: "add \<name\>" and "upgrade \<name\>" MUST ONLY run --check. NEVER execute install/upgrade without the word "confirm" in the user's message.**

**CRITICAL: confirm flow now always re-downloads (no temp-dir reuse):**
- `--check` is for preview/analysis only; any temporary download from check is cleaned up after the check completes.
- `upgrade <name> confirm` and `upgrade zylos confirm` always download a fresh package.
- Do not pass `--temp-dir`; it is no longer supported and the CLI will fail fast.

| User says | CLI command |
|-----------|------------|
| list / list components | `zylos list` |
| info \<name\> | `zylos info <name> --json` |
| check / check updates | `zylos upgrade --all --check --json` |
| check \<name\> | `zylos upgrade <name> --check --json` |
| upgrade \<name\> | `zylos upgrade <name> --check --json` **(CHECK ONLY)** |
| upgrade \<name\> confirm | `zylos upgrade <name> --yes --skip-eval --json` |

From zylos-ai/zylos-core, MIT.

More from zylos-ai/zylos-core