docs: update step.skip docs after api review (#34968)

docs/src/test-api/class-test.md

@@ -1773,6 +1773,8 @@ Specifies a custom location for the step to be shown in test reports and trace v
 
 Mark a test step as "skip" to temporarily disable its execution, useful for steps that are currently failing and planned for a near-term fix. Playwright will not run the step.
 
+We recommend [`method: TestStepInfo.skip#1`] instead.
+
 **Usage**
 
 You can declare a skipped step, and Playwright will not run it.

docs/src/test-api/class-teststepinfo.md

@@ -83,12 +83,41 @@ Path on the filesystem to the attached file. Mutually exclusive with [`option: b
 ## method: TestStepInfo.skip#1
 * since: v1.51
 
-Unconditionally skip the currently running step. Test step is immediately aborted. This is similar to [`method: Test.step.skip`].
+Abort the currently running step and mark it as skipped. Useful for steps that are currently failing and planned for a near-term fix.
+
+**Usage**
+
+```js
+import { test, expect } from '@playwright/test';
+
+test('my test', async ({ page }) => {
+  await test.step('check expectations', async () => {
+    test.skip();
+    // step body below will not run
+    // ...
+  });
+});
+```
 
 ## method: TestStepInfo.skip#2
 * since: v1.51
 
-Conditionally skips the currently running step with an optional description. This is similar to [`method: Test.step.skip`].
+Conditionally skip the currently running step with an optional description. Useful for steps that should not be executed in some cases.
+
+**Usage**
+
+```js
+import { test, expect } from '@playwright/test';
+
+test('my test', async ({ page, isMobile }) => {
+  await test.step('check desktop expectations', async () => {
+    test.skip(isMobile, 'not present in the mobile layout');
+
+    // step body below will not run
+    // ...
+  });
+});
+```
 
 ### param: TestStepInfo.skip#2.condition
 * since: v1.51

packages/playwright/types/test.d.ts

@@ -5800,6 +5800,9 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
    * Mark a test step as "skip" to temporarily disable its execution, useful for steps that are currently failing and
    * planned for a near-term fix. Playwright will not run the step.
    *
+   * We recommend [testStepInfo.skip()](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-skip-1)
+   * instead.
+   *
    * **Usage**
    *
    * You can declare a skipped step, and Playwright will not run it.
@@ -9658,14 +9661,45 @@ export interface TestStepInfo {
   }): Promise<void>;
 
   /**
-   * Unconditionally skip the currently running step. Test step is immediately aborted. This is similar to
-   * [test.step.skip(title, body[, options])](https://playwright.dev/docs/api/class-test#test-step-skip).
+   * Abort the currently running step and mark it as skipped. Useful for steps that are currently failing and planned
+   * for a near-term fix.
+   *
+   * **Usage**
+   *
+   * ```js
+   * import { test, expect } from '@playwright/test';
+   *
+   * test('my test', async ({ page }) => {
+   *   await test.step('check expectations', async () => {
+   *     test.skip();
+   *     // step body below will not run
+   *     // ...
+   *   });
+   * });
+   * ```
+   *
    */
   skip(): void;
 
   /**
-   * Conditionally skips the currently running step with an optional description. This is similar to
-   * [test.step.skip(title, body[, options])](https://playwright.dev/docs/api/class-test#test-step-skip).
+   * Conditionally skip the currently running step with an optional description. Useful for steps that should not be
+   * executed in some cases.
+   *
+   * **Usage**
+   *
+   * ```js
+   * import { test, expect } from '@playwright/test';
+   *
+   * test('my test', async ({ page, isMobile }) => {
+   *   await test.step('check desktop expectations', async () => {
+   *     test.skip(isMobile, 'not present in the mobile layout');
+   *
+   *     // step body below will not run
+   *     // ...
+   *   });
+   * });
+   * ```
+   *
    * @param condition A skip condition. Test step is skipped when the condition is `true`.
    * @param description Optional description that will be reflected in a test report.
    */