> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# peaqOS AI
> Use the peaqOS agent skill to onboard machines, query MCR, and run fleet workflows from any AI coding agent.
peaqOS ships one curated agent skill — `peaqos` — that turns your AI agent into a peaqOS onboarding co-pilot. It's a [skill.md](https://agentskills.io/specification)-spec skill with first-class adapters for Claude Code, Cursor, and Windsurf, plus a manual upload path for any other runtime that reads the standard. Under the hood it drives the [`peaqos` Python CLI](/peaqos/cli) — anything you can do at the terminal, the skill can do for you with the right questions asked first.
## What the skill does
Trigger it in your agent (`/peaqos` in Claude Code, or just describe what you want elsewhere) and it picks the right mode based on what you ask:
| Mode | When it kicks in |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Demo** | First-time tour on agung testnet — full onboarding in \~15 minutes with explanations at every step. |
| **Real onboarding** | Asks five questions about your machine and deployment, recommends self-managed or proxy-managed architecture, then runs the CLI to register, mint the Machine NFT, and submit the first event. |
| **Fleet management** | Pulls MCR scores for an operator's fleet, surfaces machines with low or no rating, submits heartbeat events. |
| **Troubleshooting** | Diagnoses common failures — funding, activation, MCR lag, key mismatches — and walks you through the fix. |
The skill adapts its tone to your background: concise for developers, plain English with narrated steps for non-technical operators.
## Install
Two pieces. The CLI does the actual work; the skill is the orchestration layer your agent loads.
### 1. Install the CLI
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
python3 -m venv .peaqos-env
source .peaqos-env/bin/activate
pip install peaq-os-cli
peaqos --version
```
Python 3.10 or newer is required.
### 2. Add the skill to your agent
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
# Auto-detect (Claude Code, Cursor, or Windsurf)
npx skills add peaqnetwork/peaq-os-skills
# Or target a specific runtime
npx skills add peaqnetwork/peaq-os-skills --agent claude-code
npx skills add peaqnetwork/peaq-os-skills --agent cursor
npx skills add peaqnetwork/peaq-os-skills --agent windsurf
```
The installer ships adapters for Claude Code, Cursor, and Windsurf, auto-detecting the agent it finds on disk (or prompting if multiple are installed). Invoke `/peaqos` (Claude Code) or just describe what you want (e.g. *"onboard my machine to peaqOS"*) in Cursor or Windsurf.
For ChatGPT, Claude Projects, custom GPTs, or anywhere you can't run a local CLI, clone the repo and upload `AGENT-PROMPT.md` as the system prompt with `knowledge/` and `GUIDE.md` as knowledge sources:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
git clone https://github.com/peaqnetwork/peaq-os-skills
```
## LLM context files
Separate from the curated skill, Mintlify auto-generates machine-readable bundles of these docs. Point any agent at one of:
| File | URL | Use when |
| :-------------- | :------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
| `llms.txt` | [https://docs.peaq.xyz/llms.txt](https://docs.peaq.xyz/llms.txt) | Model has a modest context window or you want a compact index with links |
| `llms-full.txt` | [https://docs.peaq.xyz/llms-full.txt](https://docs.peaq.xyz/llms-full.txt) | Model has a large context window and you want the full docs inline |
| `skill.md` | [https://docs.peaq.xyz/skill.md](https://docs.peaq.xyz/skill.md) | Agent needs a doc-derived capabilities spec rather than prose docs |
These are doc context, not a substitute for the curated `peaqos` skill — that one knows the onboarding flow, decision tree, and recovery paths; the auto-generated bundle just knows what's on the page.
## Editor setup (docs context)
Wire the peaq docs into your editor of choice. Independent of the `peaqos` skill — useful any time you want the agent to ground answers in current docs.
Open **Cursor Settings → Features → Docs**, click **Add new doc**, and paste:
```
https://docs.peaq.xyz/llms-full.txt
```
Reference peaq in chat with `@docs` → peaq.
Windsurf has no persistent docs store. Paste into Cascade (`Cmd+L`) per chat:
```
@docs:https://docs.peaq.xyz/llms-full.txt
```
Add the Mintlify-hosted MCP server to `.mcp.json`:
```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
"mcpServers": {
"peaq-docs": { "url": "https://docs.peaq.xyz/mcp" }
}
}
```
Or one-shot install with the Mintlify CLI:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
npx @mintlify/mcp add docs.peaq.xyz
```
Same MCP URL: `https://docs.peaq.xyz/mcp`. For custom GPTs or Claude Projects, upload `llms-full.txt` as a knowledge source.
## See also
Chain-level prompting tips, Cursor Projects, peaq SDK prompt patterns.
The ground truth the skill calls into via the CLI.