anthropics / anthropics/skills

Structural lint findings: name collisions in claude-api skill

未关闭
#920 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
Python
星标
176k
派生
20.8k
平均合并
7 小时 21 分钟
30 天内合并 PR
5

描述

## Summary

I ran [`claude-skill-lint`](https://www.npmjs.com/package/claude-skill-lint) (v0.5.1) against this repo. The headline finding is **5 name collisions** in the `claude-api` skill — files that silently overwrite each other when installed to a flat namespace. There's also a YAML parse error in the skill's frontmatter.

Claude Code tolerates all of these, but "tolerates" isn't "works correctly" — one file quietly wins and the rest are lost.

```
$ npx claude-skill-lint graph .
✖ 14 errors and 24 warnings in 37 files (72 files checked)
```

## Name collisions in `claude-api` (5 distinct collisions)

Multiple files share the same filename, meaning one silently overwrites the others when installed to a flat namespace. The linter reports each participating file, so 5 collisions produce 13 total error lines.

| Colliding filename | Languages involved | Files |
|---|---|---|
| `claude-api.md` | PHP, Ruby, Java, Go, C# | 5 |
| `tool-use.md` | TypeScript, Python | 2 |
| `streaming.md` | TypeScript, Python | 2 |
| `files-api.md` | TypeScript, Python | 2 |
| `batches.md` | TypeScript, Python | 2 |

**Suggested fix:** Prefix filenames with the language — e.g., `ruby-claude-api.md`, `typescript-tool-use.md` — or add a `name` field in frontmatter that disambiguates (e.g., `name: claude-api-ruby`).

## YAML parse error in `claude-api/SKILL.md`

The `description` field contains unquoted special characters (`/` in `anthropic/@anthropic-ai/sdk`, parentheses) that break YAML parsing. Wrapping the value in quotes fixes it.

## Potential false positives

The remaining 1 error and 24 warnings are likely false positives driven by linter limitations rather than real issues in this repo:

- **1 broken reference** — `./README.md` link in `typescript/claude-api/tool-use.md`; file exists but is excluded from the linter's reference index by default ignore rules
- **10 orphaned theme files** — `theme-factory/themes/` files are loaded dynamically by user selection, not via static references
- **14 orphaned shared files** — `claude-api/shared/` files are referenced via inline markdown links, which the linter doesn't track (it only tracks frontmatter `context:` references)

## Reproduction

```bash
npx claude-skill-lint@0.5.1 graph /path/to/skills/
npx claude-skill-lint@0.5.1 lint /path/to/skills/
```

---

*Generated with [`claude-skill-lint`](https://www.npmjs.com/package/claude-skill-lint) — structural validation and dependency graph analysis for Claude Code skills.*

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。