manage-configs

Files (1)

• SKILL.md

SKILL.md (first lines)

# ArchAstro Local Config Management

Set up and manage a local `configs/` directory for editing agent configs as files, syncing with the server, and deploying changes.

This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill.

## What is Local Config Management?

Instead of creating and editing configs one-by-one through CLI CRUD commands, you can manage them as local files in a `configs/` directory. This enables:
- **Edit configs in your editor** with syntax highlighting and version control
- **Batch deploy** all changes in dependency order
- **Sync** server configs down to local files
- **Browser editor** for visual editing of individual configs

The CLI tracks the mapping between local files and server configs in a manifest file.

## Always Start with State

Every invocation must begin by understanding the current project state:

```
archastro auth status
ls configs/ 2>/dev/null || echo "No configs directory"
```

Determine:
- Does a `configs/` directory already exist?
- Is the user starting a new project or working with an existing one?
- Do they want to pull configs from the server or push local changes?

## Routing

### CLI not installed or too old

Before any config work, verify the CLI:

- Read `plugin-compatibility.json` from the plugin root.
- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`.
- If authentication or app selection is missing, direct the user to `/archastro:auth`.

### User wants to set up a configs directory for the first time

1. **Initialize the config directory**:
   ```
   archastro init --enable-configs
   ```
   This enables local config management and creates the configured `configs/` directory if needed. It does not automatically sync remote configs; use `archastro sync configs` next when you want local files.

2. **Explain the layout**: After init, the directory looks like:
   ```
   configs/
   ├── .archastro-manifest.json    # Maps local files to server configs (do not edit manually)
   ├── agents/                     # AgentTemplate configs
   ├── skills/                     # Skill bundles
   ├── scripts/                    # Script configs
   ├── workflows/                  # Workflow configs
   └── ...                         # Other config kinds
   ```

   Managed virtual paths also follow these prefixes on the server: `skills/`, `scripts/`, and `workflows/`.

3. **Offer next steps**: Ask if the user wants to create a new config (`archastro describe configsample <Kind>`) or sync existing configs from the server.

### App context and owner-pinned directories

Inspect the project config to discover configured directories instead of assuming `configs/`. For noninteractive setup, use `archastro init --app-id <app-id> --enable-configs --no-samples`; `--app-id current` keeps app selection portable.

Each directory has one owner. `--config-dir <path>` follows the signed-in identity; explicit `--config-dir configs/org=org=<org-id>` pins an organization. Supported owners are system, org, user, team, and agent. Use `archastro create configdir --help` to add another directory. Sync and deploy resolve scope per directory, preventing one owner's config set from being treated as another's.

### User wants to pull configs from the server

Sync server configs to local files:
```
archastro sync configs
```

This downloads configs visible to each configured directory's resolved owner — including skills, scripts, and workflows — and writes them as local files in the correct directories. The manifest tracks the file-to-config mapping.

Use `sync configs --dry-run` before reviewing incoming changes. Conflicts default to failure; select `--on-conflict overwrite|skip|fail` deliberately. `--prune-local` deletes tracked local files removed remotely.

After syncing, the directory structure reflects server state:
```
configs/
├── agents/                     # AgentTemplate configs (.yaml)
├── skills/my-skill/            # Skill bundles (SKILL.md + supporting files)
├── scripts/                    # Script configs (.aascript)
├── workflows/                  # Workflow configs (.json)
└── ...                         # Other config kinds
```

You can then edit any file locally and run `archastro deploy configs` to push changes back.

### User wants to create a new config locally

For **scripts**, **skills**, and **workflows**, prefer the dedicated commands or create files directly in the correct directory:

- **Script**: Write a `.agentscript` file in `configs/scripts/`:
  ```
  configs/scripts/my-script.agentscript
  ```
- **Skill**: Create a `SKILL.md` (with frontmatter) in `configs/skills/<slug>/`:
  ```
  configs/skills/my-skill/SKILL.md
  configs/skills/my-skill/prompts/greeting.liquid   # optional supporting files
  ```
- **Workflow**: Write a `.json` file in `configs/workflows/`:
  ```
  configs/workflows/my-workflow.json
  ```

For **other config kinds** (AgentTemplate, Persona, etc.), get a sample:
```
archastro list configkinds
archastro describe configsample <Kind> --to-file ./configs/<category>/<name>.yaml
```

You can also use the browser editor. Its path is relative to the configured config directory (or use an absolute path), not the project root:
```

From ArchAstro/archastro, MIT.

More from ArchAstro/archastro