How to Contribute New Skills to Upstream Vertical-Plugins in Financial Services

To contribute new skills to upstream vertical-plugins, create the skill definition in plugins/vertical-plugins/<vertical>/skills/, define the configuration in a SKILL.md file with proper YAML front-matter, execute scripts/sync-agent-skills.py to distribute changes to agent bundles, and validate with scripts/check.py before opening a pull request.

The anthropics/financial-services repository maintains a strict separation between skill source code and agent bundles to ensure deterministic deployments. When you contribute new skills to upstream vertical-plugins, you work exclusively within the vertical-plugin directories while automated tooling handles downstream synchronization. This architecture establishes a single source of truth while preventing configuration drift across distributed agent implementations.

Understand the Plugin Architecture

The repository organizes capabilities into two distinct layers. Vertical-plugins located at plugins/vertical-plugins/<vertical>/skills/ serve as the canonical source of truth for each skill. Agent-plugins located at plugins/agent-plugins/<slug>/skills/ contain vendored copies that ship with specific agents. The relationship between these layers remains strictly one-way: vertical-plugins feed into agent-plugins, never the reverse.

Two critical scripts maintain this relationship. The scripts/sync-agent-skills.py utility re-copies source skills into every agent bundle that references them, while scripts/check.py lints manifests and verifies that bundled copies match their upstream sources exactly. This design guarantees that when you contribute new skills to upstream vertical-plugins, those changes propagate deterministically to all dependent agents.

Scaffold Your New Skill

All skill development begins in the vertical-plugins directory. Do not modify files directly in agent-plugin folders, as the sync process overwrites these automatically.

Create the Directory Structure

Navigate to the appropriate vertical directory and create a new folder for your skill. Each skill requires a top-level SKILL.md file and may optionally include scripts/, references/, and assets/ subdirectories for implementation resources.

mkdir -p plugins/vertical-plugins/<vertical>/skills/<skill-name>
cp -r plugins/vertical-plugins/financial-analysis/skills/skill-creator/* \
    plugins/vertical-plugins/<vertical>/skills/<skill-name>/

Replace <vertical> with the target vertical domain and <skill-name> with a descriptive slug for your functionality.

Use the Skill Creator Template

The repository provides a reference implementation at plugins/vertical-plugins/financial-analysis/skills/skill-creator/SKILL.md that defines best practices for skill construction. This template includes the required YAML front-matter structure and demonstrates the concise-first documentation principle. Copy this template to your new skill directory and modify the metadata fields to match your implementation.

Document the Skill Configuration

Every skill requires a SKILL.md file containing standardized YAML front-matter with at minimum the name and description keys. This metadata enables the validation scripts to index and verify your skill during the CI pipeline.

Open your generated SKILL.md and define the workflow, triggers, and usage examples. Follow the concise-first principle outlined in the skill-creator guide: prioritize clarity and brevity over exhaustive documentation. The file should explain what the skill does, when an agent should invoke it, and provide concrete input-output examples.

Sync and Validate Your Changes

After editing the source files in the vertical-plugin directory, you must propagate those changes to the agent bundles and verify integrity.

Propagate Skills to Agent Bundles

Execute the synchronization script from the repository root to copy your new skill into all agent-plugin directories that reference it:

python3 scripts/sync-agent-skills.py

This script walks the directory tree at plugins/vertical-plugins/*/skills/* and replaces matching directories under plugins/agent-plugins/*/skills/. It ensures every agent bundling your skill receives the exact same file set, eliminating version skew.

Run Repository Validation

Before committing, run the validation suite to catch drift or missing references:

python3 scripts/check.py

The validation script parses all YAML and JSON manifests, confirms that every agent-plugin skill matches its vertical source byte-for-byte, and verifies that required files exist. If this check passes, your contribution meets the repository's integrity standards.

Submit Your Contribution

With validation successful, commit only the changes within plugins/vertical-plugins/ and any automatically updated agent-plugin directories. The Contributing section of README.md specifies that you should include the sync script output in your commit history to demonstrate deterministic propagation.

git checkout -b feat/add-<skill-name>
git add plugins/vertical-plugins/<vertical>/skills/<skill-name>
git add plugins/agent-plugins/*/skills/<skill-name>  # Synced copies

git commit -m "Add <skill-name> skill to <vertical> vertical plugins"
git push origin feat/add-<skill-name>

Open a pull request on GitHub. The CI pipeline will re-run scripts/check.py to ensure the bundled-skill check never fails in production.

Summary

• Vertical-plugins at plugins/vertical-plugins/<vertical>/skills/ serve as the single source of truth for skill definitions.
• Agent-plugins contain vendored copies that must never be edited manually; use scripts/sync-agent-skills.py to update them.
• Every skill requires a SKILL.md with YAML front-matter containing name and description fields.
• Validation via scripts/check.py prevents drift by ensuring agent bundles match their upstream vertical sources exactly.
• The skill-creator template at plugins/vertical-plugins/financial-analysis/skills/skill-creator/SKILL.md provides the authoritative pattern for new skills.

Frequently Asked Questions

Where should I create a new skill when contributing to upstream vertical-plugins?

Create new skills exclusively within plugins/vertical-plugins/<vertical>/skills/<skill-name>/. Never modify files directly in plugins/agent-plugins/, as these directories contain auto-generated copies that the sync script overwrites. The vertical-plugin directory is the only location that persists your source code changes.

What files are required in a new skill contribution?

Every skill requires a SKILL.md file at the root of the skill directory with YAML front-matter specifying at minimum the name and description keys. You may optionally include scripts/, references/, and assets/ subdirectories for implementation resources, but the SKILL.md metadata is mandatory for the validation script to index your contribution.

How do I update agent bundles after modifying a skill?

Run python3 scripts/sync-agent-skills.py from the repository root after saving your changes in the vertical-plugin directory. This script automatically discovers your new or modified skill and copies it into every agent-plugin directory that references it, ensuring deterministic propagation across all agent bundles.

What validation checks run before my contribution can merge?

The scripts/check.py utility parses all YAML/JSON manifests, verifies that every file in plugins/agent-plugins/*/skills/ matches its corresponding source in plugins/vertical-plugins/, and confirms required files exist. This prevents "drift" where agent bundles might contain outdated or modified copies of canonical skills, ensuring strict consistency between upstream vertical-plugins and downstream agent implementations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}