filepadai
sign inget started

Writing effective skills

Skills are reusable prompt modules your agents discover and call. Get them right.

Skills live in skills/ as Markdown files. External agents discover them via GET /agent-api/v1/workspaces/:id/prompts and call them by name. A well-written skill library makes agents more consistent, easier to debug, and simpler to maintain.

What a skill is

A skill is a focused, reusable prompt module. Not a full operating brief — those belong in optional notes under agents/. A skill is a specific capability the agent can invoke:

  • summarize.md — how to summarize a source document
  • extract-entities.md — how to extract structured entities from text
  • format-report.md — how to format a finished output
  • score-relevance.md — how to evaluate whether a source is relevant

Each skill should do one thing well.

File format

Skills are plain Markdown. Keep them direct:

# Summarize

Use this skill when asked to summarize a source document.

## Instructions

Write a 3-paragraph executive summary. Structure:
1. Headline finding (1 sentence)
2. Key metrics and evidence (1 paragraph)
3. Risks and open questions (1 paragraph)

Cite the source document in each paragraph.
Do not include information that is not in the source.

## Output format

Return only the summary. No preamble, no meta-commentary.

The # Title becomes the skill name. The file's first paragraph under the title becomes the description exposed via the /prompts endpoint.

Discovery and calling

When an agent calls GET /prompts, it receives:

{
  "prompts": [
    {
      "path": "skills/summarize.md",
      "fileNodeId": "fn_abc",
      "name": "summarize.md",
      "title": "Summarize",
      "description": "Use this skill when asked to summarize a source document.",
      "contentUrl": "/agent-api/v1/workspaces/ws_abc/files/fn_abc"
    }
  ]
}

The agent then fetches the full content from contentUrl and incorporates the skill into its prompt.

Keep skills narrow

A skill that tries to do everything is worse than no skill. If you find yourself writing ## Case 1 and ## Case 2 in a single skill file, split it into two skills.

Narrow skills are:

  • Easier to improve independently
  • Easier to test with a single example
  • Easier for an agent to select correctly

Update skills when output drifts

If an agent produces output that does not match expectations, check the skill it used before adjusting operating notes or memory. Skills are often the lever.

Use FilepadAI to identify which skill the agent called:

"Which skill did external-agent use most recently?"

Then open the skill, read it as if you were the agent, and ask whether you'd produce the same output.

Versioning skills

Skills are files. Edit them, save them, and the next agent run gets the updated version. There's no deploy step.

For breaking changes that would invalidate in-progress work, consider creating a new skill such as summarize-v2.md and updating your operating notes to point to it explicitly.

Next steps