#!/usr/bin/env python3
"""skill-name: Brief description of what the script does.

This docstring becomes --help output AND is immediately visible to the LLM.
It should contain:
- Purpose (one sentence)
- Usage examples
- Key behaviors

Usage:
    python script.py command [options]
    
Examples:
    python script.py move north --quiet
    python script.py examine sword --verbose
"""

import argparse
from pathlib import Path
import yaml

# move command
move_parser = subparsers.add_parser("move", help="Move in a direction")
move_parser.add_argument("direction", choices=VALID_DIRECTIONS,
                         help="Direction to move")
move_parser.add_argument("--quiet", "-q", action="store_true",
                         help="Suppress output")

# examine command
examine_parser = subparsers.add_parser("examine", help="Look at something")
examine_parser.add_argument("target", help="What to examine")
examine_parser.add_argument("--verbose", "-v", action="store_true",
                            help="Show details")

# status command
status_parser = subparsers.add_parser("status", help="Show game state")
status_parser.add_argument("--verbose", "-v", action="store_true",
                           help="Show details")

args = parser.parse_args()
_dispatch(args)

undefined

undefined

undefined

@click.option('--verbose', '-v', is_flag=True, help='Show details')

undefined

These comments ARE data. The LLM reads them. Acts on them. Uses them to understand *why*, not just *what*.

---

undefined

**Don't trim Christmas trees:**

Avoid ASCII art or box-drawing in comments. Use plain section comments instead:

```python

**Do include useful semantic comments:**

```python

**The rule:** Every comment token should carry meaning. If it's just decoration, delete it.

---

undefined

With argparse, `main()` contains the **entire CLI tree** with no implementation:

```python

# examine command
examine_parser = subparsers.add_parser("examine", help="Look at something")
examine_parser.add_argument("target", help="What to examine")
examine_parser.add_argument("--verbose", "-v", action="store_true")

# move command
move_parser = subparsers.add_parser("move", help="Move in a direction")
move_parser.add_argument("direction", choices=VALID_DIRECTIONS)

args = parser.parse_args()
_dispatch(args)  # ← implementation is ELSEWHERE

**The LLM reads `main()` and sees the entire command tree** — arguments, types, choices, help text — without any implementation noise. Pure sniffability. No need to hold your nose.

---

skill/
├── SKILL.md           # Tells LLM how to generate scripts
├── CARD.yml           # Interface definition
└── scripts/
    └── helper.py      # Sniffable Python

from pathlib import Path

**Why `__file__`?**
- `Path(__file__)` — path to THIS script file
- `.resolve()` — resolve symlinks to get real location
- `.parent` — containing directory

**Why NOT `os.getcwd()`?**
- `os.getcwd()` returns the CALLER's directory
- Script invoked from `/home/user/` won't find `skills/foo/patterns/`

#!/usr/bin/env python3
"""sister-tool: Brief description.

Usage:
    python3 skills/my-skill/scripts/sister-tool.py command [options]
    
Can be invoked from any directory — finds its own context.
"""

from pathlib import Path
import argparse
import yaml

undefined

undefined

**The LIFT stage produces sniffable Python because:**
- Others (human and LLM) need to understand the tool quickly
- The CLI must be discoverable without reading implementation
- The script must be maintainable without spelunking

**See:** [play-learn-lift/](../play-learn-lift/) — The full methodology

---

undefined

**Example from adventure skill:**

The adventure skill's vision includes a Python CLI that handles deterministic operations:

```python
$ adventure lint examples/adventure-4/    # Validate world
$ adventure move alice north              # Update coordinates  
$ adventure scan --pending                # Find work to do

undefined

**From [examples/adventure-4/LINTER.yml](../../examples/adventure-4/LINTER.yml):**

```yaml
summary:
  rooms_found: 36
  objects_found: 37
  characters_found: 6
  errors: 8
  warnings: 36
  compile_requests: 9

events:
- type: FOUND_ROOM
  severity: INFO
  path: pub/ROOM.yml
  message: 'Found room: The Gezelligheid Grotto'
  data:
    exits: [NORTH, UP, BACK]
    objects: 15
    sub_rooms: 1

abilities:
  COMPASS:
    description: "Point toward a target"
    usage: "COMPASS [target]"
    targets:
      - start     # Always knows home
      - home      # The surface
      - treasure  # The goal

framing:
  mode: [performance, celebration, socialization, tribute, third_place]
  
  description: |
    This is a PLACE OF PERFORMANCE AND CELEBRATION.
    This is a THIRD PLACE — neither home nor work, but community.
    This is where TRIBUTES are performed with love.

> enter the adventure skill
You are in the Adventure Workshop.
Exits: pub, maze, character-gallery
Objects: room-templates, npc-catalog, puzzle-designs

undefined

The LLM discovers the tool's capabilities by reading its structure, not by loading documentation. One quick sniff and it knows what's cooking.

---

def _helper():
    ...
def _another_helper():
    ...

❌ **No docstrings**
```python
@click.command()
def process(x, y, z):
    # What does this do? What are x, y, z?

if retries > 3:  # Why 3? What happens at 4?

import os
def foo():
    import json  # Hidden dependency

> SNIFF CODE src/api/handler.ts

Sniffability Report for handler.ts:
✓ Purpose clear from first 10 lines
✓ Exports/API visible before implementation  
✗ Magic number on line 47 — needs comment
✗ Helper function before main export — reorder
✓ Semantic comments explain WHY not WHAT

Overall: Mostly fresh, minor reordering needed

SNIFFABLE-PYTHON

undefined

| Skill | Relationship to Sniffable Python |
|-------|----------------------------------|
| [sister-script/](../sister-script/) | Sister scripts ARE sniffable Python |
| [skill/](../skill/) | Skills generate sniffable scripts |
| [yaml-jazz/](../yaml-jazz/) | Comments carry semantic meaning |
| [play-learn-lift/](../play-learn-lift/) | Sniffable Python is LIFT output |
| [constructionism/](../constructionism/) | Build inspectable things |
| [adventure/](../adventure/) | Linter exemplifies the feedback loop |
| [session-log/](../session-log/) | Raw exploration → procedures → scripts |
| [research-notebook/](../research-notebook/) | Documented patterns become scripts |

PLAY: Try things, log them
  ↓
LEARN: Document patterns in PROCEDURE.md
  ↓
LIFT: Generate sister-script.py in SNIFFABLE PYTHON format
  ↓
SKILL: Add to skill, expose to LLM
  ↓
LLM: Sniffs script, understands API, uses tool
  ↓
OUTPUT: YAML results (linter, builder, etc.)
  ↓
PLAY: Try new things with the tool...
  ↓
[repeat]

// ✓ Sniffable TypeScript
/**
 * User authentication service.
 * @module auth
 */

export interface AuthConfig { ... }
export function authenticate(config: AuthConfig): Promise<User> { ... }
export function logout(): void { ... }

// Implementation details below
function validateToken(token: string): boolean { ... }