AgentSkillsCN

audit-metric

在评分体系中新增一项新的 SEO 审计指标。当您需要拓展 SEO 分析维度、增加全新质量检测项，或优化审计仪表板时，可考虑引入这一功能。

SKILL.md
--- frontmatter
name: audit-metric
description: Add a new SEO audit metric to the scoring system. Use when extending the SEO analysis, adding new quality checks, or improving the audit dashboard.
argument-hint: [metric-name] [points] [category]

Add SEO Audit Metric

Add a new metric to the Saman SEO audit scoring system.

Arguments

  • •$ARGUMENTS should contain: metric name, points value, and category

Categories (with current point totals)

  1. •Basic SEO (40 points) - Title, description, H1, content length
  2. •Keyword Optimization (30 points) - Keyphrase placement, density
  3. •Content Structure (15 points) - Heading hierarchy
  4. •Links & Media (15 points) - Internal/external links, image alts

Steps

  1. •

    Define the metric:

    • •Name and description
    • •Point value (consider category balance)
    • •Pass/fail criteria
    • •Category assignment
  2. •

    Add to calculate_seo_score() in includes/helpers.php:

php
// {Metric Name} Check ({points} points)
${metric_key}_check = {your_check_logic};
if ( ${metric_key}_check ) {
    $score += {points};
    $passed_checks[] = '{metric_key}';
} else {
    $failed_checks[] = array(
        'key'         => '{metric_key}',
        'message'     => __( '{Failure message explaining the issue}', 'saman-seo' ),
        'suggestion'  => __( '{Actionable suggestion to fix it}', 'saman-seo' ),
        'points_lost' => {points},
    );
}
  1. •

    Update the scoring documentation in the function's docblock

  2. •

    Add to React Audit UI (src-v2/pages/Audit.js):

    • •Add metric to the appropriate category section
    • •Include icon and description
    • •Handle pass/fail display states

Metric Check Examples

Content Length Check

php
$content_length = str_word_count( wp_strip_all_tags( $content ) );
$has_sufficient_content = $content_length >= 300;

Keyphrase in Title Check

php
$keyphrase_in_title = ! empty( $focus_keyphrase ) &&
    stripos( $title, $focus_keyphrase ) !== false;

Image Alt Text Check

php
preg_match_all( '/<img[^>]+>/i', $content, $images );
$images_without_alt = 0;
foreach ( $images[0] as $img ) {
    if ( ! preg_match( '/alt=["\'][^"\']+["\']/', $img ) ) {
        $images_without_alt++;
    }
}
$all_images_have_alt = $images_without_alt === 0;

Internal Links Check

php
$internal_links = \Saman\SEO\Helpers\count_internal_links( $content );
$has_internal_links = $internal_links >= 2;

Scoring Guidelines

  • •Total should equal 100 when all categories are summed
  • •Balance impact - High-impact SEO factors get more points
  • •Be actionable - Every failed check should have a clear fix
  • •Avoid false positives - Don't penalize valid content patterns

Filter Hook

The score is filterable for third-party customization:

php
/**
 * Filter the SEO score calculation.
 *
 * @param array $score_data The score data including score, passed, failed checks.
 * @param int   $post_id    The post ID.
 * @param array $meta       The post SEO meta.
 */
$score_data = apply_filters( 'samanseo_seo_score', $score_data, $post_id, $meta );

Example Usage

code
/audit-metric readability-score 10 content-structure Check content readability using Flesch-Kincaid score

This will:

  1. •Add the metric calculation to helpers.php
  2. •Update point totals for the category
  3. •Add UI display in the Audit page