bad-example-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

⚠️ BAD EXAMPLE - Interdependent Skill (Anti-Pattern)

⚠️ 错误示例——依赖型Skill（反模式）

WARNING: This is an ANTI-PATTERN example showing what NOT to do.

DO NOT COPY THIS STRUCTURE. See good-self-contained-skill for correct approach.

警告：这是一个展示错误做法的反模式示例，请勿效仿。

请勿复制此结构。正确实现方式请参考good-self-contained-skill。

❌ VIOLATION #1: Relative Path Dependencies

❌ 违规点1：相对路径依赖

markdown

undefined

markdown

undefined

Complementary Skills

互补Skill

Consider these related skills (if deployed):

setup-skill: Installation and configuration patterns
pytest-patterns: Testing framework and fixtures
database-skill: Database integration patterns

Note: All skills are independently deployable.

---

可参考以下相关Skill（若已部署）：

setup-skill：安装与配置模式
pytest-patterns：测试框架与夹具
database-skill：数据库集成模式

注：所有Skill均可独立部署。

---

❌ VIOLATION #2: Missing Essential Content

❌ 违规点2：缺失核心内容

markdown

undefined

markdown

undefined

Testing

测试

This skill uses pytest for testing.

See pytest-patterns skill for all testing code.

To write tests for this framework, install pytest-patterns skill and refer to its documentation.


**Why This is Wrong**:
- ❌ No actual testing patterns included
- ❌ Requires user to have another skill
- ❌ Skill is incomplete without other skills
- ❌ "See other skill" instead of inlining

**Correct Approach**:
```markdown

本Skill使用pytest进行测试。

所有测试代码请见pytest-patterns Skill。

若要为此框架编写测试，请安装pytest-patterns Skill并参考其文档。


**错误原因**：
- ❌ 未包含实际测试模式
- ❌ 要求用户必须拥有另一个Skill
- ❌ 缺少其他Skill时，本Skill功能不完整
- ❌ 用“参考其他Skill”替代了内联实现

**正确做法**：
```markdown

Testing (Self-Contained)

测试（自包含）

Essential pytest pattern (inlined):

python

import pytest
from example_framework.testing import TestClient

@pytest.fixture
def client():
    """Test client fixture."""
    return TestClient(app)

def test_home_route(client):
    """Test homepage."""
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello"}

Advanced fixtures (if pytest-patterns skill deployed):

Parametrized fixtures
Database session fixtures
Mock fixtures

See pytest-patterns skill for comprehensive patterns.

---

核心pytest模式（内联实现）：

python

import pytest
from example_framework.testing import TestClient

@pytest.fixture
def client():
    """测试客户端夹具。"""
    return TestClient(app)

def test_home_route(client):
    """测试首页路由。"""
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello"}

高级夹具（若已部署pytest-patterns Skill）：

参数化夹具
数据库会话夹具
模拟夹具

如需完整模式，请参考pytest-patterns Skill。

---

❌ VIOLATION #3: Hard Skill Dependencies

❌ 违规点3：硬依赖其他Skill

markdown

undefined

markdown

undefined

Prerequisites

前置条件

Required Skills:

setup-skill - Must be installed first
database-skill - Required for database operations
pytest-patterns - Required for testing

Install all required skills before using this skill:

bash

claude-code skills add setup-skill database-skill pytest-patterns

This skill will not work without these dependencies.


**Why This is Wrong**:
- ❌ Lists other skills as "Required"
- ❌ Skill doesn't work standalone
- ❌ Creates deployment coupling
- ❌ Violates self-containment principle

**Correct Approach**:
```markdown

必备Skill：

setup-skill - 必须先安装
database-skill - 数据库操作必备
pytest-patterns - 测试必备

使用本Skill前，请安装所有依赖Skill：

bash

claude-code skills add setup-skill database-skill pytest-patterns

缺少这些依赖，本Skill将无法正常工作。


**错误原因**：
- ❌ 将其他Skill列为“必备项”
- ❌ Skill无法独立运行
- ❌ 造成部署耦合
- ❌ 违反自包含原则

**正确做法**：
```markdown

Prerequisites

前置条件

External Dependencies:

bash

pip install example-framework pytest sqlalchemy

外部依赖：

bash

pip install example-framework pytest sqlalchemy

Complementary Skills

互补Skill

When using this skill, consider (if deployed):

setup-skill: Advanced configuration patterns (optional)
database-skill: ORM patterns and optimization (optional)
pytest-patterns: Testing enhancements (optional)

This skill is fully functional independently.

---

使用本Skill时，可按需参考（若已部署）：

setup-skill：高级配置模式（可选）
database-skill：ORM模式与优化（可选）
pytest-patterns：测试增强（可选）

本Skill可独立运行，功能完整。

---

❌ VIOLATION #4: Cross-Skill Imports

❌ 违规点4：跨Skill导入

python

"""
Bad example - importing from other skills.
"""

python

"""
错误示例——从其他Skill导入模块。
"""

❌ DON'T DO THIS

❌ 请勿这样做

from skills.database_skill import get_db_session from skills.pytest_patterns import fixture_factory from ..shared.utils import validate_input

Using imported patterns

使用导入的模式

@app.route("/users") def create_user(data): # Requires database-skill to be installed with get_db_session() as session: user = User(**data) session.add(user) return user.to_dict()


**Why This is Wrong**:
- ❌ Imports from other skills
- ❌ Code won't run without other skills
- ❌ Creates runtime dependencies
- ❌ Violates Python module boundaries

**Correct Approach**:
```python
"""
Good example - self-contained implementation.
"""
from contextlib import contextmanager

@app.route("/users") def create_user(data): # 依赖database-skill已安装 with get_db_session() as session: user = User(**data) session.add(user) return user.to_dict()


**错误原因**：
- ❌ 从其他Skill导入模块
- ❌ 缺少其他Skill时代码无法运行
- ❌ 造成运行时依赖
- ❌ 违反Python模块边界规则

**正确做法**：
```python
"""
正确示例——自包含实现。
"""
from contextlib import contextmanager

✅ Include pattern directly in this skill

✅ 将模式直接包含在本Skill中

@contextmanager def get_db_session(): """Database session context manager (self-contained).""" db = SessionLocal() try: yield db db.commit() except Exception: db.rollback() raise finally: db.close()

@app.route("/users") def create_user(data): # Works independently with get_db_session() as session: user = User(**data) session.add(user) return user.to_dict()

---

@contextmanager def get_db_session(): """数据库会话上下文管理器（自包含）。""" db = SessionLocal() try: yield db db.commit() except Exception: db.rollback() raise finally: db.close()

@app.route("/users") def create_user(data): # 可独立运行 with get_db_session() as session: user = User(**data) session.add(user) return user.to_dict()

---

❌ VIOLATION #5: Hierarchical Directory Assumptions

❌ 违规点5：假设层级目录结构

markdown

undefined

markdown

undefined

Project Structure

项目结构

This skill is located in:

toolchains/python/frameworks/bad-example-skill/

Navigate to parent directories for related skills:

```
../
```
- Other framework skills
```
../../testing/
```
- Testing skills
```
../../data/
```
- Database skills

All skills in
toolchains/python/frameworks/
are related to this skill.


**Why This is Wrong**:
- ❌ Assumes specific directory structure
- ❌ Navigation instructions using relative paths
- ❌ Won't work in flat deployment
- ❌ Confuses deployment location with skill relationships

**Correct Approach**:
```markdown

本Skill位于：

toolchains/python/frameworks/bad-example-skill/

导航至上级目录查看相关Skill：

```
../
```
- 其他框架Skill
```
../../testing/
```
- 测试Skill
```
../../data/
```
- 数据库Skill

toolchains/python/frameworks/`下的所有Skill均与本Skill相关。


**错误原因**：
- ❌ 假设了特定的目录结构
- ❌ 使用相对路径提供导航指引
- ❌ 在扁平化部署中失效
- ❌ 将部署位置与Skill关联混淆

**正确做法**：
```markdown

Related Skills

❌ VIOLATION #6: Incomplete Examples

❌ 违规点6：示例不完整

python

undefined

python

undefined

Database setup

数据库设置

(See database-skill for complete implementation)

（完整实现请见database-skill）

class User(db.Model): # ... see database-skill for model definition ... pass

class User(db.Model): # ... 模型定义请见database-skill ... pass

Testing

测试

(See pytest-patterns for test examples)

（测试示例请见pytest-patterns）

def test_user(): # ... see pytest-patterns for fixtures ... pass

def test_user(): # ... 夹具请见pytest-patterns ... pass

Deployment

部署

(See deployment-skill for production setup)

（生产环境设置请见deployment-skill）


**Why This is Wrong**:
- ❌ Examples are fragments, not complete code
- ❌ "See other skill" instead of showing code
- ❌ Users can't copy-paste and run
- ❌ Skill provides no actual implementation guidance

**Correct Approach**:
```python


**错误原因**：
- ❌ 示例仅为代码片段，非完整实现
- ❌ 用“参考其他Skill”替代代码展示
- ❌ 用户无法直接复制运行
- ❌ Skill未提供实际实现指引

**正确做法**：
```python

Complete database model (self-contained)

完整数据库模型（自包含）

from sqlalchemy import Column, Integer, String from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base): """User model - complete implementation.""" tablename = "users"

id = Column(Integer, primary_key=True)
username = Column(String(80), unique=True, nullable=False)
email = Column(String(120), unique=True, nullable=False)

def to_dict(self):
    return {
        "id": self.id,
        "username": self.username,
        "email": self.email
    }

from sqlalchemy import Column, Integer, String from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base): """用户模型——完整实现。""" tablename = "users"

id = Column(Integer, primary_key=True)
username = Column(String(80), unique=True, nullable=False)
email = Column(String(120), unique=True, nullable=False)

def to_dict(self):
    return {
        "id": self.id,
        "username": self.username,
        "email": self.email
    }

Complete test example (self-contained)

完整测试示例（自包含）

import pytest from example_framework.testing import TestClient

@pytest.fixture def client(): return TestClient(app)

def test_create_user(client): """Test user creation - complete working test.""" response = client.post("/users", json={ "username": "testuser", "email": "test@example.com" }) assert response.status_code == 201 assert response.json()["username"] == "testuser"

import pytest from example_framework.testing import TestClient

@pytest.fixture def client(): return TestClient(app)

def test_create_user(client): """测试用户创建——完整可运行测试。""" response = client.post("/users", json={ "username": "testuser", "email": "test@example.com" }) assert response.status_code == 201 assert response.json()["username"] == "testuser"

Complete deployment example (self-contained)

完整部署示例（自包含）

import os

class ProductionConfig: DEBUG = False SECRET_KEY = os.getenv("SECRET_KEY") DATABASE_URL = os.getenv("DATABASE_URL")

app = App(config=ProductionConfig())

import os

class ProductionConfig: DEBUG = False SECRET_KEY = os.getenv("SECRET_KEY") DATABASE_URL = os.getenv("DATABASE_URL")

app = App(config=ProductionConfig())

Run with: gunicorn -w 4 app:app

运行命令：gunicorn -w 4 app:app

---

---

❌ VIOLATION #7: References Directory with Cross-Skill Paths

❌ 违规点7：引用目录包含跨Skill路径

bad-example-skill/
├── SKILL.md
├── metadata.json
└── references/
    ├── testing.md          # Contains: ../../pytest-patterns/
    ├── database.md         # Contains: ../../database-skill/
    └── deployment.md       # Contains: ../../../universal/deployment/

references/testing.md contains:

markdown

undefined

bad-example-skill/
├── SKILL.md
├── metadata.json
└── references/
    ├── testing.md          # 包含：../../pytest-patterns/
    ├── database.md         # 包含：../../database-skill/
    └── deployment.md       # 包含：../../../universal/deployment/

references/testing.md内容如下：

markdown

undefined

Testing Patterns

测试模式

For complete testing patterns, see:

Pytest Patterns
TDD Workflow

Refer to those skills for all testing code.


**Why This is Wrong**:
- ❌ References directory has cross-skill paths
- ❌ Progressive disclosure leads outside skill
- ❌ Breaks in flat deployment
- ❌ References aren't self-contained

**Correct Approach**:

good-example-skill/ ├── SKILL.md ├── metadata.json └── references/ ├── advanced-patterns.md # All about THIS skill ├── api-reference.md # THIS skill's API └── examples.md # THIS skill's examples


**references/advanced-patterns.md should contain**:
```markdown

完整测试模式请见：

Pytest Patterns
TDD工作流

所有测试代码请参考上述Skill。


**错误原因**：
- ❌ 引用目录包含跨Skill路径
- ❌ 逐步引导会跳转到本Skill外部
- ❌ 在扁平化部署中失效
- ❌ 引用内容不具备自包含性

**正确做法**：

good-example-skill/ ├── SKILL.md ├── metadata.json └── references/ ├── advanced-patterns.md # 仅关于本Skill ├── api-reference.md # 本Skill的API文档 └── examples.md # 本Skill的示例


**references/advanced-patterns.md应包含**：
```markdown

Advanced Testing Patterns

高级测试模式

Advanced pytest fixtures (this skill):

python

undefined

高级pytest夹具（本Skill）：

python

undefined

Parametrized test fixture

参数化测试夹具

@pytest.fixture(params=["value1", "value2"]) def data_variants(request): return request.param

def test_with_variants(data_variants): # Test with multiple data variants assert process(data_variants) is not None


**Further enhancements** (if pytest-patterns deployed):
- Fixture factories
- Custom markers
- Plugin integration

*See pytest-patterns skill for comprehensive advanced patterns.*

@pytest.fixture(params=["value1", "value2"]) def data_variants(request): return request.param

def test_with_variants(data_variants): # 多数据变体测试 assert process(data_variants) is not None


**进一步增强**（若已部署pytest-patterns）：
- 夹具工厂
- 自定义标记
- 插件集成

*如需完整高级模式，请参考pytest-patterns Skill。*

❌ VIOLATION #8: metadata.json with Skill Dependencies

❌ 违规点8：metadata.json中包含Skill依赖

json

{
  "name": "bad-example-skill",
  "version": "1.0.0",
  "requires": [
    "setup-skill",
    "database-skill",
    "pytest-patterns"
  ],
  "self_contained": false,
  "dependencies": ["example-framework"],
  "notes": [
    "This skill requires setup-skill to be installed first",
    "Must deploy with database-skill for database operations",
    "Won't work without pytest-patterns for testing"
  ]
}

Why This is Wrong:

❌ Lists other skills in "requires" field
❌
```
"self_contained": false
```
❌ Notes say skill won't work without others
❌ Creates deployment coupling

Correct Approach:

json

{
  "name": "good-example-skill",
  "version": "1.0.0",
  "requires": [],
  "self_contained": true,
  "dependencies": ["example-framework", "pytest", "sqlalchemy"],
  "complementary_skills": [
    "setup-skill",
    "database-skill",
    "pytest-patterns"
  ],
  "notes": [
    "This skill is fully self-contained and works independently",
    "All essential patterns are inlined",
    "Complementary skills provide optional enhancements"
  ]
}

json

{
  "name": "bad-example-skill",
  "version": "1.0.0",
  "requires": [
    "setup-skill",
    "database-skill",
    "pytest-patterns"
  ],
  "self_contained": false,
  "dependencies": ["example-framework"],
  "notes": [
    "本Skill需先安装setup-skill",
    "必须与database-skill一同部署以实现数据库操作",
    "缺少pytest-patterns则无法进行测试"
  ]
}

错误原因：

❌ 在"requires"字段中列出其他Skill
❌
```
"self_contained": false
```
❌ 备注中说明缺少其他Skill时本Skill无法工作
❌ 造成部署耦合

正确做法：

json

{
  "name": "good-example-skill",
  "version": "1.0.0",
  "requires": [],
  "self_contained": true,
  "dependencies": ["example-framework", "pytest", "sqlalchemy"],
  "complementary_skills": [
    "setup-skill",
    "database-skill",
    "pytest-patterns"
  ],
  "notes": [
    "本Skill完全自包含，可独立运行",
    "所有核心模式均已内联实现",
    "互补Skill仅提供可选增强功能"
  ]
}

Summary of Violations

违规点汇总

Violation	Example	Impact
Relative Paths	`../../other-skill/`	Breaks in flat deployment
Missing Content	"See other skill for X"	Incomplete, not self-sufficient
Hard Dependencies	"Requires other-skill"	Can't deploy standalone
Cross-Skill Imports	`from skills.other import`	Runtime dependency
Hierarchical Assumptions	"Navigate to parent dir"	Location-dependent
Incomplete Examples	Code fragments only	Not usable
References Cross-Skill	`references/` has `../`	Progressive disclosure broken
Metadata Dependencies	`"requires": ["skill"]`	Deployment coupling

违规点	示例	影响
相对路径	`../../other-skill/`	扁平化部署中失效
缺失内容	"请参考其他Skill获取X"	内容不完整，无法独立使用
硬依赖	"必须依赖other-skill"	无法独立部署
跨Skill导入	`from skills.other import`	运行时依赖
层级结构假设	"导航至上级目录"	依赖部署位置
示例不完整	仅代码片段	无法直接使用
跨Skill引用	`references/` 目录包含 `../`	逐步引导失效
元数据依赖	`"requires": ["skill"]`	部署耦合

How to Fix These Violations

修复方案

Step 1: Remove All Relative Paths

步骤1：移除所有相对路径

bash

undefined

bash

undefined

Find violations

查找违规内容

grep -r ".\./" bad-example-skill/

Remove them - use skill names instead

移除相对路径，改用Skill名称

❌ skill

✅ skill (if deployed)

✅ skill（若已部署）

undefined

undefined

Step 2: Inline Essential Content

步骤2：内联核心内容

markdown

undefined

markdown

undefined

Before (wrong):

之前（错误）：

Testing

测试

See pytest-patterns skill for all testing code.

所有测试代码请见pytest-patterns Skill。

After (correct):

之后（正确）：

Testing (Self-Contained)

测试（自包含）

Essential pattern (inlined): [20-50 lines of actual testing code]

Advanced patterns (if pytest-patterns deployed):

Feature list

See pytest-patterns for comprehensive guide.

undefined

核心模式（内联实现）： [20-50行实际测试代码]

高级模式（若已部署pytest-patterns）：

功能列表

如需完整指南，请参考pytest-patterns Skill。

undefined

Step 3: Remove Hard Dependencies

步骤3：移除硬依赖

markdown

undefined

markdown

undefined

Before (wrong):

之前（错误）：

Required Skills: pytest-patterns, database-skill

必备Skill：pytest-patterns, database-skill

After (correct):

之后（正确）：

Complementary Skills (optional):

pytest-patterns: Testing enhancements
database-skill: ORM optimization

undefined

互补Skill（可选）：

pytest-patterns：测试增强
database-skill：ORM优化

undefined

Step 4: Make Imports Self-Contained

步骤4：实现自包含导入

python

undefined

python

undefined

Before (wrong):

之前（错误）：

from skills.database import get_db_session

After (correct):

之后（正确）：

@contextmanager def get_db_session(): """Inlined pattern.""" # Implementation here

undefined

@contextmanager def get_db_session(): """内联实现的模式。""" # 实现代码

undefined

Step 5: Update metadata.json

步骤5：更新metadata.json

json

// Before (wrong):
{
  "requires": ["other-skill"],
  "self_contained": false
}

// After (correct):
{
  "requires": [],
  "self_contained": true,
  "complementary_skills": ["other-skill"]
}

json

// 之前（错误）：
{
  "requires": ["other-skill"],
  "self_contained": false
}

// 之后（正确）：
{
  "requires": [],
  "self_contained": true,
  "complementary_skills": ["other-skill"]
}

Verification

验证方法

After fixing, verify self-containment:

bash

undefined

修复完成后，验证自包含性：

bash

undefined

Should return empty (no violations)

应无结果（无违规内容）

grep -r ".\./" skill-name/ grep -r "from skills." skill-name/ grep -i "requires.*skill" skill-name/SKILL.md

Isolation test

隔离测试

cp -r skill-name /tmp/skill-test/ cd /tmp/skill-test/skill-name cat SKILL.md # Should be complete and useful

cp -r skill-name /tmp/skill-test/ cd /tmp/skill-test/skill-name cat SKILL.md # 内容应完整且可用

Metadata check

元数据检查

cat metadata.json | jq '.requires' # Should be [] or external packages only

---

cat metadata.json | jq '.requires' # 应为[]或仅包含外部包

---

See Good Example Instead

请参考正确示例

DO NOT USE THIS EXAMPLE AS A TEMPLATE

Instead, see:

good-self-contained-skill: Correct template
SKILL_SELF_CONTAINMENT_STANDARD.md: Complete standard

Remember: This example shows what NOT to do. Always ensure your skills are self-contained!

请勿将本示例作为模板使用

请参考：

good-self-contained-skill：正确模板
SKILL_SELF_CONTAINMENT_STANDARD.md：完整标准

bad-example-skill

Original

Translation

⚠️ BAD EXAMPLE - Interdependent Skill (Anti-Pattern)

⚠️ 错误示例——依赖型Skill（反模式）

❌ VIOLATION #1: Relative Path Dependencies

❌ 违规点1：相对路径依赖

Related Documentation

相关文档

Complementary Skills

互补Skill

❌ VIOLATION #2: Missing Essential Content

❌ 违规点2：缺失核心内容

Testing

测试

Testing (Self-Contained)

测试（自包含）

❌ VIOLATION #3: Hard Skill Dependencies

❌ 违规点3：硬依赖其他Skill

Prerequisites

前置条件

Prerequisites

前置条件

Complementary Skills

互补Skill

❌ VIOLATION #4: Cross-Skill Imports

❌ 违规点4：跨Skill导入

❌ DON'T DO THIS

❌ 请勿这样做

Using imported patterns

使用导入的模式

✅ Include pattern directly in this skill

✅ 将模式直接包含在本Skill中

❌ VIOLATION #5: Hierarchical Directory Assumptions

❌ 违规点5：假设层级目录结构

Project Structure

项目结构

Related Skills

相关Skill

❌ VIOLATION #6: Incomplete Examples

❌ 违规点6：示例不完整

Database setup

数据库设置

(See database-skill for complete implementation)

（完整实现请见database-skill）

Testing

测试

(See pytest-patterns for test examples)

（测试示例请见pytest-patterns）

Deployment

部署

(See deployment-skill for production setup)

（生产环境设置请见deployment-skill）

Complete database model (self-contained)

完整数据库模型（自包含）

Complete test example (self-contained)

完整测试示例（自包含）

Complete deployment example (self-contained)

完整部署示例（自包含）

Run with: gunicorn -w 4 app:app

运行命令：gunicorn -w 4 app:app

❌ VIOLATION #7: References Directory with Cross-Skill Paths

❌ 违规点7：引用目录包含跨Skill路径

Testing Patterns

测试模式

Advanced Testing Patterns

高级测试模式

Parametrized test fixture

参数化测试夹具

❌ VIOLATION #8: metadata.json with Skill Dependencies

❌ 违规点8：metadata.json中包含Skill依赖

Summary of Violations

违规点汇总

How to Fix These Violations

修复方案

Step 1: Remove All Relative Paths

步骤1：移除所有相对路径

Find violations

查找违规内容

Remove them - use skill names instead