Skip to main content

SKILL.md

OpenDocs ships a public SKILL.md file specifically so agents can use the product correctly without you repeating the workflow every time.

If your tool supports skills, repo instructions, task guides, or reusable system docs, start here.

What it does​

The file teaches an agent:

  • which CLI commands exist
  • how to authenticate with an OpenDocs API key
  • how to publish a Markdown file and return the final URL
  • how to update, list, pull, and unpublish posts
  • how to handle visibility safely
  • why --json is preferred for machine workflows

Why it matters​

Without a reusable instruction file, agents tend to improvise:

  • they may forget to install the CLI
  • they may omit --json
  • they may guess the wrong visibility behavior
  • they may not understand how to find a postId before updating

SKILL.md removes those rough edges and makes OpenDocs feel like part of the agent's normal toolchain.

  1. Keep the OpenDocs SKILL.md URL handy:
https://github.com/opendocs-cc/opendocs/blob/main/SKILL.md
  1. Point your agent or framework at that file.
  2. Ask the agent to write a Markdown file and publish it.
  3. Have the agent return the resulting URL.

Example instruction​

Use the OpenDocs SKILL.md workflow for publishing Markdown. If you generate a
doc, publish it and return the final URL.

What the skill covers today​

The skill matches the current public CLI:

  • opendocs login
  • opendocs publish
  • opendocs update
  • opendocs list
  • opendocs get
  • opendocs pull
  • opendocs unpublish
  • opendocs whoami
  • opendocs logout

When to skip it​

You can skip SKILL.md if:

  • you are publishing manually from your own shell
  • your automation is calling the HTTP API directly
  • your tool does not support instruction files and you prefer to script the CLI yourself

In those cases, use the CLI quickstart or the API reference.

Best practices​

  • Keep your prompts explicit about writing Markdown and publishing it.
  • Prefer workspace visibility unless you truly need a public link.
  • Ask the agent to return both the final URL and the local file path it published.
  • Use --json whenever the agent needs to parse the result.