技能排查

数据 社区

技能解读

当前原文的自动摘译,尚未人工审校。

关键最佳实践

保持技能重点 - 每项技能一项功能 编写具体描述 - 包括用户会提到的实际术语 测试激活 - 验证 Claude 在预期时调用它 使用允许的工具 - 限制安全权限

描述示例

❌ 不好:“帮助处理数据” ✅ 好:“分析 Excel 电子表格、生成数据透视表、创建图表。在处理 .xlsx 文件时使用。” ❌ 不好:“管理配置” ✅ 好:“读取和更新 YAML/JSON 配置文件。在修改设置、环境变量或应用程序配置时使用。”

调试清单

如果 Claude 不使用您的技能: 描述缺少触发术语 用户会说 YAML 语法错误(检查 --- 标记、缩进) 描述对于何时使用不够具体 错误的文件路径或权限

查找并解决 frontmatter 问题

检查 frontmatter 是否存在:常见的 frontmatter 问题:缺少 frontmatter 块 - 文件以 # 开头,而不是 --- 修复:在文件顶部添加 YAML 块 缺少结束符 --- - 只有一个 --- 标记

系统化的技能调试工作流程

调试不起作用的技能时: 列出所有技能 - 验证技能是否存在 检查 frontmatter - 验证 YAML 结构 验证必填字段 - 确保名称和描述存在 name: 必须与目录名称匹配

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
数据
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
94 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@majiayu000 · MIT
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Writing effective Claude Code skills

## Required structure

```
skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── scripts/ (optional)
└── templates/ (optional)
```

## SKILL.md frontmatter

```yaml
---
name: lowercase-with-hyphens
description: Explain WHAT it does AND WHEN to use it. Include trigger terms users would say.
allowed-tools: [Read, Write, Bash]  # optional: restrict permissions
---
```

## Critical best practices

1. **Keep skills focused** - one capability per skill
2. **Write specific descriptions** - include actual terms users would mention
3. **Test activation** - verify Claude invokes it when expected
4. **Use allowed-tools** - restrict permissions for security

## Description examples

❌ Bad: "Helps with data"
✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files."

❌ Bad: "Manages configuration"
✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."

## Debugging checklist

If Claude doesn't use your skill:
- Description lacks trigger terms users would say
- YAML syntax errors (check `---` markers, indentation)
- Description not specific enough about WHEN to use it
- Wrong file path or permissions

### Finding and fixing frontmatter issues

**Check if frontmatter exists:**
```bash
# View first 10 lines of SKILL.md
head -10 ~/.claude/skills/*/SKILL.md
```

**Common frontmatter problems:**
1. **Missing frontmatter block** - File starts with `#` instead of `---`
   - Fix: Add YAML block at top of file
2. **Missing closing `---`** - Only one `---` marker
   - Fix: Ensure both opening and closing markers exist
3. **Missing required fields** - No `name:` or `description:`
   - Fix: Add both required fields
4. **Wrong indentation** - YAML is indentation-sensitive
   - Fix: Use 2 spaces, no tabs
5. **Missing description trigger terms** - Generic description
   - Fix: Add specific keywords users would say

**Validation script:**
```bash
# Check all skills for frontmatter
for skill in ~/.claude/skills/*/SKILL.md; do
  echo "=== $skill ==="
  if head -1 "$skill" | grep -q "^---$"; then
    echo "✓ Has frontmatter"
  else
    echo "✗ Missing frontmatter"
  fi
done
```

## Systematic skill debugging workflow

When debugging skills that aren't working:

1. **List all skills** - Verify skill exists
   ```bash
   ls -la ~/.claude/skills/
   ```

2. **Check frontmatter** - Validate YAML structure
   ```bash
   head -10 ~/.claude/skills/skill-name/SKILL.md
   ```

3. **Verify required fields** - Ensure name and description exist
   - `name:` must match directory name
   - `description:` must include trigger terms

4. **Test description specificity** - Does it explain WHEN to use?
   - Include file types, actions, or domain terms
   - Avoid generic phrases like "helps with" or "manages"

5. **Check allowed-tools** - If restricted, verify needed tools included
   ```yaml
   allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
   ```

6. **Review content** - Ensure instructions are clear and actionable

## Skills vs slash commands

**Use skills for:**
- Complex workflows with multiple files
- Automatic contextual invocation
- Comprehensive capabilities

**Use slash commands for:**
- Simple single prompts
- Manual explicit control
- Quick frequently-used operations

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。