Agent skill for AI coding assistants

[dahlia]

Fedify already ships llms.txt and llms-full.txt at https://fedify.dev/ for AI tools that want to understand the library. A skill serves a complementary but different purpose: rather than describing what the library is, it tells an AI agent how to use the library correctly inside a user's project, and gets loaded automatically when the agent is working on relevant code.

Background: the Agent Skills standard

Agent Skills is an open standard originally developed by Anthropic and published in December 2025. It has since been adopted by Claude Code, OpenAI Codex CLI, GitHub Copilot in VS Code, Cursor, Windsurf, Goose, and others. The format is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions, plus optional scripts/, references/, and assets/ subdirectories:

skills/
└── fedify/
    ├── SKILL.md
    └── references/
        └── (optional detail pages)

The frontmatter description field is what agents use for automatic matching: when the description fits the task at hand, the agent loads and follows the skill without any explicit invocation from the user.

Distribution via npm

The skill should live inside the @fedify/fedify package itself, under packages/fedify/skills/fedify/. The package declares its skill in package.json using the agents field:

{
  "agents": {
    "skills": [
      { "name": "fedify", "path": "./skills/fedify" }
    ]
  }
}

This is purely a metadata declaration. @fedify/fedify does not need to depend on any skill tooling—the agents field is just a convention that skill-aware tools can read, similar to how exports works for bundlers.

The files field in packages/fedify/package.json also needs to include "skills" so the directory is bundled into the published tarball. The build pipeline (tsdown) requires no changes—SKILL.md files ship as-is.

On the user side, tools like skills-npm (by @antfu) read this field and wire up skills from node_modules automatically. A user who wants their agent to discover Fedify's skill adds a one-time prepare script to their own package.json:

{
  "scripts": {
    "prepare": "skills-npm"
  }
}

After that, every npm install symlinks skills from node_modules into the appropriate agent directories (.claude/skills/, .cursor/rules/, etc.), and the skill stays in sync with the installed version of Fedify. No manual file management, no separate install step, and it works for every agent that implements the Agent Skills spec—not just Claude Code.

For Deno/JSR users, the SKILL.md file in the repository remains directly accessible by URL. A separate Claude Code plugin marketplace (tracked in #489) will additionally provide an npm-independent installation path that bundles this skill together with slash commands and specialized agents.

What the skill should cover

The skill body should focus on things AI agents commonly get wrong, not on exhaustively documenting the API (that is what llms.txt is for). At minimum:

• The builder pattern: createFederationBuilder() → configure dispatchers → .build() yields a Federation. When createFederation() is appropriate instead.
• Dispatcher callbacks for actor, object, inbox, outbox, followers, following, liked, and featured collections
• Registering inbox listeners with setInboxListeners() and the activity-type-keyed handler map
• The distinction between Context and context data (the TContextData generic)
• Mounting federation into a web framework via an integration package (@fedify/express, @fedify/hono, @fedify/nuxt, @fedify/astro, @fedify/nestjs, etc.) rather than reimplementing routing by hand
• Built-in protocol endpoints: WebFinger and NodeInfo are handled automatically; user code should not reinvent them
• Outgoing activities via ctx.sendActivity() and the queue system for reliable delivery
• Using @fedify/vocab for ActivityPub vocabulary objects (not the removed src/vocab/ path from Fedify 1.x)
• Key pair management with setKeyPairsDispatcher() for HTTP Signatures and Object Integrity Proofs
• Persistent storage: the KvStore and MessageQueue interfaces and the available adapter packages (@fedify/sqlite, @fedify/postgres, @fedify/redis, @fedify/mysql, @fedify/amqp, @fedify/denokv)
• Observability: structured logging via LogTape (Fedify emits categorized log records out of the box) and distributed tracing via Fedify's built-in OpenTelemetry integration under packages/fedify/src/otel/. The skill should explain which log categories exist, which spans are emitted, and how users plug in a tracer/exporter. If the user's project has LogTape's own skill installed, the two skills should compose cleanly rather than duplicate advice.
• Looking up FEPs: when the user references a Fediverse Enhancement Proposal (e.g. FEP-8fcf), the skill should instruct the agent to clone the FEP repository locally with git clone https://codeberg.org/fediverse/fep.git and read the relevant file from the clone. Codeberg blocks web scraping, so WebFetch-style approaches fail. The FEP MCP server is an alternative when the user has it configured.
• CLI helpers: fedify init for project bootstrapping, fedify inbox and fedify lookup for debugging
• A common mistakes section — negative examples are particularly useful for AI code generation (e.g. forgetting to await federation setup, hand-rolling WebFinger or NodeInfo, importing from deprecated paths like src/vocab/, src/webfinger/, or src/runtime/, bypassing the queue for outgoing activities, calling framework-specific APIs that the integration package already abstracts)

Links into the full documentation should be included throughout rather than reproducing the content inline.

Harvesting documentation callouts

While drafting the skill, the author should scan the Markdown sources under docs/ for every GFM-style callout (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]) and ensure each one is reflected in the skill—either inline next to the relevant topic, or in the common mistakes section. Every callout is a place where the docs have already flagged something as error-prone or surprising, which makes them the highest-signal source of material for an agent skill. This harvest must be done by reading the sources directly, not reconstructed from memory.

Suggested file layout

The SKILL.md frontmatter should look roughly like:

---
name: fedify
description: >
  Use this skill when writing any code that uses Fedify to build an
  ActivityPub server in JavaScript or TypeScript. Covers the federation
  builder pattern, actor/inbox/outbox dispatchers, framework integrations,
  vocabulary objects, key management, queues and storage adapters, the CLI
  toolchain, and common mistakes to avoid. Trigger whenever the user is
  implementing a fediverse server, handling federation activities, or
  integrating Fedify with a web framework.
---

The body should stay concise (ideally under 300 lines). For anything longer, split into references/ files and link to them from the main file.

Scope

This issue covers only the skill itself and its npm distribution. The follow-up Claude Code plugin that wraps this skill together with slash commands and specialized agents (fedify-reviewer, fedify-debugger) remains tracked in #489, which will be rescoped accordingly.

References

• Agent Skills specification: https://agentskills.io/specification
• Fedify documentation index: https://fedify.dev/llms.txt
• Fedify full documentation: https://fedify.dev/llms-full.txt
• skills-npm: https://github.com/antfu/skills-npm
• npm-agentskills: https://github.com/onmax/npm-agentskills
• FEP MCP server: https://github.com/dahlia/fep-mcp