Claude Skills 工作机制：用标准化能力包管理 AI Agent

internal-analytics-skill/
├── SKILL.md
├── scripts/
│   └── generate_report.py
├── references/
│   ├── db_schema.md
│   └── metric_definitions.md
└── assets/
    └── report_template.docx

---
name: internal-analytics
description: Use this skill when the user asks for weekly business metrics, funnel analysis, retention analysis, or standard analytics reports based on the internal warehouse.
---

# Internal Analytics Skill

Use this skill to query the internal data warehouse and generate standard analytics reports.

## Workflow

1. Identify the requested business metric and time range.
2. Check `references/db_schema.md` for available tables and fields.
3. Use SQL only against approved analytics views.
4. Run `scripts/generate_report.py` to produce the final weekly report.
5. Use `assets/report_template.docx` as the report template.

## Rules

- Do not query raw user-identifiable data.
- Always include metric definitions from `references/metric_definitions.md`.
- If the requested metric is not defined, ask for clarification before generating SQL.

description: Use this skill when the user asks for weekly business metrics, funnel analysis, retention analysis, or standard analytics reports based on the internal warehouse.

description: Use this skill for data analysis.

name: internal-analytics
description: Use this skill when the user asks for weekly business metrics...

1. Identify the requested business metric and time range.
2. Check `references/db_schema.md`.
3. Run `scripts/generate_report.py`.
4. Use `assets/report_template.docx`.

internal-analytics-skill/
├── SKILL.md
├── scripts/
│   ├── run_query.py
│   └── generate_report.py
├── references/
│   ├── db_schema.md
│   ├── metric_definitions.md
│   └── report_rules.md
└── assets/
    └── weekly_report_template.docx

# Analytics Views

## dim_user
- user_id_hash: hashed user identifier
- signup_date: date of registration
- channel: acquisition channel

## fact_user_activity
- user_id_hash: hashed user identifier
- activity_date: activity date
- event_type: login, purchase, share, comment

## agg_daily_metrics
- metric_date
- new_users
- active_users
- paying_users
- revenue

# Metric Definitions

## New Users
Users whose signup_date falls within the selected date range.

## Day-7 Retention
Among users who signed up on day D, the percentage that had any activity on D+7.

## Paying Users
Users with at least one successful payment event in the selected date range.

---
name: internal-analytics
description: Use this skill for standard internal analytics reports, including weekly metrics, funnel analysis, retention analysis, and business review reports.
---

# Internal Analytics Skill

## Workflow

1. Identify report type, date range, and requested metrics.
2. Read `references/metric_definitions.md` to confirm metric definitions.
3. Read `references/db_schema.md` before generating SQL.
4. Use only aggregate views unless the user explicitly has permission for detailed analysis.
5. Execute SQL through `scripts/run_query.py`.
6. Generate the final report with `scripts/generate_report.py`.
7. Apply `assets/weekly_report_template.docx` for Word output.

## Safety Rules

- Do not output raw user-level records.
- Do not infer undocumented metric definitions.
- If a metric is ambiguous, ask for clarification.
- Include SQL and metric definitions in the appendix.

# scripts/generate_report.py
from pathlib import Path
from datetime import date

def generate_weekly_report(metrics: dict, output_path: str) -> None:
    """
    Generate a standard weekly analytics report.

    metrics example:
    {
        "new_users": 12500,
        "active_users": 83400,
        "day_7_retention": "31.2%",
        "revenue": 962000
    }
    """
    lines = [
        "# Weekly Analytics Report",
        "",
        f"Generated at: {date.today().isoformat()}",
        "",
        "## Core Metrics",
    ]

    for key, value in metrics.items():
        lines.append(f"- {key}: {value}")

    Path(output_path).write_text("\n".join(lines), encoding="utf-8")

from dataclasses import dataclass
from pathlib import Path
import yaml

@dataclass
class SkillMeta:
    name: str
    description: str
    path: Path

def load_skill_meta(skill_dir: Path) -> SkillMeta:
    skill_file = skill_dir / "SKILL.md"
    text = skill_file.read_text(encoding="utf-8")

    # 简化处理：假设文件以 YAML front matter 开头
    _, yaml_block, _ = text.split("---", 2)
    meta = yaml.safe_load(yaml_block)

    return SkillMeta(
        name=meta["name"],
        description=meta["description"],
        path=skill_dir,
    )

def discover_skills(root: str) -> list[SkillMeta]:
    root_path = Path(root)
    skills = []

    for child in root_path.iterdir():
        if child.is_dir() and (child / "SKILL.md").exists():
            skills.append(load_skill_meta(child))

    return skills

def select_skill(user_task: str, skills: list[SkillMeta]) -> SkillMeta | None:
    task = user_task.lower()

    for skill in skills:
        desc = skill.description.lower()
        keywords = [w for w in desc.replace(",", " ").split() if len(w) > 4]

        if any(keyword in task for keyword in keywords):
            return skill

    return None

description: Use this skill for documents.

description: Use this skill when filling, validating, or extracting fields from structured PDF forms.

SKILL.md                  # 任务流程、规则、资源索引
references/api.md         # API 细节
references/schema.md      # 数据结构
references/policy.md      # 业务政策

## Version

- Metric definition version: 2026-05
- Warehouse schema version: analytics-v3
- Owner: data-platform-team

internal-analytics-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── tests/
    ├── weekly_report_case.md
    ├── retention_case.md
    └── invalid_metric_case.md

# Test Case: invalid_metric_case

## User Request
Generate a weekly report with happiness score.

## Expected Behavior
The Agent should ask for clarification because "happiness score" is not defined in `references/metric_definitions.md`.