Contribute a Skill

This repository is community-maintained, and new skills and improvements to existing ones are all welcome. The canonical guide lives in CONTRIBUTING.md; this page summarises it for browsing.

Before you start

Branch in this repo, not a fork. The PR workflow has a fork-gate job that fails any pull request opened from a fork; that failure cascades to the results aggregator, which is the gate on merge. If you can't push a branch to bcgov/agent-skills, you don't have the access you need. Sort that out first.

Commits must be signed. The main branch ruleset requires signed commits, so the merge will be blocked otherwise. Set up SSH or GPG commit signing once per machine; see GitHub's docs.

Check upstream catalogues first

This repository is for BC Gov–specific skills. Before adding a new skill, confirm it isn't already published in an upstream catalogue. Duplicating an upstream skill fragments the ecosystem, doubles the maintenance burden, and makes it ambiguous which one consumers should install.

The Agent Skills Directory

A vendor-neutral directory of agent skills aggregated across publishers. Good first stop for a broad sweep before drilling into the publisher-specific catalogues below.

skills.sh →

Microsoft Agent Skills

A large catalogue covering Azure SDKs, Microsoft Foundry, M365, Entra, Azure Resource Manager, plus cross-cutting workflows like azure-prepare, azure-deploy, azure-validate, azure-cost, microsoft-docs, kql, mcp-builder, cloud-solution-architect.

microsoft.github.io/skills →

Anthropic `anthropics/skills`

Reference skills for document work (pdf, docx, xlsx, pptx) and other patterns, plus material on the SKILL.md format this repo follows. See also agentskills.io.

github.com/anthropics/skills →

awesome-copilot

Community-curated index of skills, prompts, custom agents, and hooks. Also distributes vendor plugin catalogues (M365 Agents Toolkit, Power BI, Oracle-to-PostgreSQL, Spark, WorkIQ, and others), so one check covers them.

github.com/github/awesome-copilot →

If an upstream skill already covers your use case, don't re-publish it here. If it's close but not quite right, open an issue or PR upstream so the fix benefits the widest audience. Only add a new skill here if it is genuinely BC Gov–specific; for instance, it encodes BC Gov policies, conventions, internal services, regulatory requirements, or organisation-specific workflows. Include the result of this check in your PR description.

How contributions work

Branch. Create a feature branch in this repo for your change.
Add or update a skill. For a new skill, follow the spec and copy an existing skill's SKILL.md as a starting point (e.g. skills/azure-networking/SKILL.md).
Validate locally: uv run python scripts/validate_skill.py skills/<name>/SKILL.md.
Open a pull request. Describe what the skill does and why it's useful.
Pass the checks. The PR workflow validates the skills your branch changed (diffed against the base branch).
Merge. Once results is green and your branch is up to date with main, the PR can be merged. Consumers pick up the change the next time they run npx skills add bcgov/agent-skills.

Skill structure

Each skill lives in its own directory. The whole directory is what consumers install with npx skills add, so put everything the skill needs alongside its manifest:

skills/<skill-name>/
├── SKILL.md        # required: the manifest
├── scripts/        # optional: executable helpers
├── references/     # optional: heavy detail
└── assets/         # optional: examples & resources

`SKILL.md`

Mandatory name + description frontmatter, then a body with an H1 title and the seven required sections (Use When, Don't Use When, Workflow, Rules, Examples, Edge Cases, References).

name must be kebab-case (≤64 chars) and match the skill's directory name; description must be ≤1024 chars with no angle brackets. Keep the manifest under 500 lines; any scripts/, references/, or assets/ directory must be flat (one level deep).

See the spec for the full definition of every required field and what the validator checks.

Tooling

This project uses uv, so there is no requirements.txt. Dependencies are declared in pyproject.toml and installed on demand by uv run. Common commands:

make format     # auto-format Python (2-space indent, double quotes)
make lint       # lint Python with ruff + workflow YAML with yamllint
make test       # run the validator unit tests
make validate   # validate every skill

Python is formatted and linted with ruff (2-space indentation, double quotes, docstrings required on every function). Workflow YAML under .github/workflows/ is linted with yamllint. Run make format before pushing.

Review expectations

Keep skills focused: one clear purpose per skill.
Write descriptions that make it obvious when a skill should fire.
Prefer clarity over cleverness; these are shared across many teams.
Be responsive to review feedback; most PRs need a small iteration or two.

The ruleset doesn't enforce an approval count, so reviewers weigh in by convention rather than by gate. A green results check, on the other hand, is mandatory. See Pipeline & governance for the full PR, publish, and branch-protection picture.