Working With an Agent

The tools let an agent read and change your tracker. They do not say how to do a job well. That part is the method, and the remote server delivers it three ways: instructions sent when the client connects, nine prompts the client lists for you to pick, and one skill you can upload to Claude.

Instructions on connect

When a client connects, the server sends it a short set of instructions. They tell the agent to call flydocs_whoami first, to pass the organization and workspace on every call, which tool answers which kind of question, and the rules that matter most: quote issue references and statuses exactly as returned, keep the source next to each claim, and read a refusal back instead of retrying it. You get this without installing anything.

Prompts

The server offers nine prompts. Each is a playbook that calls the tools in the order the workflow expects and stops for your approval before it writes anything. In Claude Desktop they appear under the connector. In Claude Code they are slash commands named after the server, such as /mcp__flydocs-cloud__triage_backlog. Other clients list MCP prompts in their own way.

Prompt	What it does	Takes
triage_backlog Triage the backlog	Reviews what is in Backlog, proposes a priority and a next step for each issue in one table, and applies the ones you approve.	limit (default 20)
refine_issue Refine an issue into a spec	Reads one issue, drafts it in the workspace template with acceptance criteria, an estimate and a priority, links dependencies, and marks it Ready once you approve.	ref
break_down_epic Break an epic into sub-issues	Drafts the children in the workspace template, dry-runs them against it, fixes what the relay names, then creates the whole set on your approval, or none of it.	ref, count
spec_and_size Spec an idea and size it	Turns a paragraph into a specced issue, breaks it into children, and sizes the plan in points, calendar weeks and agent spend from your own history, all before anything is created.	idea, parent
weekly_project_update Write the weekly project update	Summarizes the week from the tracker (shipped, in flight, at risk) and posts a project update with a health rating you confirm.	none
what_shipped What shipped for an issue	Explains what an issue records as shipped, in plain language for someone who does not read code, with a source under every claim.	ref
feature_brief Draft a feature brief	Drafts a post or announcement for one shipped issue, using the project narrative for context. Stops for approval and publishes nothing.	ref
release_post Draft a release post	The same for a whole release: one milestone, project, sprint or list of issues, from the release digest. Stops for approval and publishes nothing.	one of milestone, project, sprint, refs; audience
delivery_report Report on a window of delivery	Reports what shipped in a window, what it cost and how fast, with the coverage caveat attached. Reads only, and stops before posting. Needs the Team plan.	days (7, 14, 30 or 90)

Every prompt also accepts organization and workspace, for when you belong to several.

The skill

If you use Claude Skills, the same playbooks are available as one skill named flydocs. It has a router at the top, the rules every job shares, and three job sections: backlog and intake, delivery and spend reporting, and release and product copy. It also carries three reference files: the tools, the issue templates, and the refusal codes.

1. Open Account → Connect your agent in the FlyDocs portal and find Skills.
2. Download the flydocs skill. The zip is listed with a version.
3. In Claude, go to Settings → Capabilities → Skills and upload it.

The version is a short fingerprint of the skill's content. It changes when the content does, so if the version on the portal differs from the one you uploaded, download it again. Earlier releases offered three skills (flydocs-pm, flydocs-lead and flydocs-marketing). Their download links still work and serve the one skill, so nothing you bookmarked breaks.

Skills and the local server

In a repository set up with the FlyDocs CLI, the method comes from the flydocs-workflow skill that flydocs init installs, paired with the local flydocs mcp server. That skill and this one cover different ground. See Skills.

Working well with it

• Name things the way you say them. Milestones, projects and sprints can be named in words. If a name matches nothing, or more than one thing, the agent is given the candidates and should ask you.
• Expect it to stop and ask. The prompts pause before any write. The breakdown prompt runs a dry run first, so a set of sub-issues is checked against the workspace template before any of them exists.
• Treat figures as history. Delivery numbers carry a coverage note. An answer of "unmeasured" is not zero.
• Ticking a criterion is a claim. The agent can tick or defer an acceptance criterion by id. Tell it the outcome is real before it does.