Template Skill

System Prompt Additions

When this skill is active, add these guidelines to the LLM context:

# Template Skill Guidelines

When working with the Template skill:

- Use `template.example` for basic operations
- Use `template.process_data` for data processing tasks
- All commands are defined in `scripts/commands.py`
- No tools.py needed - this is the single source of truth

Trinity Architecture v2.0 Context

This skill operates within the Trinity Architecture v2.0 with scripts/commands.py pattern:

_template/
├── SKILL.md           # Metadata + System Prompts
├── scripts/           # Commands (v2.0+)
│   ├── __init__.py    # Dynamic module loader (importlib.util)
│   └── commands.py    # registered command functions
└── tests/             # Test files

Component	Description
Code	scripts/commands.py - Hot-reloaded via ModuleLoader
Context	template.help - Full skill context via Repomix XML
State	SKILL.md - Skill metadata in YAML Frontmatter

Why scripts/commands.py Pattern?

The Trinity Architecture v2.0 uses a simplified pattern:

• scripts/commands.py - Command functions registered for runtime discovery
• Single source of truth
• No router-indirection layer
• Easier to understand and maintain
• Hot-reload works directly on commands

ODF-EP Protocol Awareness

All core skill modules follow the "Python Zenith" Engineering Protocol:

Pillar	Implementation in Skills
A: Pydantic Shield	DTOs use ConfigDict(frozen=True)
B: Protocol-Oriented Design	ISkill, ISkillCommand protocols
C: Tenacity Pattern	@retry for resilient I/O operations
D: Context-Aware Observability	logger.bind() for structured logs

Creating a New Skill

Use _template as a scaffold for new skills:

Development Workflow

1. _template/                    # Start: Copy this template
   │
2. scripts/                     # Step 1: COMMANDS (actual logic)
   │
3. tests/                       # Step 2: TESTS (zero-config)
   │
4. README.md                    # Step 3: User documentation
   │
5. SKILL.md                     # Step 4: LLM context & manifest

Step 1: Copy Template

cp -r assets/skills/_template assets/skills/my_new_skill

Step 2: Add Commands (scripts/commands.py)

from xiuxian_foundation.api.decorators import skill_command

@skill_command(
    name="my_command",
    category="read",
    description="Brief description",
)
async def my_command(param: str) -> str:
    """Detailed docstring."""
    return f"Result: {param}"

Note: Command name is just my_command, not my_new_skill.my_command. The skill runtime applies the skill namespace during registration.

Step 3: Add Tests (tests/test_*.py)

def test_my_command_exists():
    from skills.my_new_skill.scripts import commands
    assert hasattr(commands, "my_command")

Step 4: Update Documentation (README.md)

Add usage examples and command reference.

Step 5: Update Manifest (SKILL.md)

Edit the frontmatter:

---
name: my_new_skill
version: 1.0.0
description: My new skill description
routing_keywords: ["keyword1", "keyword2"]
permissions: [] # Zero Trust: declare required capabilities
---

Permission Format: "category:action" (e.g., "filesystem:read", "network:http")

Step 6: (Optional) Subprocess Mode - Sidecar Execution Pattern

For heavy/conflicting dependencies (e.g., crawl4ai, playwright), use the Sidecar Pattern:

assets/skills/my_skill/
├── pyproject.toml        # Skill dependencies (uv isolation)
└── scripts/
    ├── __init__.py       # Module loader
    └── engine.py         # Heavy implementation (imports OK here!)

Step A: Create pyproject.toml (copied from _template/pyproject.toml)

Step B: Write scripts/engine.py (heavy imports allowed!)

# scripts/engine.py - Heavy implementation
import json
from heavy_lib import do_work  # This works!

def main(param: str):
    result = do_work(param)
    # Print JSON to stdout for the shim to capture
    print(json.dumps({"success": True, "result": result}))

if __name__ == "__main__":
    import sys
    main(sys.argv[1] if sys.argv[1:] else "")

Step C: Write scripts/__init__.py (lightweight shim)

# scripts/__init__.py - Lightweight loader
import importlib.util
from pathlib import Path
import subprocess
import json

_scripts_dir = Path(__file__).parent

def run_engine(param: str) -> dict:
    """Run engine.py as subprocess."""
    engine_path = _scripts_dir / "engine.py"
    result = subprocess.run(
        ["python", str(engine_path), param],
        capture_output=True,
        text=True,
        timeout=60,
    )
    return json.loads(result.stdout)

Why This Pattern?

Layer	What	Why
scripts/__init__.py	Lightweight loader	Main agent stays clean
scripts/engine.py	Heavy implementation	Can import anything
pyproject.toml	Dependencies	uv manages isolation

Quick Reference

Command	Category	Description
template.example	read	Example command
template.example_with_options	read	Example with options
template.process_data	write	Process data strings
template.help	view	Show full skill context

Related Documentation

• Skills Documentation - Comprehensive guide
• Trinity Architecture
• ODF-EP Planning Prompt