# Skill Template (Anthropic + AgentScope Aligned)

> 用于定义可执行、可路由、可评估的技能规范。
> 建议所有 `SKILL.md` 至少覆盖以下 6 个部分。

---

## Frontmatter Spec

All `SKILL.md` files should begin with a YAML frontmatter block:

```yaml
---
name: skill_name          # Required. Unique identifier for the skill.
description: ...          # Required. One-line description of the skill.
version: "1.0.0"          # Optional. Semantic version string.
tools: [...]               # Optional. Tools provided or used by this skill.
allowed_tools: [...]      # Optional. List of tool names permitted when this skill is active.
denied_tools: [...]       # Optional. List of tool names denied when this skill is active.
---
```

### Frontmatter Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique skill identifier (kebab-case recommended). |
| `description` | string | Human-readable one-line description. |
| `version` | string | Semantic version (e.g., `"1.0.0"`). |
| `tools` | list[string] | Tools provided by or associated with this skill. |
| `allowed_tools` | list[string] | Enumerates which tools are **permitted** when this skill is active. If set, only these tools may be used. |
| `denied_tools` | list[string] | Enumerates which tools are **forbidden** when this skill is active. Denied tools take precedence over `allowed_tools`. |

### Tool Restriction Rules

- If **only** `allowed_tools` is set: only those tools are accessible.
- If **only** `denied_tools` is set: all tools except those are accessible.
- If **both** are set: `allowed_tools` defines the initial set, then `denied_tools` removes from it.
- **Denial takes precedence**: a tool in `denied_tools` is always blocked even if also in `allowed_tools`.

---

## 1) When to use

- 明确触发条件（任务类型、关键词、场景）。
- 明确不应使用该技能的边界（避免误触发）。

## 2) Required inputs

- 列出最小必要输入（如 `tickers`、价格、组合状态、风险约束）。
- 声明输入缺失时的处理规则（终止 / 降级 / 请求补充）。

## 3) Decision procedure

- 采用固定步骤，确保可复现。
- 每一步说明目标、判据和产物（例如中间结论）。
- 标明冲突处理逻辑（信号冲突、数据冲突、置信度冲突）。

## 4) Tool call policy

- 说明优先使用哪些工具组与工具。
- 规定何时可以“无工具直接结论”，何时必须工具先证据后结论。
- 规定工具失败、超时、返回异常时的替代动作。

## 5) Output schema

- 定义标准输出字段，便于下游 Agent 消费与评估。
- 推荐包含：`signal`、`confidence`、`reasons`、`risks`、`invalidation`、`next_action`。
- 若是组合决策技能，必须包含每个 ticker 的 `action` 与 `quantity`。

## 6) Failure fallback

- 规定在数据不足、信号冲突、风险超限、工具不可用时的降级策略。
- 默认优先“保守 + 可解释 + 可执行”的输出。

## Optional: Evaluation hooks

定义技能的可评估指标，用于后续记忆/反思阶段写入长期经验。

### 支持的指标类型

| 指标类型 | 描述 | 适用技能 |
|---------|------|---------|
| `hit_rate` | 信号命中率 - 决策信号与实际结果的符合程度 | sentiment_review, technical_review |
| `risk_violation` | 风控违例率 - 触发风控规则的次数 | risk_review, portfolio_decisioning |
| `position_deviation` | 仓位偏离率 - 建议仓位与实际执行仓位的偏差 | portfolio_decisioning |
| `pnl_attribution` | P&L 归因一致性 - 收益归因与实际收益的匹配度 | fundamental_review, valuation_review |
| `signal_consistency` | 信号一致性 - 多来源信号的一致程度 | sentiment_review |
| `decision_latency` | 决策延迟 - 从输入到决策的耗时 | portfolio_decisioning |
| `tool_usage` | 工具使用率 - 工具调用次数与成功率的比值 | 所有技能 |
| `custom` | 自定义指标 | 特定业务场景 |

### 使用方式

```python
from backend.agents.base.evaluation_hook import EvaluationHook, MetricType

# 在技能执行开始时
evaluation_hook.start_evaluation(
    skill_name="technical_review",
    inputs={"tickers": ["AAPL"], "prices": {...}}
)

# 在技能执行过程中添加指标
evaluation_hook.add_metric(
    name="signal_confidence",
    metric_type=MetricType.HIT_RATE,
    value=0.85,
    metadata={"method": "rsi", "threshold": 30}
)

# 在技能完成时记录结果
evaluation_hook.record_outputs({"signal": "buy", "confidence": 0.8})
evaluation_hook.complete_evaluation(success=True)
```

### 评估结果存储

评估结果自动保存到 `runs/{run_id}/evaluations/{agent_id}/{skill_name}_{timestamp}.json`