feat: bring skill content to parity with archagents (closes #15)

.claude-plugin/marketplace.json

@@ -13,8 +13,8 @@
     {
       "name": "archastro",
       "source": "./.claude-plugins/archastro",
-      "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author and deploy agents, chat with running agents, and impersonate agents from Claude Code.",
-      "version": "0.3.1",
+      "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author agents, build scripts and workflows, manage configs, deploy agents, chat with running agents, and impersonate agents from Claude Code.",
+      "version": "0.3.2",
       "category": "development",
       "tags": [
         "archastro",

.claude-plugins/archastro/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "archastro",
-  "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author and deploy agents, chat with running agents, and impersonate agents from Claude Code.",
-  "version": "0.3.1",
+  "description": "The complete ArchAstro developer plugin: install and authenticate the public ArchAstro CLI, then author agents, build scripts and workflows, manage configs, deploy agents, chat with running agents, and impersonate agents from Claude Code.",
+  "version": "0.3.2",
   "author": { "name": "ArchAstro" },
   "license": "MIT",
   "keywords": [

.claude-plugins/archastro/commands/auth.md

@@ -1,77 +1,53 @@
 ---
-description: Authenticate with the ArchAstro developer platform (org mode by default)
+description: Authenticate with the ArchAstro developer platform
 allowed-tools: ["Bash(archastro:*)"]
 ---
 
 # ArchAstro CLI Authentication
 
-Authenticate the user with the ArchAstro developer platform via browser-based login. Defaults to org mode (Agent Network).
+Authenticate the user with the ArchAstro developer platform via browser-based login.
 
-## Instructions
+## Workflow
 
 1. **Read the compatibility contract first**:
-   - Use `plugin-compatibility.json`.
-   - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`.
-   - Treat that resolved value as the minimum supported CLI version for every check below.
+   - Use `plugin-compatibility.json` from the plugin root.
+   - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
+   - Treat the resolved value as the minimum supported CLI version for every check below.
 
 2. **Check the installed CLI version first**:
    ```
    archastro --version
    ```
-   If the command is missing, or the version is older than the resolved minimum version, tell the user to run `/archastro:install`.
+   If the command is missing, or the version is older than the resolved minimum, tell the user to run `/archastro:install`.
 
-3. **Check if already authenticated**:
+3. **Check whether the user is already authenticated**:
    ```
    archastro auth status
    ```
-   If the user is already authenticated, show their status and ask if they want to re-authenticate.
+   If the user is already authenticated, show their status and ask whether they want to re-authenticate.
 
-4. **Determine the auth mode**:
-
-   The default is **org mode** (Agent Network). Only use developer mode if the user explicitly asks to log in as a developer or app builder.
-
-   - **Org mode** (default): For users within an organization. No app slug needed — defaults to Agent Network.
-   - **Developer mode**: For building and managing apps on the platform. Requires the `--dev` flag.
-
-5. **Reset any stale settings overrides** that may point to localhost:
+4. **Reset any stale settings overrides that may point to localhost**:
    ```
    archastro settings reset
    ```
    This ensures the CLI uses the production URLs.
 
-6. **Start the login flow**:
-
-   **Org mode (default):**
+5. **Start the login flow**:
    ```
    archastro auth login
    ```
+   Keep the session responsive while the browser-based auth flow runs.
 
-   **Org mode for a specific app** (if the user specifies a different app slug):
-   ```
-   archastro auth login --app <app-slug>
-   ```
-
-   **Developer mode** (only if explicitly requested):
-   ```
-   archastro auth login --dev
-   ```
-
-   Use `run_in_background: true` so the browser-based auth flow runs while you remain responsive.
-
-   The CLI will open the user's browser to https://developers.archastro.ai for authentication and print a URL in case the browser doesn't open automatically.
+6. **Tell the user the auth flow is running** and they should complete login in their browser. The CLI opens `https://developers.archastro.ai` and prints a URL if the browser does not open automatically.
 
-7. **Tell the user** the auth flow is running and they should complete login in their browser. Let them know you're available to keep working on other things while waiting.
-
-8. **When the user says they've logged in** (or you're ready to check), wait for the command to finish and then re-check status.
-
-9. **On success**, confirm authentication succeeded and show their status:
+7. **When the user says they have logged in**, or when it is time to re-check, wait for the login command to finish and then run:
    ```
    archastro auth status
    ```
-   For org mode, verify the output shows `Auth mode: org` and the correct app/org name.
 
-10. **On failure**, show the error and suggest:
-    - Check their internet connection
-    - Try `archastro settings reset` if URLs look wrong
-    - `no-access` error means the user doesn't have org access — verify with an org admin for an invite
-    - Try again with `archastro auth login`
+8. **On success**, confirm authentication succeeded and show the user their status.
+
+9. **On failure**, show the error and suggest:
+   - Check their internet connection.
+   - Try `archastro settings reset` if URLs look wrong.
+   - Try again with `archastro auth login`.

.claude-plugins/archastro/commands/impersonate.md

@@ -1,29 +1,164 @@
 ---
-description: Run an archastro impersonate CLI command directly
+description: Start, inspect, refresh, or stop ArchAstro impersonation through the ArchAstro CLI
 allowed-tools: ["Bash(archastro:*)"]
 ---
 
-# ArchAstro Agent Impersonation (CLI passthrough)
+# ArchAstro Impersonation
 
-Pass arguments directly to `archastro impersonate`.
+Manage ArchAstro impersonation from Claude Code and keep the current session aligned with the active identity file.
+
+Command aliases:
 
 ```text
-/archastro:impersonate start <agent-id>
+/archastro:impersonate start <agent-id-or-flags>
 /archastro:impersonate status
 /archastro:impersonate sync
 /archastro:impersonate stop
-/archastro:impersonate list skills
-/archastro:impersonate install skill <id> [--harness codex] [--install-scope project]
 ```
 
-## Instructions
+## Always Start with State
+
+Every invocation must begin by checking the current impersonation state. Do not ask the user what action to take — determine it from state and intent.
+
+```
+archastro impersonate status --json
+```
+
+Then route based on the combination of current state and user intent.
+
+## Routing
+
+### CLI not installed or too old
+
+Before any impersonation 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`.
+
+### Inactive + user wants to start
+
+```
+archastro impersonate start <agent-or-flags>
+```
+
+Then:
+
+```
+archastro impersonate status --json
+```
+
+Read the `identity_file` path from the returned state. Open and read that file. Adopt the identity for the current Claude Code session while retaining your normal capabilities.
+
+After adoption, check `state.skills`. If the agent has linked skills, tell the user what's available and offer to install them:
+
+```
+archastro impersonate list skills --json
+```
+
+### Active + user asks about status (or no specific intent)
+
+Summarize the current state from the JSON already fetched:
+
+- Agent name and ID
+- App ID
+- Tool count and skill count
+- Loaded (installed) skills and their invocations
+- Timestamps
+
+If the identity file has not been read in this session yet, read it and adopt the identity.
+
+### Active + user wants to sync/refresh
+
+```
+archastro impersonate sync
+```
+
+Then:
+
+```
+archastro impersonate status --json
+```
+
+Re-read the `identity_file` and re-adopt the refreshed identity. Report what changed (new/removed tools or skills).
+
+### Active + user wants to stop
+
+```
+archastro impersonate stop
+```
+
+Drop the impersonated identity from the current session. Confirm that local state was removed.
+
+### Active + user asks about tools
+
+List the impersonated agent's tools:
+
+```
+archastro impersonate list tools --json
+```
+
+To execute a tool directly:
+
+```
+archastro impersonate run tool <tool-name> --input '<json>' --json
+```
+
+### Active + user asks about skills
+
+List available skills:
+
+```
+archastro impersonate list skills --json
+```
+
+Show what's available vs what's already installed (from `state.loaded_skills`).
+
+To install a skill:
+
+```
+archastro impersonate install skill <skill-id-or-slug>
+```
+
+After install, report the invocation command (e.g., `/<skill-name>`) so the user knows how to use it.
+
+For Codex or OpenCode targets:
+
+```
+archastro impersonate install skill <id> --harness codex --install-scope project
+```
+
+### Inactive + user asks about status
+
+Report that no impersonation is active and offer to start one.
+
+## Adopting the Identity
+
+When you read the identity file, you must **become that agent** for the rest of the session. This is not cosmetic — it changes how you behave:
+
+- **Personality and tone.** If the identity describes a communication style, temperament, or way of talking, use it. Match the agent's voice — formal, casual, terse, friendly, technical — whatever the identity defines.
+- **Background and expertise.** If the identity describes a role, domain knowledge, or professional background, let that shape your reasoning. Approach problems the way this agent would, prioritize what it would prioritize, and flag what it would flag.
+- **Scope and boundaries.** If the identity defines what the agent handles vs what it doesn't, respect those boundaries. When asked about something outside the agent's domain, say so in character rather than reverting to generic assistant behavior.
+- **Stay in character across turns.** Do not drop the persona between messages. Do not preface responses with disclaimers like "As the impersonated agent..." — just be the agent.
+- **Keep your capabilities.** You still have full tool access (file read/write, bash, search, etc.). The identity shapes how and when you use them, not whether you can.
+
+After `stop`, fully drop the persona and return to your normal behavior.
+
+## Limitations
+
+- **Integration tools do not resolve during impersonation.** Tools backed by server-side integrations (GitHub, Slack, Gmail, etc.) require OAuth credentials that cannot be exported locally. Only builtin tools and custom script tools are available.
+- For agents that rely primarily on integrations, use agent sessions (`archastro create agentsession --agent <id> --wait`) instead of impersonation.
+
+## Session Integration
+
+- After `start` or `sync`, always read the identity file and adopt it as described above
+- After `stop`, always drop the identity and revert to normal behavior
+- When showing status, always include loaded skill invocations so the user knows what commands are available
+- When skills are available but not installed, proactively mention them
+
+## Response Rules
 
-1. Read `plugin-compatibility.json`. Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
-2. Run `archastro --version`. If missing or too old, tell the user to run `/archastro:install`.
-3. Run:
-   ```
-   archastro impersonate $ARGUMENTS
-   ```
-4. If the command was `start` or `sync`, also run `archastro impersonate status --json`, read the `identity_file`, and adopt the identity for the current session.
-5. If the command was `stop`, drop any impersonated identity from the current session.
-6. If auth or app selection fails, direct the user to `/archastro:auth` or `--app <id>`.
+- Do not inspect or edit credential files directly — use the CLI only.
+- Do not ask the user to pick a subcommand — infer the action from their message and the current state.
+- If the CLI reports an auth or app error, route to `/archastro:auth` or suggest `--app <id>`.
+- Keep responses concise — state the outcome, not the process.

.claude-plugins/archastro/commands/install.md

@@ -1,28 +1,28 @@
 ---
-description: Install the ArchAstro developer platform CLI
+description: Install the ArchAstro platform CLI
 allowed-tools: ["Bash(archastro:*)", "Bash(brew:*)", "Bash(curl:*)", "Bash(bash:*)", "Bash(sh:*)", "Bash(pwsh:*)", "Bash(powershell:*)"]
 ---
 
 # Install ArchAstro CLI
 
 Install or upgrade the public `archastro` binary from Homebrew or GitHub Releases.
 
-## Instructions
+## Workflow
 
 1. **Read the compatibility contract first**:
-   - Use `plugin-compatibility.json`.
-   - For this command, prefer `plugins.archastro.minimumCliVersion` and fall back to the top-level `minimumCliVersion`.
-   - Treat that resolved value as the minimum supported CLI version for every check below.
+   - Use `plugin-compatibility.json` from the plugin root.
+   - Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
+   - Treat the resolved value as the minimum supported CLI version for every check below.
 
 2. **Check whether the CLI is already installed**:
    ```
    archastro --version
    ```
    If this succeeds, record the version.
 
-3. **If the CLI is present and meets the resolved minimum version**, confirm the version and stop unless the user explicitly asked to upgrade.
+3. **If the CLI is present and meets the resolved minimum**, confirm the version and stop unless the user explicitly asked to upgrade.
 
-4. **If the CLI is missing or older than the resolved minimum version**, install it using the public distribution path:
+4. **If the CLI is missing or older than the resolved minimum**, install it using the public distribution path:
    - On macOS, if Homebrew is available:
      ```
      brew install ArchAstro/tools/archastro
@@ -44,12 +44,12 @@ Install or upgrade the public `archastro` binary from Homebrew or GitHub Release
    ```
    archastro --version
    ```
-   Confirm that the version now meets the resolved minimum version.
+   Confirm that the version now meets the resolved minimum.
 
-6. **On success**, tell the user the CLI is ready and suggest `/archastro:auth`.
+6. **On failure, help troubleshoot the public install path**:
+   - Missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh`.
+   - `Permission denied` usually means they need `--install-dir` or a user-writable target directory.
+   - `command not found: archastro` after install usually means the install directory is not on `PATH`.
+   - Release download failures usually mean the target release asset has not been published yet.
 
-7. **On failure**, help troubleshoot the public install path:
-   - missing `brew` is expected on Linux and some macOS setups; fall back to `install.sh`
-   - `Permission denied` usually means they need `--install-dir` or a user-writable target directory
-   - `command not found: archastro` after install usually means the install directory is not on `PATH`
-   - release download failures usually mean the target release asset has not been published yet
+7. **On success**, tell the user the CLI is ready and suggest `/archastro:auth`.