AI agents

Use Markyard with an AI agent

Install the Markyard CLI agent skill to help a compatible AI agent work safely with your Markdown documents through the Markyard CLI.

Customer guideIdentity administrator

The skill gives the agent instructions for choosing the right CLI command, checking a document binding, reviewing differences, and handling concurrent edits. It does not give the agent a Markyard account or bypass your organization's access controls.

Before you begin

You need:

an AI agent that supports the open Agent Skills format and can run terminal commands;
Node.js 22 or newer with npm and npx;
the public @markyardio/cli package installed globally for the same operating-system user as the agent; and
your organization's Markyard URL and a Markyard account.

Read Use Markyard from the command line before allowing an agent to create or push documents.

1. Install the Markyard skill

From the folder where the agent will work, run:

npx skills add https://markyard.io/skills/markyard-cli/SKILL.md

Select your agent when prompted and install the skill for the current project. A project installation makes the team's agent configuration reviewable with the rest of the project.

If you want the skill available in every project for your operating-system user, add --global and follow the prompts instead:

npx skills add https://markyard.io/skills/markyard-cli/SKILL.md --global

Confirm that the skill is installed:

npx skills list

The installed skill is named markyard-cli and may be displayed as Markyard CLI. Start a new agent session after installation so the agent discovers it.

Authenticate before asking the agent to work with documents:

markyard --server https://markyard.example.com auth login
markyard auth status

Complete sign-in in your browser. The agent can then use the saved CLI session while running as the same operating-system user. Never paste a bearer token into an agent prompt or save one in a project file.

The agent has the same Markyard permissions as the signed-in account. Use a dedicated account with only the access needed for unattended or shared agent environments.

3. Start with a read-and-review workflow

Name the skill explicitly when your agent supports named skill invocation. For example:

Use $markyard-cli to pull document DOC_ID into proposal.md. Show me its status when you are done.

Ask the agent to edit the ordinary Markdown file. Before it writes to Markyard, request a review:

Use $markyard-cli to show the status of proposal.md and compare it with the current remote
document. Summarize the differences, but do not push anything yet.

After you review the changes, authorize the remote write with the full stable document URL:

Use $markyard-cli to push proposal.md to
https://markyard.example.com/documents/DOC_ID. Stop and ask me if there is a conflict.

Compatible agents may also select the skill automatically when you ask them to create, pull, inspect, diff, or push a Markyard Markdown document. Naming $cli removes ambiguity when several skills are available.

What the agent can do

With access to the CLI and your working folder, the agent can:

Task	Typical request
Download a document	“Use `$markyard-cli` to pull document `DOC_ID` into `brief.md`.”
Create a document	“Use `$markyard-cli` to create a document titled ‘Launch brief’ from `brief.md`.”
Inspect synchronization	“Use `$markyard-cli` to check the status of `brief.md`.”
Review changes	“Use `$markyard-cli` to diff `brief.md` against the current remote document.”
Upload approved work	“Use `$markyard-cli` to push `brief.md` to this document URL.”
Help resolve a conflict	“Use `$markyard-cli` to inspect this conflict and explain what each side changed.”

The skill tells the agent to preserve Markdown as the editable source, check the server and binding before a push, and keep conflict resolution visible. The CLI still enforces document access and concurrent-update checks. If the CLI offers an update, the skill tells the agent to accept it, wait for completion, and retry the original command. An agent that cannot answer the terminal prompt uses markyard update --yes instead.

Choose approval boundaries

Configure your agent's command approvals according to the effect of each action:

Action	Effect	Recommended boundary
`status`, `diff`, `auth status`	Reads local state or remote document state.	Allow for the current project and server.
`update`, `update --yes`	Replaces a detected global npm CLI installation with the offered version.	Allow when the CLI reports an available update; never add `sudo`.
`pull`	Downloads remote content and can merge changes into a local file.	Review when the local file has edits.
`create`	Creates a new remote document.	Require explicit approval.
`push`	Changes a remote document.	Review the diff, then approve the exact file and URL.
`pull --force`	Replaces local content, binding, conflicts, or managed-image edits.	Require explicit approval every time.
`auth login`	Opens an interactive browser sign-in.	Run personally rather than unattended.

Do not give an agent blanket permission to use pull --force. The Markyard skill treats it as destructive and should explain what would be discarded before asking for approval.

Work safely with more than one agent

Give each agent its own working copy when agents may edit the same document at the same time. Before editing, have each agent pull the latest version. Before pushing, have it run status and compare against the remote document.

Markyard and the CLI can merge many concurrent Markdown changes, but an overlapping edit can still require a person to choose the final text. Do not ask an agent to discard one side of a conflict automatically.

Keep the skill current

List installed skills with:

npx skills list

To download the current version from Markyard, rerun the installation command:

npx skills add https://markyard.io/skills/markyard-cli/SKILL.md

Add --global again when the skill was installed globally. The installer shows that the existing skill will be replaced. Review skill changes through the same process you use for other agent instructions, especially before granting command approvals.

The Markyard skill follows the Agent Skills specification and uses the open skills installer.

Troubleshooting

The agent cannot find the skill

Run npx skills list, confirm markyard-cli is installed for the agent you are using, and start a new agent session from the project where you installed it.

The agent reports that `markyard` is not found

Open a terminal in the agent's environment and run markyard --version. If that fails, install the CLI for that operating-system user and restart the agent:

npm install --global @markyardio/cli

The CLI update could not be installed

Ask the agent to use the exact npm command printed by markyard update. If the CLI reports that it is running through npx or a project-local dependency, update through that same installation method. Do not authorize sudo; instead, fix the current user's npm global prefix or reinstall the CLI for that user.

Authentication is invalid or expired

Run markyard auth login yourself, complete browser sign-in, and verify the result with markyard auth status before retrying the agent task.

The remote document changed

Ask the agent to stop writing, run status, and compare the file with the remote document. Pull and review the merge. If conflict markers appear, choose the final text before authorizing another push.