Contributing Team Skills

This repo is for reusable agent skills that save team time and make repeated work more consistent. A good skill captures a workflow the team expects to reuse, not just a clever one-time prompt.

What Belongs Here

• Repeatable team workflows.
• Skills for specific tools, boards, repos, documents, APIs, or business processes.
• Templates, references, or scripts that make a skill safer or easier to use.
• Contract-specific examples only when they are safe and belong in this contract repo.

What Does Not Belong Here

• Secrets, API keys, PATs, passwords, credentials, or private tokens.
• Raw client data, raw exports, meeting recordings, or transcripts unless explicitly approved.
• One-off prompts that are not reusable.
• Skills that make destructive changes without clear review or confirmation steps.
• Personal preferences that would surprise the rest of the team.

Skill Status

Use one of these statuses in the top-level skill index and the skill README:

• Experimental: useful idea captured from real work. It is safe to inspect and try intentionally, but it is not approved for broad team use or default installation.
• Team Review: ready for others to inspect or test. The author believes the skill is reusable, documented, and safe enough for review.
• Production Ready: approved for normal team use. The skill has stable naming, complete usage docs, realistic examples, known requirements, and reviewed safeguards.
• Required: production-ready and expected for the team to use for that workflow. Use this only when the team explicitly agrees it is required.
• Deprecated: kept for history, but should not be used for new work.

Where Status Lives

Status is indicated by editing text in two repo-visible places:

• skills/<skill-name>/README.md: set the status line, for example Status: Experimental.
• Root README.md: set the matching value in the skill index Status column.

Those two values should match in the same PR. Do not rely on only a PR comment, branch name, or conversation note to indicate status.

Promotion Workflow

Most new personal agent workflows should enter the repo as Experimental. That means the contributor has captured the workflow in SKILL.md, removed secrets and raw project data, added a short README, and included at least one realistic prompt or test scenario.

Move a skill to Team Review when another teammate should be able to understand what it does without the original author narrating it. The skill should have clear triggers, expected inputs and outputs, requirements, safeguards, and enough example material for a reviewer to try it.

Move a skill to Production Ready when the team accepts it for normal use. In practice, that means review feedback is addressed, risky actions have confirmation steps, install guidance is clear, and at least one realistic example has been tested or reviewed.

Move a skill to Required only when the team explicitly decides everyone should use it for that workflow.

Status changes should be made by PR. Update both the skill README and the top-level skill index, and include the review or test evidence in the PR description.

Submission Checklist

Before opening a PR:

• Create one skill per PR.
• Put the skill under skills/<stable-folder-name>/.
• Include a required SKILL.md with clear name and description frontmatter.
• Include a short skill README.md for team-facing context.
• Use skills/_template/ as a starting point, but do not copy placeholder text into a finished skill.
• Document required tools, permissions, and assumptions.
• Include at least one realistic example prompt.
• Keep project-specific identity, URLs, and local vocabulary in references/project-profile.md when needed.
• Use sample or sanitized examples only.
• Check that no secrets or sensitive data are included.

Review Expectations

Reviewers should check:

• The skill has a clear trigger and a narrow purpose.
• The skill asks for confirmation before risky or destructive actions.
• The skill does not make broad searches or external changes without a reason.
• The skill keeps shared workflow logic separate from contract-specific project details.
• The skill can be installed intentionally without colliding with an existing global skill name.

Installing Skills

Adding a skill to this repo does not automatically mean everyone should install it globally. Install team skills intentionally after review. If a workflow applies across contracts, prefer one neutral global skill plus project context, rather than multiple same-named installed skills.