Bad Example Skill

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

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.

---

❌ VIOLATION #1: Relative Path Dependencies

## 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/)

Why This is Wrong:

• ❌ Uses relative paths (../, ../../)
• ❌ Assumes hierarchical directory structure
• ❌ Breaks in flat deployment (~/.claude/skills/)
• ❌ Links break when skill deployed standalone

Correct Approach:

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

---

❌ VIOLATION #2: Missing Essential Content

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

## Testing (Self-Contained)

**Essential pytest pattern** (inlined):

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

---

❌ VIOLATION #3: Hard Skill Dependencies

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

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:

## Prerequisites

**External Dependencies**:

pip install example-framework pytest sqlalchemy

## Complementary Skills

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

---

❌ VIOLATION #4: Cross-Skill Imports

"""
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()

Why This is Wrong:

• ❌ Imports from other skills
• ❌ Code won't run without other skills
• ❌ Creates runtime dependencies
• ❌ Violates Python module boundaries

Correct Approach:

"""
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()

---

❌ VIOLATION #5: Hierarchical Directory Assumptions

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

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

---

❌ VIOLATION #6: Incomplete Examples

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

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:

# 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": "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())

# Run with: gunicorn -w 4 app:app

---

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

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:

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

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:

# Advanced Testing Patterns

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

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

---

❌ VIOLATION #8: metadata.json with Skill Dependencies

{
  "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:

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

---

Summary of Violations

---

How to Fix These Violations

Step 1: Remove All Relative Paths

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

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

Step 2: Inline Essential Content

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

Step 3: Remove Hard Dependencies

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

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

Step 4: Make Imports Self-Contained

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

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

Step 5: Update metadata.json

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

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

---

Verification

After fixing, verify self-containment:

# 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

---

See Good Example Instead

DO NOT USE THIS EXAMPLE AS A TEMPLATE

Instead, see:

• [good-self-contained-skill](../good-self-contained-skill/): Correct template
• [SKILL_SELF_CONTAINMENT_STANDARD.md](../../docs/SKILL_SELF_CONTAINMENT_STANDARD.md): Complete standard

---

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

⚠️ Bad Interdependent Skill Example (Anti-Patterns)

WARNING: This directory contains ANTI-PATTERN examples showing what NOT to do.

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

---

Purpose

This example demonstrates common violations of the self-containment standard. Study these anti-patterns to understand what to avoid when creating skills.

---

❌ Critical Violations Demonstrated

Violation 1: Relative Path Dependencies

Example from SKILL.md:

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

Why It's Wrong:

• Assumes hierarchical directory structure
• Breaks when deployed to flat directory (~/.claude/skills/)
• Links become invalid when skill deployed standalone

Detection:

$ grep -r "\.\\./" bad-interdependent-skill/
bad-interdependent-skill/SKILL.md:42:For setup, see [../setup-skill/...

How to Fix: Replace with informational skill name references (no paths)

---

Violation 2: Missing Essential Content

Example from SKILL.md:

## Testing

See pytest-patterns skill for all testing code.

Why It's Wrong:

• No actual testing patterns included
• Skill is incomplete without other skills
• Users can't accomplish testing tasks with only this skill

How to Fix: Inline essential testing patterns (20-50 lines)

---

Violation 3: Hard Skill Dependencies

Example from SKILL.md:

## Prerequisites

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

This skill will not work without these dependencies.

Why It's Wrong:

• Creates deployment coupling
• Violates self-containment principle
• Limits deployment flexibility

How to Fix: Make skill self-sufficient, note optional enhancements

---

Violation 4: Cross-Skill Imports

Example from SKILL.md:

# ❌ DON'T DO THIS
from skills.database_skill import get_db_session
from skills.pytest_patterns import fixture_factory

Why It's Wrong:

• Creates runtime dependency on other skills
• Code won't run without other skills installed
• Violates Python module boundaries

How to Fix: Include patterns inline within skill

---

Violation 5: Hierarchical Directory Assumptions

Example from SKILL.md:

Navigate to parent directories for related skills:
- `../` - Other framework skills
- `../../testing/` - Testing skills

Why It's Wrong:

• Assumes specific directory structure
• Won't work in flat deployment
• Location-dependent documentation

How to Fix: Reference skills by name only (no navigation)

---

Violation 6: Incomplete Examples

Example from SKILL.md:

# Database setup
# (See database-skill for complete implementation)
class User(db.Model):
    # ... see database-skill for model definition ...
    pass

Why It's Wrong:

• Examples are fragments, not complete code
• Users can't copy-paste and run
• No actual implementation guidance

How to Fix: Provide complete, working examples

---

Violation 7: references/ with Cross-Skill Paths

Example structure:

bad-interdependent-skill/
└── references/
    └── testing.md          # Contains: ../../pytest-patterns/

Why It's Wrong:

• Progressive disclosure leads outside skill
• Breaks in flat deployment
• References aren't self-contained

How to Fix: Keep references/ within skill boundary

---

Violation 8: metadata.json with Skill Dependencies

Example from metadata.json:

{
  "requires": ["setup-skill", "database-skill"],
  "self_contained": false
}

Why It's Wrong:

• Lists other skills as requirements
• Marks skill as not self-contained
• Creates deployment coupling

How to Fix: Use "complementary_skills" field instead

---

Violation Detection

Automated Checks

Run these commands to detect violations:

# Check 1: Relative path violations
grep -r "\.\\./" bad-interdependent-skill/
# Expected: Should find violations (this is bad example)

# Check 2: Cross-skill imports
grep -r "from skills\." bad-interdependent-skill/
# Expected: Should find violations

# Check 3: "Required" language
grep -i "requires.*skill\|must.*install" bad-interdependent-skill/SKILL.md
# Expected: Should find violations

# Check 4: Hierarchical assumptions
grep -i "navigate.*parent\|directory.*structure" bad-interdependent-skill/SKILL.md
# Expected: Should find violations

Manual Review Checklist

• [ ] ❌ Uses ../ or ../../ paths (VIOLATION)
• [ ] ❌ Says "see other skill for X" without inlining (VIOLATION)
• [ ] ❌ Lists other skills as "required" (VIOLATION)
• [ ] ❌ Imports from other skills (VIOLATION)
• [ ] ❌ Assumes directory structure (VIOLATION)
• [ ] ❌ Provides incomplete examples (VIOLATION)
• [ ] ❌ references/ has cross-skill paths (VIOLATION)
• [ ] ❌ metadata.json lists skill dependencies (VIOLATION)

---

How to Fix These Violations

Fix Pattern 1: Replace Relative Paths

Before (Wrong):

See [pytest patterns](../../testing/pytest/SKILL.md)

After (Correct):

Consider pytest-patterns skill for advanced testing (if deployed)

---

Fix Pattern 2: Inline Essential Content

Before (Wrong):

## Testing
See pytest-patterns skill for testing code.

After (Correct):

## Testing (Self-Contained)

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

**Advanced patterns** (if pytest-patterns deployed):
[Brief description]

---

Fix Pattern 3: Remove Hard Dependencies

Before (Wrong):

**Required Skills**: pytest-patterns, database-skill

After (Correct):

**Complementary Skills** (optional, if deployed):
- pytest-patterns: Testing enhancements
- database-skill: ORM optimization

---

Fix Pattern 4: Self-Contained Imports

Before (Wrong):

from skills.database import get_db_session

After (Correct):

# Inline the pattern
@contextmanager
def get_db_session():
    """Database session (self-contained)."""
    # Implementation here

---

Fix Pattern 5: Remove Directory Assumptions

Before (Wrong):

Navigate to `../../testing/` for testing skills

After (Correct):

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

---

Fix Pattern 6: Complete Examples

Before (Wrong):

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

After (Correct):

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

def test_create_user(client):
    """Complete working test."""
    response = client.post("/users", json={
        "username": "test"
    })
    assert response.status_code == 201

---

Fix Pattern 7: Self-Contained references/

Before (Wrong):

references/testing.md contains:
"See ../../pytest-patterns/ for details"

After (Correct):

references/advanced-testing.md contains:
"Advanced patterns for THIS skill:
[actual content about this skill]

For complementary patterns, see pytest-patterns (if deployed)"

---

Fix Pattern 8: Update metadata.json

Before (Wrong):

{
  "requires": ["other-skill"],
  "self_contained": false
}

After (Correct):

{
  "requires": [],
  "self_contained": true,
  "complementary_skills": ["other-skill"]
}

---

Transformation Example

Before (All Violations)

# Bad Skill

## Testing

This skill requires pytest-patterns skill for testing.

See [pytest patterns](../../testing/pytest/SKILL.md) for:
- Fixtures (../../testing/pytest/fixtures.md)
- Assertions (../../testing/pytest/assertions.md)

Install pytest-patterns first:

from skills.pytest_patterns import test_client

After (Self-Contained)

# Good Skill

## Testing (Self-Contained)

**Essential pytest patterns** (inlined):

import pytest from app import create_app

@pytest.fixture def client(): """Test client fixture.""" app = create_app() return app.test_client()

def test_home(client): """Test homepage.""" response = client.get("/") assert response.status_code == 200 assert b"Hello" in response.data

**Advanced fixtures** (if pytest-patterns skill deployed):
- Parametrized fixtures
- Database fixtures with rollback
- Mock fixtures for external services

*See pytest-patterns skill for comprehensive testing guide.*

---

Checklist: Is Your Skill Like This Bad Example?

Use this checklist to verify your skill DOESN'T have these violations:

• [ ] ❌ My skill has ../ paths? (FIX REQUIRED)
• [ ] ❌ My skill says "see other skill" without inlining? (FIX REQUIRED)
• [ ] ❌ My skill lists other skills as "required"? (FIX REQUIRED)
• [ ] ❌ My skill imports from other skills? (FIX REQUIRED)
• [ ] ❌ My skill assumes directory structure? (FIX REQUIRED)
• [ ] ❌ My skill has incomplete examples? (FIX REQUIRED)
• [ ] ❌ My references/ has cross-skill paths? (FIX REQUIRED)
• [ ] ❌ My metadata.json lists skill dependencies? (FIX REQUIRED)

If you checked ANY boxes, your skill has violations. Fix them before submitting.

---

Comparison: Bad vs. Good

---

Study This Example To Learn

What to Look For

1. Identify each violation - Find all 8 violation types 2. Understand why it's wrong - Read the explanations 3. See the fix - Compare with good example 4. Apply to your skills - Avoid these patterns

Learning Exercise

1. Read through this SKILL.md 2. Find each violation (marked with ❌) 3. Read the "How to Fix" section 4. Compare with good-self-contained-skill 5. Apply lessons to your own skills

---

Resources

• [good-self-contained-skill](../good-self-contained-skill/): Correct template
• [SKILL_SELF_CONTAINMENT_STANDARD.md](../../docs/SKILL_SELF_CONTAINMENT_STANDARD.md): Complete standard
• [SKILL_CREATION_PR_CHECKLIST.md](../../docs/SKILL_CREATION_PR_CHECKLIST.md): PR checklist

---

Summary

This example is intentionally broken to teach what NOT to do.

8 Critical Violations:

1. Relative path dependencies 2. Missing essential content 3. Hard skill dependencies 4. Cross-skill imports 5. Hierarchical directory assumptions 6. Incomplete examples 7. Cross-skill references/ paths 8. Skill dependencies in metadata.json

Learn from these mistakes. Build self-contained skills instead.

---

Remember: If your skill looks like this example, it violates self-containment. Fix it before submitting!