docs: Expand Factory skill guidance

[warp-agent-staging]

What this feature does

Factory skills can come from default roles and integrations, Warp-provided platform bundles, or files your team manages. Conversation API users can attribute team-owned usage without treating every skill_path as customer-owned. Shipped in v0.2026.09.16.08.27.stable_02 (2026-09-16).

Summary

Expands the Factory skills page so factory operators can distinguish skill sources, look up the full stable bundled-skill catalog, and classify team-owned usage from Conversation API data without leaving the Factory documentation.

Changes

• Distinguished factory role and integration skills, Warp-provided platform-bundled skills, and custom file-based factory skills.
• Added the complete stable bundled-skill ID catalog with concise purposes, matching the API reference.
• Documented safe ownership attribution for input.bundled_skill_id and input.skill_path.
• Retained the API-reference cross-link for related Conversation API detail.

Content design plan

• Reader and job: A factory operator reviewing skill usage who needs to distinguish default, Warp-provided, and team-owned skills and attribute usage correctly.
• Gap today: The Factory page names platform-bundled skills in one paragraph but does not present the three skill sources together or explain why a path alone does not prove team ownership.
• Change: Expand the existing Factory skills page with a concise source model, the full stable bundled-ID catalog, and public Conversation API attribution rules. Excludes availability and implementation mechanics.

Verification

• npm run build — passed; generated the OpenAPI JSON, built the Astro site, and generated 388 Markdown docs.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — passed; checked 4,282 internal links across 389 files with 0 broken links.
• python3 .agents/skills/style_lint/style_lint.py --changed — completed; scanned 1 file and reported 3 pre-existing unrecognized-term advisories on unchanged lines.
• python3 .agents/skills/doc_quality_policy/check_compression_contract.py src/content/docs/factories/factory-skills.mdx --content-type feature-doc — passed.
• Catalog-to-reference assertion — passed; all 14 bundled-skill IDs and purposes match src/content/docs/reference/api-and-sdk/index.mdx.
• git diff origin/main...HEAD --check — passed.
• trunk check — unavailable because Trunk is not installed in the environment.

Unverified claims

None — Conversation API field semantics and skill-source behavior were verified against the merged public OpenAPI schema and warp-server source.

Documentation risk

Risk: engineering-review-required
Rationale: Explains public Conversation API skill-source fields and factory skill ownership attribution.
Source files consulted: warpdotdev/docs:developers/agent-api-openapi.yaml@f742823, warpdotdev/warp-server:logic/ai/multi_agent/utils/output/tool_call/shared/read_skill.go@028e1233066935f7d333c5cd702f0018c47b542f, warpdotdev/warp-server:logic/ai/multi_agent/skills/skills_context.go@028e1233066935f7d333c5cd702f0018c47b542f
Requested engineering reviewers: none (multiple source owners resolved: szgupta, cephalonaut, zachbai)
Engineering review status: pending
Docs override: none

Additional context

Follow-up to PR #791, which added the canonical bundled-skill catalog and API semantics.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 24, 2026 10:22pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

  

[warp-for-oss]

@hongyi-chen

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

I cancelled the in-progress review run because this pull request was closed.

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/factory-skills.mdx:20-22 — [SUGGESTION] The three-source preview list orders items as Factory role and integration skills, Warp-provided platform-bundled skills, Custom file-based factory skills, but the sections that follow appear in a different order (Custom file-based factory skills at line 24, Factory role and integration skills at line 44, Warp-provided platform-bundled skills at line 54). Requested resolution: reorder the intro list or the section headings so the preview matches the reading order.
• src/content/docs/factories/factory-skills.mdx:58-77 — [SUGGESTION] The 14-row bundled-skill-ID table duplicates src/content/docs/reference/api-and-sdk/index.mdx:105-120 verbatim, verified in sync only by a manual assertion noted in the PR body, with no automated CI check. Requested resolution: link to the reference table instead of duplicating it, or add a script that fails CI when the two tables diverge.

Verdict

Approve with nits