[common-skills migration] Generalize common-skills cores to be Warp-agnostic by vkodithala · Pull Request #34 · warpdotdev/common-skills

vkodithala · 2026-06-26T14:14:38Z

What

This is the first PR in a series of changes intended to make common-skills plug-and-play with any repo (which should be particularly helpful for enterprises we're working with, like Narwhal) and present a public-facing library of skills curated by Warp. The end-goal here is to make our common skills library akin to something like this, rather than a set of skills specific to our team and repos. Here's some more context on the motivation behind this change: https://warpdev.slack.com/archives/C08KTPNQN65/p1781557027648009.

This PR makes the generic skill cores in common-skills reusable outside Warp (skill content + README only; no installation/CI machinery changes). Warp-specific behavior stays optional, and repo/team-specific behavior moves to companion skills the cores reference by name.

Related PRs:

Changes

write-product-spec / write-tech-spec — remove "in Warp" framing and client paths; generalize Linear to a generic issue tracker, delegating to a team issue-tracking skill when available. Keep the intentionally Warp-specific example wording (Warp Drive, active Warp theme) and drop the markdown-table aside.
spec-driven-implementation — generalize the issue-creation flow: prefer a team issue-tracking skill, else AGENTS.md/*-local, else ask the user.
create-pr — slim to a generic core; add deterministic base-branch discovery; delegate tracker linkage to issue-tracking; gate the Warp-only structured-question prompt behind availability.
fix-errors / diagnose-ci-failures — add a top-of-file "Related Skills" section; point at AGENTS.md/contributing/CI for check commands and name the *-local companions; replace the weak generic error-category list with a fix-errors-local extension point.
validate-changes-match-specs — keep cloud computer-use / Figma as optional; defer co-author attribution to a team agent-attribution skill (no hardcoded warp-skills host); gate Warp-only structured questions.
respond-to-pr-comments — renamed from respond-to-pr-comments-in-blocklist; keep the generic gh-based workflow and gate block-list rendering (insert_code_review_comments) and /pr-comments as Warp-terminal-only with gh/plain-text fallbacks; defer reply attribution to agent-attribution.
pr-walkthrough — keep the Warp-built branding and Matter/Matter Mono font tokens alongside neutral fallbacks; reference a branding skill (rather than a dedicated companion) for brand tokens when available.
Remove .agents/skills/brandalf (now lives in warp-skills as the branding skill).
README — reframe as a public core library with an Extension model section that explicitly enumerates the repo-specific (*-local) and team-specific (agent-attribution, issue-tracking, branding) companions the cores reference, and documents how to add them.

Validation

Every edited SKILL.md keeps valid name + description frontmatter.
No stale references to the renamed/removed skills remain.

Note: update-skill was intentionally left unchanged.

Initially, there are probably going to be some rough edges here; since we're moving repo-specific context to our client repo (PR here), and team-specific context to warp-skills (PR here), we may see issues where the agent forgets to reference the right skills for branding, issue tracking, attribution, presubmit checks, etc. It's on my personal radar to monitor these for regressions, and I'll share a message in #engineering that references this.

Conversation: https://staging.warp.dev/conversation/7b6eea54-9443-4566-93ce-d063914fba3d
Run: https://oz.staging.warp.dev/runs/019f043f-2c36-70e1-827c-adf7c1f9520e

This PR was generated with Oz.

Phase 1 of the agent-skills migration: make the generic skill cores reusable outside Warp by removing Warp/Oz/Linear coupling and hardcoded agent-attribution strings, slimming client-coupled cores, and removing the brandalf skill (which moves to warp-skills). - write-product-spec / write-tech-spec: drop "in Warp" framing, the Warp block-list/theme example, client paths, and warpdotdev/warp blob links; generalize Linear references to a generic issue tracker. - spec-driven-implementation: generalize the Linear MCP issue flow and specs/<linear-ticket-number> convention to a generic tracker/ticket id. - validate-changes-match-specs: keep cloud computer-use and Figma MCP as generic optional capabilities; replace [Warp Agent] and Co-Authored-By: Oz with generic agent attribution. - pr-walkthrough: remove the brandalf reference entirely; rely on the neutral fallback styling tokens and note an optional pr-walkthrough-local companion for brand styling. - respond-to-pr-comments-in-blocklist: make the /pr-comments workflow and insert_code_review_comments tool optional with gh/plain-text fallbacks; generalize agent attribution. - create-pr / fix-errors / diagnose-ci-failures: remove cargo/clippy/WASM/ presubmit/crates specifics and Warp skill references; reduce to generic cores and note repos may add *-local companions. - Remove .agents/skills/brandalf. - README: reflect generic cores and add a Conventions section documenting the *-local specialization pattern and the soft/optional-reference rule. Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-06-30T14:37:41Z

@vkodithala

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR generalizes the common-skills core guidance by removing Warp-specific framing, commands, paths, attribution text, and the bundled brandalf skill while documenting the *-local companion pattern for repository- or brand-specific behavior.

Concerns

No blocking correctness, security, or spec-alignment concerns found in the annotated diff.
No approved or repository spec context was provided for this PR, so there were no spec commitments to compare against.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

- create-pr: reference AGENTS.md for check commands, name the optional create-pr-local companion, merge the duplicate companion note, add a final create-pr-local reminder at PR-open, and point attribution at the optional companion/agent-attribution skill instead of hardcoding. - fix-errors: add AGENTS.md to the check-discovery sources. - pr-walkthrough: restore the "Warp PR walkthrough" branding kicker and the Matter / Matter Mono font tokens alongside generic fallbacks. - respond-to-pr-comments-in-blocklist: directly reference the bundled /pr-comments skill and gate block-list rendering to the Warp terminal, keeping the gh/plain-text fallback. - validate-changes-match-specs: point attribution at the warp-skills agent-attribution skill and re-add an optional Warp cloud agents (Oz) reference with docs link. - write-product-spec: fix the example framing, add an optional Warp markdown-table aside, and restore optional Warp Drive / Warp theme refs. Co-Authored-By: Oz <oz-agent@warp.dev>

Co-Authored-By: Oz <oz-agent@warp.dev>

vkodithala

I did a pretty thorough review here, and have several nits and then a more general comment (see the README) on how this is structured. You should heed this and make the necessary changes.

- create-pr: add base-branch discovery; delegate issue-tracker linkage to a team issue-tracking skill; gate the Warp-only structured-question prompt. - fix-errors / diagnose-ci-failures: add top-of-file Related Skills; replace the weak generic error-category list with a *-local extension point. - validate-changes-match-specs / respond-to-pr-comments: defer attribution to a team agent-attribution skill; gate Warp-only affordances with fallbacks. - Rename respond-to-pr-comments-in-blocklist -> respond-to-pr-comments. - pr-walkthrough: reference a branding skill for visual styling. - write-product-spec: keep the Warp-specific example wording; drop the markdown-table aside. - README: document the repo-specific (*-local) and team-specific companions the cores reference, and how to add them. Co-Authored-By: Oz <oz-agent@warp.dev>

captainsafia · 2026-07-01T20:58:16Z

+
+- **Generic cores** live here in `common-skills`.
+- **Repo-specific companions** live in the consuming repository and are named `*-local`.
+- **Team-specific companions** live in a team's shared skills repository and capture branding, attribution, issue tracking, and other organization-wide conventions.


Is there a naming convention for these? Can a team create a more specific create-pr skill that overrides the default?

I think this is a good point. There isn't a naming convention currently, mostly because the way I have it set up, team-specific skills sit a layer above any one common skill.

i.e., the "attribution" team skill is referenced by several skills here. I agree that we should think through a better naming convention in the future, but to avoid spending more time here I'm going to just document what the referenced team skills are (branding, attribution, etc.) for users to implement.

captainsafia · 2026-07-01T21:02:17Z

 - `name`: the kebab-case skill identifier
 - `description`: what the skill does and when agents should use it

+Companion skills that extend a core also declare:


I assume this is in the front-matter of the skill?

Yup, documented this more explicitly in latest.

captainsafia · 2026-07-01T21:03:27Z

- `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.
+- `create-pr` — prepares and opens pull requests; specialize per repo with `create-pr-local`.


Random thought: I think the -local suffix is a carryover from when I started using it for the Oz for OSS stuff but I am not sure if it is actually the best standard to use. No concrete changes requested here. Just something to think about.

I actually kinda like -local, since it's 'local' to a specific repository. Don't see any reason to remove, but lmk if you disagree!

Document where specializes metadata belongs and clarify the supported repo-local and team-scoped companion conventions. Co-Authored-By: Oz <oz-agent@warp.dev>

vkodithala marked this pull request as ready for review June 30, 2026 14:37

oz-for-oss Bot reviewed Jun 30, 2026

View reviewed changes