Bundle an Agent Skills document inside @fedify/fedify#712
Bundle an Agent Skills document inside @fedify/fedify#712dahlia merged 9 commits intofedify-dev:mainfrom
Conversation
Ship an Agent Skills document at packages/fedify/skills/fedify/SKILL.md so that AI coding agents working inside a consumer project get project-local guidance on how to use Fedify correctly, staying in sync with the installed version. The skill covers the Federation builder pattern, dispatcher callbacks for actor/object/inbox/outbox/collection endpoints, inbox listeners, Context and TContextData, the web framework integration packages, built-in WebFinger and NodeInfo endpoints, outgoing activity delivery and the message queue, vocabulary imports from @fedify/vocab (and away from the deprecated shims), key pair management, persistent storage adapters, LogTape categories, OpenTelemetry wiring, FEP lookup via a Codeberg clone, the fedify CLI, and a list of common mistakes distilled from the WARNING/CAUTION callouts across docs/. Declare the skill in packages/fedify/package.json through the agents field so tools such as skills-npm can discover it, and add "skills" to the files field so it ships in the npm tarball. fedify-dev#711 Assisted-by: Claude Code:claude-opus-4-7
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds an Agent Skills bundle for Fedify: includes Changes
Sequence Diagram(s)(omitted — changes are documentation and packaging metadata; no new multi-component runtime control flow to illustrate) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
dahlia
moved this to In progress
in STF 2025–2026 Milestone 5: Comprehensive Documentation and Examples
|
@codex review |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces an 'Agent Skills' bundle for Fedify, which includes a comprehensive SKILL.md guide for AI coding agents and necessary metadata updates in package.json and CHANGES.md. The documentation covers essential topics such as the builder pattern, dispatchers, and framework integrations. Review feedback focused on ensuring npm package names are correctly formatted as inline code using backticks rather than italics, consistent with the project's Markdown standards.
There was a problem hiding this comment.
Pull request overview
Adds an Agent Skills bundle to the @fedify/fedify npm package so skill-aware AI coding tools can automatically load Fedify-specific usage guidance from node_modules.
Changes:
- Added a new
skills/fedify/SKILL.mdAgent Skills document describing recommended Fedify APIs/patterns and common pitfalls. - Updated
packages/fedify/package.jsonto ship theskills/directory and declare the skill viaagents.skills. - Documented the new distribution mechanism in
CHANGES.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| packages/fedify/skills/fedify/SKILL.md | Introduces the Fedify Agent Skills guidance document (API usage, integrations, pitfalls). |
| packages/fedify/package.json | Ensures skills/ is included in the published tarball and exposes the skill via agents.skills. |
| CHANGES.md | Adds a changelog entry announcing the bundled Agent Skills support and links. |
|
Codex Review: Didn't find any major issues. Already looking forward to the next diff. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/fedify/skills/fedify/SKILL.md`:
- Around line 39-50: The doc incorrectly states both entry points return
Federation<TContextData>; update the first bullet to state that
createFederationBuilder<TContextData>() returns a FederationBuilder (not a
Federation), and clarify that you must call await builder.build(options) to
obtain the Federation; reference the symbols createFederationBuilder,
FederationBuilder, and build in the corrected wording and keep the second bullet
describing createFederation<TContextData>(options) as-is.
- Around line 287-294: Add a new row for the `@fedify/cfworkers` adapter in the
adapter matrix inside SKILL.md: include the package name `@fedify/cfworkers` and
mark both `KvStore` and `MessageQueue` as "yes" since this package provides
`WorkersKvStore` and `WorkersMessageQueue`; update the table alongside the other
adapters so the row reads like the others (package column then `yes` for both
capabilities).
- Around line 402-405: Update the bullet to stop referencing the non-existent
shim string "@fedify/fedify/webfinger" and instead warn against importing from
the old in-tree path "src/webfinger/"; keep the note that the only deprecated
shims are "@fedify/fedify/vocab" and "@fedify/fedify/runtime" and instruct users
to import from the dedicated packages "@fedify/vocab", "@fedify/vocab-runtime",
and "@fedify/webfinger" instead.
- Around line 211-216: The docs for ctx.sendActivity need to state the
limitation that the fan-out form (passing the literal "followers" as recipients)
cannot be used when the sender is a raw SenderKeyPair or SenderKeyPair[]; update
SKILL.md to document that when using the "followers" recipient you must supply a
sender that includes an actor identifier/username (not a raw keypair), because
ctx.sendActivity enforces this at runtime — mention the exact symbols:
ctx.sendActivity, "followers", SenderKeyPair, and SenderKeyPair[] so consumers
know to provide an actor id/username instead of a raw keypair to avoid generated
type-invalid delivery code.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: c5b8416b-bfd1-45d0-9ad5-7c00e1aec6c5
📒 Files selected for processing (3)
CHANGES.mdpackages/fedify/package.jsonpackages/fedify/skills/fedify/SKILL.md
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
The Fedify skill claimed that both createFederationBuilder() and createFederation() return a Federation<TContextData>, but the builder returns a FederationBuilder<TContextData>; only .build() resolves to Federation<TContextData>. Rephrase so the distinction is clear. Also soften the Cloudflare Workers guidance: the builder is the documented approach because dispatcher registration can happen at module load time, but technically createFederation() can also be constructed inside the fetch handler. Drop the "require" wording. fedify-dev#712 (comment) fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
The @fedify/fedify package only exports ./vocab and ./runtime as deprecated shims; ./webfinger has never been a subpath export. The path agents should avoid is the old in-tree src/webfinger, not a non-existent @fedify/fedify/webfinger entrypoint. Rephrase the common-mistakes bullet accordingly; the Vocabulary imports section already described this correctly. fedify-dev#712 (comment) fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
@fedify/cfworkers ships both WorkersKvStore and WorkersMessageQueue but was missing from the KvStore/MessageQueue support table in the skill. Add the row so agents running on Cloudflare Workers see it as an option. fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
The sendActivity overload that takes the literal "followers" as the
recipients parameter only accepts { identifier } or { username } as
the sender. A raw SenderKeyPair or SenderKeyPair[] is rejected,
because Fedify needs the actor identifier to resolve the followers
collection URI. The skill previously just noted the "followers"
shortcut without this restriction, which would let agents generate
code that fails at runtime.
fedify-dev#712 (comment)
Assisted-by: Claude Code:claude-opus-4-7
|
@codex review |
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces an 'Agent Skills' bundle for Fedify, featuring a comprehensive SKILL.md file designed to guide AI coding agents in building ActivityPub-compliant applications. The changes also update package.json to declare the skill and CHANGES.md to document the addition. The review feedback identifies several Markdown formatting inconsistencies in the new documentation, specifically recommending that npm package names be formatted with backticks and file paths with italics to adhere to the repository's style guidelines.
|
Codex Review: Didn't find any major issues. Hooray! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Unregistered activity types are not "silently ignored" at the inbox. handleInbox returns HTTP 202 Accepted to the sender, and routeActivity in packages/fedify/src/federation/inbox.ts logs the activity at error level as an unsupported type before giving up. Reflect that so the skill does not mislead agents into thinking the request disappeared without a trace. fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
Project Markdown convention wraps file paths in asterisks for italics; the two in-tree src/webfinger mentions were using backticks. Switch them to *src/webfinger* so the formatting lines up with the rest of the skill and the CONTRIBUTING.md Markdown guide. fedify-dev#712 (comment) fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
|
@codex review |
|
/gemini review |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/fedify/skills/fedify/SKILL.md`:
- Around line 436-438: Update the contradictory bullet so it matches the
behavior described earlier (lines 136–138): replace the phrase "silently
dropped" with wording that states unregistered inbox activity types are logged
as unsupported and the server returns HTTP 202 (Accepted). Keep the note about
registering handlers for specific activity types and, if you want delivery-level
handling, add an explicit suggestion to add a catch-all handler on `Activity` to
handle or requeue unsupported types. Ensure references to the `Activity`
catch-all and the behavior (log + HTTP 202) are present so the documentation is
consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 10aea6b8-bb8a-4903-857f-3a1f3ce2b7ee
📒 Files selected for processing (1)
packages/fedify/skills/fedify/SKILL.md
|
Codex Review: Didn't find any major issues. You're on a roll. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
Code Review
This pull request introduces an 'Agent Skills' bundle for Fedify, designed to guide AI coding agents in using the library effectively. The changes include declaring the skill in package.json, updating the changelog, and adding a comprehensive SKILL.md file that covers core concepts like the builder pattern, dispatchers, and framework integrations. Feedback focused on ensuring that npm package names within the Markdown documentation are consistently formatted as inline code using backticks rather than italics, adhering to project style conventions.
Commit 417d12e corrected the inbox listener WARNING to say that unregistered activity types are answered with HTTP 202 and logged as unsupported, but the common-mistakes bullet at the bottom of the skill still said "silently dropped", which contradicted the earlier wording. Bring the two descriptions in line. fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
fedify.dev serves every documentation page as raw Markdown by appending .md to its path, and fedify.dev/llms.txt already uses that convention. Agents can read the Markdown directly without HTML rendering noise, so switch every fedify.dev/manual/... and fedify.dev/cli link in the skill to the .md form. Also add a short note in the intro explaining the convention and telling agents to strip the .md suffix when surfacing links to the end user, so the browser view still resolves to the HTML page. fedify-dev#712 (comment) fedify-dev#712 (comment) Assisted-by: Claude Code:claude-opus-4-7
github-project-automation
Bot
moved this from In progress
to Done
in STF 2025–2026 Milestone 5: Comprehensive Documentation and Examples
The installation page covered fedify init and manual JSR/npm installation only. Three new sections at the bottom close common post-install questions: - "Editor setup" shows the .vscode/ files fedify init writes for Deno and Node.js/Bun projects, points Zed users at the snippets they need to add by hand, and notes Oxc as an alternative to Biome and ESLint. - "Linting" is a short bridge that mentions the @fedify/lint plugin is wired up automatically and links to the Linting chapter for the rest. - "Agentic skill" documents the SKILL.md bundled inside @fedify/fedify starting with Fedify 2.2.0: skills-npm + a prepare script for Node.js/Bun, manual download via curl for Deno (with a forward pointer to the Claude Code plugin marketplace work). #711 #712 #489 Assisted-by: Claude Code:claude-opus-4-7
Summary
Adds a SKILL.md at packages/fedify/skills/fedify/ and declares it through a new
agents.skillsfield in packages/fedify/package.json, so that AI coding agents working inside a consumer project get project-local guidance on how to use Fedify. Tools implementing the Agent Skills spec, such as skills-npm, pick the skill up automatically from node_modules, keeping the guidance in sync with the installed Fedify version.Closes #711.
Rationale
Fedify already ships llms.txt and llms-full.txt on fedify.dev, but those describe what the library is. A skill describes how to use it: which APIs to reach for, which patterns to avoid, which callout-level warnings in the docs are actually load-bearing. In practice, coding agents tend to reimplement
/.well-known/webfingeror/.well-known/nodeinfoby hand, import from the deprecated@fedify/fedify/vocabshim, forget thequeueoption in production, or mint actor IDs againsthttp://localhost:3000when the process is behind a tunnel. All of those are things the existing docs already warn about; the skill collapses them into triggerable guidance that lands in the agent's context whenever it touches Fedify code.What the skill covers
Following the checklist in #711:
Federationbuilder pattern (createFederationBuildervs.createFederation), with a note that serverless runtimes such as Cloudflare Workers require the builder because bindings are per-request.setInboxListeners()with the.on(ActivityType, handler)chain and the silent-ignore behaviour for unregistered types.Context<TContextData>andRequestContext<TContextData>, with the recommendation to inject dependencies through the generic rather than module-level singletons.ctx.sendActivity()overloads and the queue-in-production requirement.@fedify/vocab, with the deprecated shims (@fedify/fedify/vocab,@fedify/fedify/runtime,@fedify/fedify/webfinger) called out.setKeyPairsDispatcher, and why you want both an RSA key (HTTP Signatures) and an Ed25519 key (Object Integrity Proofs).KvStore/MessageQueueadapter packages (@fedify/sqlite,@fedify/postgres,@fedify/mysql,@fedify/redis,@fedify/amqp,@fedify/denokv) with a support matrix.fedify.*LogTape categories Fedify emits, plus OpenTelemetry setup via thetracerProvideroption andFedifySpanExporterin@fedify/fedify/otel. The skill defers generic LogTape setup to LogTape's own skill when the consumer has it installed, so the two compose cleanly.WebFetch-style scraping.fedifyCLI (init,lookup,inbox,webfinger,nodeinfo,tunnel,relay).FederationOptions.originis pinned or x-forwarded-fetch is wired into the request path.The skill body links back to fedify.dev throughout rather than reproducing documentation content inline, so guidance stays current as the docs evolve.
Distribution
agents.skills. This is a metadata convention read by Agent Skills tooling; there is no new runtime dependency on @fedify/fedify."skills"is added to thefilesarray so the directory ships in the npm tarball. Verified withnpm pack --dry-run: the tarball lists skills/fedify/SKILL.md.