Add agent skill for adding @fedify/vocab vocabulary types

[dahlia]

Summary

Adds an agent skill (.agents/skills/add-vocab/SKILL.md) that documents the complete process of adding new ActivityPub/JSON-LD vocabulary types to the @fedify/vocab package.

The skill is intended for use with coding agents (Claude Code and similar tools) to guide vocabulary additions with enough detail that the agent does not need to reverse-engineer the format from existing YAML files each time.

What the skill covers

• YAML definition format — all top-level fields (name, uri, entity, extends, compactName, typeless, defaultContext, properties) with descriptions of semantics and when each is required
• Property definitions — non-functional vs. functional properties, redundantProperties, embedContext, untyped
• defaultContext compaction coverage — guidance on ensuring every term in the serialized JSON-LD document is covered, including properties of commonly embedded types (DataIntegrityProof, Key, Multikey, DidService, etc.)
• Range type reference — XSD types, security types, and Fedify-internal fedify:* types mapped to their TypeScript equivalents
• Preloaded context registration — when and how to add entries to packages/vocab-runtime/src/contexts.ts
• Human review requirement — an explicit warning that vocabulary errors are difficult to correct after release due to wire compatibility constraints, listing what specifically must be verified before merging

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new agent skill designed to standardize and streamline the process of adding ActivityPub/JSON-LD vocabulary types to the @fedify/vocab package. By providing comprehensive guidelines and examples, it aims to assist coding agents and human developers in correctly defining new vocabulary, ensuring wire compatibility, and preventing common errors that could impact the fediverse ecosystem. The changes also include necessary updates to project configurations to accommodate the new skill's files.

Highlights

• New Agent Skill for Vocabulary Addition: A new agent skill, add-vocab, has been introduced to guide the process of adding ActivityPub/JSON-LD vocabulary types to the @fedify/vocab package, including defining new YAML schema files or updating existing ones.
• Comprehensive Documentation: The skill provides detailed documentation covering YAML definition format, property definitions (functional vs. non-functional, redundant properties, embedContext, untyped), defaultContext compaction coverage, range type references (XSD, security, Fedify-internal), and preloaded context registration.
• Emphasis on Human Review: The documentation strongly emphasizes the critical need for careful human review of vocabulary definitions before merging, highlighting potential wire compatibility issues and outlining specific verification points such as URI matching, defaultContext completeness, and correct entity and functional flags.
• Tooling Configuration Updates: Configuration files (.hongdown.toml, deno.json, mise.toml) have been updated to properly integrate the new agent skill, primarily by excluding the new skill directories from various build and linting processes and updating the hongdown tool version.

Changelog

• .agents/skills/add-vocab/SKILL.md
  • Introduced a new agent skill document for adding vocabulary types.
• .claude/skills
  • Configured Claude to recognize the new vocabulary skill.
• .hongdown.toml
  • Excluded .claude/skills from hongdown processing.
• deno.json
  • Excluded agent and Claude skill directories from Deno's build process.
• mise.toml
  • Upgraded hongdown tool to version 0.3.4.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new agent skill document for adding ActivityPub/JSON-LD vocabulary types, which is well-structured and comprehensive. The accompanying configuration updates in .hongdown.toml and deno.json correctly exclude the new skill directories from formatting and checking tools, preventing potential conflicts. The mise.toml update is a minor version bump for a tool dependency. All changes are appropriate and contribute positively to the project's development workflow and documentation for coding agents.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.