Syft News Pool (CLI)

SKILL.md

---
name: syft-cli-assistant
description: Use when the user needs help installing, authenticating, troubleshooting, or using the local `syft` CLI for Syft AI news workflows. Trigger for first-time setup, `syft login` or `syft status`, followed-topics inspection, top stories, personal search, global search, Codex skill installation via `syft install-skill`, or any request asking which Syft CLI command to use.
---

# Syft CLI Assistant

Use this skill as an operational assistant for the local `syft` CLI.

Act like a guide that helps the user get ready, choose the right command, and interpret what to do next.
Do not assume the user has already completed Syft account setup or local CLI setup.

## Start With The Right Gate

Before helping with CLI commands, confirm the user is actually ready for the CLI.

1. If the user has not set up Syft AI yet, stop and direct them to [https://syft.ai](https://syft.ai).
   They need to:
   - download and use the Syft AI app
   - create a Syft account
   - set up their interest topics in the app

2. Only after that should they install the local CLI:

```bash
npm install -g @orionarm/syft-cli
```

3. Then guide the first auth check:

```bash
syft login
syft status
```

Read [references/install-and-auth.md](references/install-and-auth.md) when setup or authentication help is needed.

## Main Workflow

Choose the first matching lane:

1. The user has not set up Syft AI account or interests yet.
   Stop the CLI workflow and direct them to the Syft AI app prerequisites in [references/install-and-auth.md](references/install-and-auth.md).

2. The local `syft` command is missing.
   Guide installation with:

```bash
npm install -g @orionarm/syft-cli
```

3. The CLI exists but the user is not authenticated or is unsure.
   Guide:

```bash
syft login
syft status
```

4. The user wants to know what they follow.
   Use:

```bash
syft following
```

5. The user wants top stories from their own news pool.
   Use:

```bash
syft top
```

6. The user wants targeted search in their own news pool.
   Use:

```bash
syft search "<query>"
```

7. The user wants broader search outside their own pool.
   Use:

```bash
syft global-search "<query>"
```

8. The user wants the built-in Syft Codex skill installed from the CLI.
   Use:

```bash
syft install-skill
```

9. The user asks which command they should use.
   Read [references/command-guide.md](references/command-guide.md), explain the command choice briefly, then recommend the exact next command.

10. The user hits a setup, auth, or command problem.
    Read [references/troubleshooting.md](references/troubleshooting.md).

## Behavior Rules

1. Prefer concrete next commands over long explanations.

2. If setup is incomplete, do not jump ahead into search or analysis.
   Fix prerequisites first.

3. For first-time users, explain the difference between:
   - `syft following`
   - `syft top`
   - `syft search`
   - `syft global-search`

4. If the user wants topic-specific top stories, get the topic id from `syft following` before suggesting `syft top --topic-id <id>`.

5. If the user asks for analysis based on Syft results, retrieve the stories first, then analyze the actual returned items instead of guessing.

6. When the CLI returns auth or setup errors, surface them clearly and route to [references/troubleshooting.md](references/troubleshooting.md).

7. Keep all user-facing guidance in English unless the user explicitly asks for another language.

## References

Read only the file you need:

- [references/install-and-auth.md](references/install-and-auth.md)
- [references/command-guide.md](references/command-guide.md)
- [references/troubleshooting.md](references/troubleshooting.md)