Define an agent in your repository

An agent can live in a git repository: its name, instructions, skills and MCP servers as plain files. You review a change to it like any other change, and Pistis imports it as a new revision of the agent.

The smallest agentCopy Anchor Link

One file, .claude-plugin/plugin.json, with a name:

{
  "name": "Reviewer"
}

Commit it, then open Agents → Import from git, paste the repository's address and click Import.

The import screen shows this page's reference too, and Copy starter file copies this starter:

{
  "name": "My agent",
  "description": "What it does, in one line",
  "version": "1.0.0"
}

Where the files goCopy Anchor Link

At the top of the repository's default branch:

Pistis reads only plain files inside the repository; links are ignored. A skill's folder may hold other files the skill needs, up to 1 MB each.

Every fieldCopy Anchor Link

A skill is a SKILL.md whose front matter sits between two --- lines; the rest of the file is what the agent reads. A server with a command and no placement runs on your Pistis server and stays off until an admin reads the command on the agent's page and clicks Enable, because a repository is someone else's code.

How updates are picked upCopy Anchor Link

• Nothing changes by itself. Import again, or click Update from repository on the agent's page, to read the default branch as it is now. Each import makes a new revision.
• Running sessions keep the revision they started on; new sessions get the new one.
• The model, approvals, browser and pull request feedback settings you choose on the agent's page stay through an update. The repository brings the name, description, instructions, skills and MCP servers.
• The agent's id comes from name. Renaming it in plugin.json imports a different agent.

When an import failsCopy Anchor Link

The import screen lists everything wrong at once, each with its file and field: no plugin.json where Pistis looked, a file that isn't valid JSON (with the line and column), a missing or wrong field, or a repository Pistis can't read. Nothing is saved until all of them are fixed. Pistis reads repositories it can reach without a password.

ExamplesCopy Anchor Link

{
  "name": "Reviewer",
  "description": "Reviews a change for bugs, risky edits and missing tests",
  "version": "1.0.0"
}

You review code changes. Read the diff and the code around it before you say anything.
- Report bugs first, then risky edits, then missing tests. Quote the lines you mean.
- Don't change files. Finish with a short list a person can act on.

---
name: review-checklist
description: The checks to run on every change before calling it ready.
---
1. Does each changed function still handle empty, missing and very large input?
2. Is every new branch covered by a test?
3. Could this change leak a secret, a token or personal data into logs?

{
  "name": "Test fixer",
  "description": "Finds why a test fails and fixes the cause",
  "version": "1.0.0"
}

You fix failing tests. Run the failing test alone first and read its whole output.
- Fix the code under test. Change a test only when it checks the wrong thing, and say why.
- Run the full suite before you finish, then commit with a message that names the cause.

---
name: run-tests
description: How to find and run this repository's tests.
---
Look for the test command in package.json, Makefile or the CI workflow, in that order. Run one test file first, then everything.

{
  "name": "Docs writer",
  "description": "Writes and updates docs from the code",
  "version": "1.0.0"
}

You write documentation. Read the code before you describe it, and run every command you document.
- Write for someone new to the project: short sentences, one idea each, real examples.
- Update the docs that the change touches; don't start new pages unless asked.

{
  "mcpServers": {
    "deepwiki": {
      "type": "http",
      "url": "https://mcp.deepwiki.com/mcp"
    }
  }
}