Turn a document into a skill

Tutorial · 6 min read

The knowledge you want an agent to have is usually already written down somewhere — an onboarding PDF, a style guide in Word, a runbook in Markdown. The gap isn't the knowledge. It's that a document is written for a person reading it start to finish, and a skill has to work for an agent that loads it mid-task and needs to act.

Skilnu can do the first pass of that conversion. Upload a document and you get back a draft SKILL.md — the core model, the definitions, the guidance, restructured as instructions. Nothing is published. You read it, fix what's wrong, and publish when you're happy, exactly like any other skill.

1. Upload the document

In the app, open + New skill and click Draft from a document, next to "Upload SKILL.md". Pick your file and wait — this takes longer than the rest of the app, because a whole document has to be read and rewritten.

These formats work: .pdf, .docx, .txt, .md, .markdown, .rst and .adoc.

Anything else is refused before it uploads. If you have a format that isn't on this list, export it to PDF first — that path is well covered.

2. Send a section, not a library

There's a length limit of about 40,000 characters of extracted text, which is roughly a long chapter. Over that, the upload is refused rather than quietly cut short — a skill drafted from the first 40,000 characters of a 300-page book, handed to you as though it were drafted from the book, would be worse than an error.

This is less of a constraint than it sounds, because the thing that makes a good skill is the same thing that fits: one coherent topic. "Our code review standards" is a skill. "The entire engineering handbook" is a folder of them. If you have a big document, split it by chapter and draft each one separately — you'll get better skills than one pass over the whole thing would have produced anyway.

3. Scanned PDFs need OCR first

A PDF that's really photographs of pages has no text to extract, so the draft comes back with a message saying so rather than an empty skill. Run it through any OCR tool first — most PDF apps have "recognize text" built in — and upload the searchable version.

A quick way to tell: open the PDF and try to select a sentence. If you can't, it's an image.

4. Read the draft properly

The draft lands in the compose form with the name and description filled in from its own frontmatter. It is a first pass by a model that read your document once, so read it as you'd read a competent colleague's first attempt, not as finished work.

Three things are worth checking every time:

Did it keep the specifics? Commands, thresholds, names of internal tools, the actual numbers. These are the most useful part of a skill and the easiest thing to lose when prose gets condensed.

Did it invent anything? The draft is told to stay inside what the document supports, but if your document was vague somewhere, check that the draft was vague in the same place rather than confidently filling the gap.

Is it instructions, or is it a summary? The failure mode to watch for is a draft that describes what the document says instead of telling the agent what to do. If a section reads like a book report, rewrite it as a rule.

5. Publish it

Edit in the form until you're happy, then publish as normal. From that point it's an ordinary skill: it can be versioned, depended on by other skills, shared with your team, and added to your MCP library.

Doing it from an agent

The same flow is available over MCP, as two tools, because the file has to reach storage between them. Ask for an upload URL, send the bytes, then ask for the draft:

get_document_upload_url(filename="handbook.pdf")
  -> { upload_url, document_key }

PUT the file's bytes to upload_url
  (no auth header -- the URL is already signed)

draft_skill_from_document(document_key=...)
  -> { name, description, skill_md }

The agent version takes an extra instructions argument the web form doesn't expose, which is genuinely useful here — "focus on chapter 3", "write it for someone new to this", "keep every code example". It layers on top of your standing compile instructions rather than replacing them.

As everywhere else, draft_skill_from_document only drafts. Shipping it is a separate publish_skill call, so an agent can't turn a document into a published skill without you seeing the draft first.

What it costs

Each draft uses one unit of your daily compile quota, on whichever model you've picked in Settings — the same budget publishing with compilation uses. A failed draft that never reached the model, like an unsupported file or one over the length limit, doesn't spend anything.

Your uploaded document is scratch space. It's deleted as soon as the draft is generated, succeed or fail, and anything that somehow survives that is removed within 24 hours. It's never part of the published skill — only the draft you review is.

What this is good for

The best candidates are documents that already encode a way of working: a style guide, a review checklist, an incident runbook, a chapter of a technical book you want an agent to apply rather than quote. Reference material with no procedure in it — an API dump, a glossary, a spreadsheet exported to PDF — makes a thin skill, because there's no guidance in the source to extract.

A good test before uploading: could someone read this document and then do something differently? If yes, it'll make a skill. If it's only something they'd look things up in, it probably won't.