bad-example-skill

⚠️ 悪い例 - 相互依存するスキル（アンチパターン）

警告：これは、やってはいけないことを示すアンチパターンの例です。

この構造をコピーしないでください。正しい方法については、good-self-contained-skill を参照してください。

---

❌ 違反例 #1：相対パスへの依存

## Related Documentation

For setup instructions, see [../setup-skill/SKILL.md](../setup-skill/SKILL.md)

For testing patterns, see:
- [../../testing/pytest-patterns/](../../testing/pytest-patterns/)
- [../../testing/test-utils/](../../testing/test-utils/)

Database integration: [../../data/database-skill/](../../data/database-skill/)

これが間違っている理由：

• ❌ 相対パス（../、../../）を使用しています
• ❌ 階層的なディレクトリ構造を前提としています
• ❌ フラットなデプロイ（~/.claude/skills/）で動作しません
• ❌ スキルを単独でデプロイするとリンクが壊れます

正しい方法：

## Complementary Skills

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.*

---

❌ 違反例 #2：必須の内容が不足

## 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.

これが間違っている理由：

• ❌ 実際のテストパターンが含まれていません
• ❌ ユーザーが別のスキルを持っていることを前提としています
• ❌ 他のスキルがないと不完全です
• ❌ 内容を埋め込まずに「他のスキルを参照」としています

正しい方法：

## 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"}

高度なフィクスチャ（pytest-patterns スキルがデプロイされている場合）：

• パラメーター化されたフィクスチャ
• データベースセッションのフィクスチャ
• モックフィクスチャ

包括的なパターンについては、pytest-patterns スキルを参照してください。

---

## ❌ VIOLATION #3: Hard Skill Dependencies

```markdown
## Prerequisites

**Required Skills**:
1. **setup-skill** - Must be installed first
2. **database-skill** - Required for database operations
3. **pytest-patterns** - Required for testing

Install all required skills before using this skill:
```bash
claude-code skills add setup-skill database-skill pytest-patterns

これらの依存関係がないと、このスキルは動作しません。

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

**Correct Approach**:
```markdown
## Prerequisites

**External Dependencies**:
```bash
pip install example-framework pytest sqlalchemy

補完的なスキル

このスキルを使用する際は、（デプロイされている場合）次のスキルも検討してください：

• setup-skill：高度な設定パターン（任意）
• database-skill：ORM パターンと最適化（任意）
• pytest-patterns：テストの拡張機能（任意）

このスキルは単独で完全に機能します。

---

## ❌ VIOLATION #4: Cross-Skill Imports

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

# ❌ 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()

これが間違っている理由：

• ❌ 他のスキルからインポートしています
• ❌ 他のスキルがないとコードが実行されません
• ❌ 実行時の依存関係が生じます
• ❌ Python モジュールの境界に違反しています

正しい方法：

"""
Good example - self-contained implementation.
"""
from contextlib import contextmanager

# ✅ Include pattern directly in this 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()

---

❌ 違反例 #5：階層的なディレクトリ構造の前提

## 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.**

これが間違っている理由：

• ❌ 特定のディレクトリ構造を前提としています
• ❌ 相対パスを使用したナビゲーション手順です
• ❌ フラットなデプロイでは動作しません
• ❌ デプロイ先とスキル間の関係を混同しています

正しい方法：

## Related Skills

**Complementary Python Framework Skills** (informational):

- **fastapi-patterns**: Web framework patterns
- **django-patterns**: Full-stack framework patterns
- **flask-patterns**: Micro-framework patterns

**Testing Skills**:
- **pytest-patterns**: Testing framework
- **test-driven-development**: TDD workflow

*Note: Skills are independently deployable. Directory structure may vary.*

---

❌ 違反例 #6：不完全な例

# Database setup
# (See database-skill for complete implementation)

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

# Testing
# (See pytest-patterns for test examples)

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

# Deployment
# (See deployment-skill for production setup)

これが間違っている理由：

• ❌ 例が完全なコードではなく断片です
• ❌ コードを示さずに「他のスキルを参照」としています
• ❌ ユーザーがコピー＆ペーストして実行できません
• ❌ スキルに実際の実装ガイダンスがありません

正しい方法：

# 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
        }

# 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": "[email protected]"
    })
    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())

# Run with: gunicorn -w 4 app:app

---

❌ 違反例 #7：他のスキルへのパスを含む References ディレクトリ

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 の内容：

# Testing Patterns

For complete testing patterns, see:
- [Pytest Patterns](../../pytest-patterns/SKILL.md)
- [TDD Workflow](../../../universal/testing/test-driven-development/)

Refer to those skills for all testing code.

これが間違っている理由：

• ❌ References ディレクトリに他のスキルへのパスがあります
• ❌ 段階的な情報開示がスキルの範囲外に及びます
• ❌ フラットなデプロイで動作しません
• ❌ References の内容が自己完結していません

正しい方法：

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 に含める内容：

# Advanced Testing Patterns

**Advanced pytest fixtures** (this skill):

```python
# 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

さらなる拡張（pytest-patterns がデプロイされている場合）：

• フィクスチャファクトリー
• カスタムマーカー
• プラグインの統合

包括的な高度なパターンについては、pytest-patterns スキルを参照してください。

---

## ❌ VIOLATION #8: metadata.json with Skill Dependencies

```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"
  ]
}

これが間違っている理由：

• ❌ 「requires」フィールドに他のスキルが列挙されています
• ❌ "self_contained": false
• ❌ 他のスキルがないと動作しないと記載されています
• ❌ デプロイ時の結合が生じます

正しい方法：

{
  "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"
  ]
}

---

違反例のまとめ

違反	例	影響
相対パス	../../other-skill/	フラットなデプロイで動作しない
内容の不足	「X については他のスキルを参照」	不完全で、自立していません
強い依存関係	「other-skill が必要」	単独でデプロイできません
他のスキルからのインポート	from skills.other import	実行時の依存関係
階層構造の前提	「親ディレクトリに移動」	場所に依存します
不完全な例	コード断片のみ	使用できません
他のスキルへの参照	references/ に ../ がある	段階的な情報開示が機能しません
メタデータの依存関係	"requires": ["skill"]	デプロイ時の結合

---

これらの違反を修正する方法

ステップ 1：すべての相対パスを削除する

# Find violations
grep -r "\.\\./" bad-example-skill/

# Remove them - use skill names instead
# ❌ [skill](../../skill/SKILL.md)
# ✅ skill (if deployed)

ステップ 2：必須の内容を埋め込む

# Before (wrong):
## Testing
See pytest-patterns skill for all testing code.

# 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.*

ステップ 3：強い依存関係を削除する

# Before (wrong):
**Required Skills**: pytest-patterns, database-skill

# After (correct):
**Complementary Skills** (optional):
- pytest-patterns: Testing enhancements
- database-skill: ORM optimization

ステップ 4：インポートを自己完結させる

# Before (wrong):
from skills.database import get_db_session

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

ステップ 5：metadata.json を更新する

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

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

---

検証

修正後、自己完結していることを確認します。

# 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

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

---

代わりに優れた例を見る

この例をテンプレートとして使用しないでください

代わりに、以下を参照してください。

• good-self-contained-skill：正しいテンプレート
• SKILL_SELF_CONTAINMENT_STANDARD.md：完全な標準

---

覚えておいてください：この例は、してはいけないことを示しています。スキルは必ず自己完結させてください！