1#!/usr/bin/env python3
2"""
3Skill Initializer - Creates a new skill from template
4 
5Usage:
6    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]
7 
8Examples:
9    python init_skill.py my-new-skill --path ./workspace/skills
10    python init_skill.py api-helper --path ./workspace/skills --resources scripts,references
11    python init_skill.py custom-skill --path ./workspace/skills --resources scripts --examples
12"""
13 
14import argparse
15import re
16import sys
17from pathlib import Path
18 
19MAX_SKILL_NAME_LENGTH = 64
20ALLOWED_RESOURCES = {"scripts", "references", "assets"}
21 
22SKILL_TEMPLATE = """---
23name: {skill_name}
24description: "[TODO: What this skill does. Use when <specific trigger scenarios>.]"
25 
26metadata:
27  starchild:
28    emoji:
29    skillKey: {skill_name}
30    requires:
31      env: []
32      bins: []
33 
34user-invocable: true
35---
36 
37# {skill_title}
38 
39[TODO: 1-2 sentences in direct voice. "You do X" not "This skill does X."
40Explain what capability this gives the agent and why it matters.]
41 
42## Structuring This Skill
43 
44Pick the pattern that fits best, then delete this section:
45 
46- **Workflow-based** — Step-by-step process (fetch data -> process -> render -> output)
47- **Task-based** — Organized by user request ("analyze X" / "compare Y" / "generate Z")
48- **Reference/guidelines** — Rules, decision frameworks, core truths
49- **Capabilities-based** — Organized by what the skill can do (tool group A / tool group B)
50 
51## [TODO: Main Section]
52 
53[TODO: Core instructions the agent needs every time this skill activates.
54Focus on knowledge the agent doesn't already have:
55- Domain-specific interpretation guides
56- Decision trees ("when X, do Y; when Z, do W")
57- Gotchas and edge cases
58- Key parameters and thresholds]
59 
60## Resources
61 
62[TODO: Document scripts/, references/, assets/ if used.
63Delete this section if no resource directories exist.]
64"""
65 
66EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
67"""
68{skill_title} - Helper Script
69 
70Usage:
71    python scripts/example.py --input <path> [--output <path>]
72 
73This script handles [TODO: describe what this automates].
74Scripts are for low-freedom operations: fragile API calls, exact rendering,
75repetitive boilerplate. The agent executes these via bash, not by reading
76them into context.
77"""
78 
79import argparse
80import json
81import sys
82 
83 
84def main():
85    parser = argparse.ArgumentParser(description="{skill_title} helper")
86    parser.add_argument("--input", required=True, help="Input file path")
87    parser.add_argument("--output", default=None, help="Output file path (default: stdout)")
88    args = parser.parse_args()
89 
90    # TODO: Replace with actual implementation
91    print(f"Processing: {{args.input}}")
92 
93    result = {{"status": "ok", "input": args.input}}
94 
95    if args.output:
96        with open(args.output, "w") as f:
97            json.dump(result, f, indent=2)
98        print(f"Output written to: {{args.output}}")
99    else:
100        print(json.dumps(result, indent=2))
101 
102 
103if __name__ == "__main__":
104    main()
105'''
106 
107EXAMPLE_REFERENCE = """# {skill_title} — Reference Documentation
108 
109This reference is loaded on demand via `read_file` when the agent needs
110detailed information beyond what's in the main SKILL.md.
111 
112## When to Load This Reference
113 
114- Agent needs full API endpoint details
115- Agent needs to look up error codes or schema definitions
116- Complex multi-step process requires detailed walkthrough
117 
118## API Reference
119 
120### Authentication
121 
122[TODO: How to authenticate — headers, tokens, env vars]
123 
124### Endpoints
125 
126| Endpoint | Method | Description |
127|----------|--------|-------------|
128| `/api/example` | GET | [TODO: Description] |
129| `/api/example` | POST | [TODO: Description] |
130 
131### Error Codes
132 
133| Code | Meaning | Recovery |
134|------|---------|----------|
135| 401 | Invalid API key | Check env var is set |
136| 429 | Rate limited | Wait and retry (backoff) |
137 
138## Troubleshooting
139 
140[TODO: Common issues and how to resolve them]
141"""
142 
143EXAMPLE_ASSET = """{{
144  "name": "{skill_name}",
145  "version": "1.0",
146  "description": "Template asset for {skill_title}",
147  "TODO": "Replace this with actual asset content (templates, config, data files). Assets are NOT loaded into context — they're used in output generation."
148}}
149"""
150 
151 
152def normalize_skill_name(skill_name: str) -> str:
153    """Normalize skill name to lowercase hyphen-case."""
154    normalized = skill_name.strip().lower()
155    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
156    normalized = normalized.strip("-")
157    normalized = re.sub(r"-{2,}", "-", normalized)
158    return normalized
159 
160 
161def title_case_skill_name(skill_name: str) -> str:
162    """Convert hyphenated skill name to Title Case."""
163    return " ".join(word.capitalize() for word in skill_name.split("-"))
164 
165 
166def parse_resources(raw_resources: str) -> list:
167    if not raw_resources:
168        return []
169    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
170    invalid = [item for item in resources if item not in ALLOWED_RESOURCES]
171    if invalid:
172        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
173        print(f"   Allowed: {', '.join(sorted(ALLOWED_RESOURCES))}")
174        sys.exit(1)
175    return list(dict.fromkeys(resources))  # dedupe while preserving order
176 
177 
178def create_resource_dirs(skill_dir: Path, skill_name: str, skill_title: str,
179                         resources: list, include_examples: bool):
180    for resource in resources:
181        resource_dir = skill_dir / resource
182        resource_dir.mkdir(exist_ok=True)
183 
184        if resource == "scripts":
185            if include_examples:
186                example_script = resource_dir / "example.py"
187                example_script.write_text(EXAMPLE_SCRIPT.format(
188                    skill_name=skill_name, skill_title=skill_title))
189                example_script.chmod(0o755)
190                print(f"[OK] Created {resource}/example.py")
191            else:
192                print(f"[OK] Created {resource}/")
193 
194        elif resource == "references":
195            if include_examples:
196                example_ref = resource_dir / "reference.md"
197                example_ref.write_text(EXAMPLE_REFERENCE.format(
198                    skill_name=skill_name, skill_title=skill_title))
199                print(f"[OK] Created {resource}/reference.md")
200            else:
201                print(f"[OK] Created {resource}/")
202 
203        elif resource == "assets":
204            if include_examples:
205                example_asset = resource_dir / "template.json"
206                example_asset.write_text(EXAMPLE_ASSET.format(
207                    skill_name=skill_name, skill_title=skill_title))
208                print(f"[OK] Created {resource}/template.json")
209            else:
210                print(f"[OK] Created {resource}/")
211 
212 
213def init_skill(skill_name: str, path: str, resources: list, include_examples: bool) -> Path:
214    """
215    Initialize a new skill directory with template SKILL.md.
216 
217    Returns:
218        Path to created skill directory, or None if error
219    """
220    skill_dir = Path(path).resolve() / skill_name
221 
222    if skill_dir.exists():
223        print(f"[ERROR] Skill directory already exists: {skill_dir}")
224        return None
225 
226    try:
227        skill_dir.mkdir(parents=True, exist_ok=False)
228        print(f"[OK] Created skill directory: {skill_dir}")
229    except Exception as e:
230        print(f"[ERROR] Error creating directory: {e}")
231        return None
232 
233    # Create SKILL.md
234    skill_title = title_case_skill_name(skill_name)
235    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
236 
237    skill_md_path = skill_dir / "SKILL.md"
238    try:
239        skill_md_path.write_text(skill_content)
240        print("[OK] Created SKILL.md")
241    except Exception as e:
242        print(f"[ERROR] Error creating SKILL.md: {e}")
243        return None
244 
245    # Create resource directories
246    if resources:
247        try:
248            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)
249        except Exception as e:
250            print(f"[ERROR] Error creating resource directories: {e}")
251            return None
252 
253    print(f"\n[OK] Skill '{skill_name}' initialized at {skill_dir}")
254    print("\nNext steps:")
255    print("1. Edit SKILL.md — complete the TODOs, write a strong description")
256    print("2. Add resources to scripts/, references/, assets/ as needed")
257    print("3. Run validate_skill.py to check for issues")
258    print("4. Call skill_refresh() to make the skill available")
259 
260    return skill_dir
261 
262 
263def main():
264    parser = argparse.ArgumentParser(
265        description="Create a new skill directory with SKILL.md template."
266    )
267    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
268    parser.add_argument("--path", required=True, help="Output directory for the skill")
269    parser.add_argument(
270        "--resources",
271        default="",
272        help="Comma-separated list: scripts,references,assets"
273    )
274    parser.add_argument(
275        "--examples",
276        action="store_true",
277        help="Create example files in resource directories"
278    )
279    args = parser.parse_args()
280 
281    raw_name = args.skill_name
282    skill_name = normalize_skill_name(raw_name)
283 
284    if not skill_name:
285        print("[ERROR] Skill name must include at least one letter or digit.")
286        sys.exit(1)
287 
288    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
289        print(f"[ERROR] Skill name too long ({len(skill_name)} > {MAX_SKILL_NAME_LENGTH})")
290        sys.exit(1)
291 
292    if skill_name != raw_name:
293        print(f"Note: Normalized '{raw_name}' to '{skill_name}'")
294 
295    resources = parse_resources(args.resources)
296 
297    if args.examples and not resources:
298        print("[ERROR] --examples requires --resources to be set")
299        sys.exit(1)
300 
301    print(f"Initializing skill: {skill_name}")
302    print(f"   Location: {args.path}")
303    if resources:
304        print(f"   Resources: {', '.join(resources)}")
305    print()
306 
307    result = init_skill(skill_name, args.path, resources, args.examples)
308    sys.exit(0 if result else 1)
309 
310 
311if __name__ == "__main__":
312    main()
313