# How to Contribute New Skills to Upstream Vertical-Plugins in Financial Services > Learn how to contribute new skills to upstream vertical-plugins in financial services. Follow our clear workflow for efficient skill definition, configuration, and validation. - Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services) - Tags: how-to-guide - Published: 2026-05-07 --- **To contribute new skills to upstream vertical-plugins, create the skill definition in `plugins/vertical-plugins//skills/`, define the configuration in a [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file with proper YAML front-matter, execute [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) to distribute changes to agent bundles, and validate with [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/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//skills/` serve as the canonical source of truth for each skill. **Agent-plugins** located at `plugins/agent-plugins//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`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) utility re-copies source skills into every agent bundle that references them, while [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file and may optionally include `scripts/`, `references/`, and `assets/` subdirectories for implementation resources. ```bash mkdir -p plugins/vertical-plugins//skills/ cp -r plugins/vertical-plugins/financial-analysis/skills/skill-creator/* \ plugins/vertical-plugins//skills// ``` Replace `` with the target vertical domain and `` 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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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: ```bash 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: ```bash 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`](https://github.com/anthropics/financial-services/blob/main/README.md) specifies that you should include the sync script output in your commit history to demonstrate deterministic propagation. ```bash git checkout -b feat/add- git add plugins/vertical-plugins//skills/ git add plugins/agent-plugins/*/skills/ # Synced copies git commit -m "Add skill to vertical plugins" git push origin feat/add- ``` Open a pull request on GitHub. The CI pipeline will re-run [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) to ensure the bundled-skill check never fails in production. ## Summary - **Vertical-plugins** at `plugins/vertical-plugins//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`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) to update them. - Every skill requires a [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) with YAML front-matter containing `name` and `description` fields. - **Validation** via [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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//skills//`. 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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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.