warpdotdev / common-skills

# Common Skills
This repository is where common agent skills that should be shared across repositories go.
A skill belongs here when it captures a reusable workflow, convention, or operating procedure that is useful in more than one repository. Repository-specific skills should stay with the repository they apply to unless they can be generalized without losing important context.
## Repository layout
 [code] 
Each skill lives in its own directory under `.agents/skills/`. The only required file for a skill is `SKILL.md` with YAML frontmatter containing at least:
- `name`: the kebab-case skill identifier
- `description`: what the skill does and when agents should use it
## Current skills
### Spec workflow
- `write-product-spec` — writes user-facing `PRODUCT.md` specs.
- `write-tech-spec` — writes implementation-oriented `TECH.md` specs.
- `spec-driven-implementation` — guides the full spec-first workflow for substantial features.
- `implement-specs` — implements approved `PRODUCT.md` and `TECH.md` files while keeping specs and code aligned.
### Development workflow
- `create-pr` — guidance for preparing and opening pull requests.
- `write-pr-description` — writes the PR body: template sections, plain-language prose, and reviewer guidance.
- `diagnose-ci-failures` — workflow for inspecting GitHub CI failures and producing a fix plan.
- `fix-errors` — guidance for fixing build, lint, formatting, and test failures.
- `resolve-merge-conflicts` — workflow and helper script for resolving git conflicts with compact context.
- `review-pr` — produces structured PR review feedback from local diff artifacts.
- `merge-risk` — asses the risk of merging a PR from low to high.
- `check-impl-against-spec` — compares PR implementation changes against provided spec context during review.
### Factory workflow
- `migrate-to-factory` — translates existing file-defined agent workflows, skills, and scripts into an existing Warp Factory configuration repository.
### Investigation and decision-making
- `research` — delegates low signal-to-noise-ratio research work to subagents and returns distilled, evidence-backed findings.
- `cross-critique` — sharpens contested decisions by having agents critique one another's independent proposals before synthesis.
### Skill authoring
- `update-skill` — guidance for creating and maintaining skill directories and `SKILL.md` files.
- `skill-doctor` — grades a repo's installed skills by scoring recent local agent conversations, then drafts the skill edits the evidence justifies.
## Adding a shared skill
When adding a skill to this repository:
1. Put it under `.agents/skills/ /`.
2. Include a `SKILL.md` with clear frontmatter.
3. Keep the skill focused on a reusable workflow rather than one repository's private details.
4. Move large reference material into `references/` and helper automation into `scripts/`.
5. If copying from another repo, copy first, then generalize in a separate change so the provenance is easy to review.
## Generalizi