Skill Designer
- 784 installs
- 2.6k repo stars
- Updated August 4, 2026
- tradermonty/claude-trading-skills
Skill Designer is an Agent Skill that converts a structured JSON idea into a Claude CLI prompt that generates a complete compliant skill directory for developers who run automated skill creation pipelines.
About
Skill Designer is an Agent Skill from tradermonty/claude-trading-skills used in skill auto-generation pipelines. Given a structured skill idea specification, it emits a comprehensive Claude CLI prompt instructing Claude to create a full skill directory following repository conventions: SKILL.md with YAML frontmatter, reference documents, helper scripts, and test scaffolding. Developers reach for Skill Designer when a backlog idea is selected and the pipeline needs a prompt that reliably produces convention-compliant skill packages. The skill sits upstream of manual authoring, standardizing how new capabilities enter claude-trading-skills or similar registries without hand-writing every folder layout.
- Converts JSON skill idea specifications into production-ready Claude CLI prompts
- Enforces repository conventions including YAML frontmatter and reference documents
- Produces complete skill directories containing SKILL.md, helper scripts and test scaffolding
- Supports the full skill auto-generation pipeline from backlog idea to reviewed artifact
- Includes built-in awareness of the scoring rubric used during quality review
Skill Designer by the numbers
- 784 all-time installs (skills.sh)
- +90 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #1,341 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/tradermonty/claude-trading-skills --skill skill-designerAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 784 |
|---|---|
| repo stars | ★ 2.6k |
| Last updated | August 4, 2026 |
| Repository | tradermonty/claude-trading-skills ↗ |
How do you auto-generate Agent Skill directories from JSON?
Turn a structured JSON idea into a complete Claude CLI prompt that generates a fully compliant skill directory with SKILL.md, references, scripts and tests.
Who is it for?
Agent skill pipeline maintainers in tradermonty/claude-trading-skills who auto-generate skill directories from structured backlog ideas.
Skip if: Developers who only need to run existing skills or refactor application code without authoring new Agent Skill packages.
When should I use this skill?
The skill auto-generation pipeline selects a backlog idea and needs a Claude CLI prompt to create a complete skill directory with SKILL.md, references, scripts, and tests.
What you get
Claude CLI prompt, SKILL.md with YAML frontmatter, reference docs, helper scripts, and test scaffolding files.
- Claude CLI generation prompt
- SKILL.md scaffold
- Reference docs and test scaffolding
Files
Skill Designer
Overview
Generate a comprehensive Claude CLI prompt from a structured skill idea specification. The prompt instructs Claude to create a complete skill directory following repository conventions: SKILL.md with YAML frontmatter, reference documents, helper scripts, and test scaffolding.
When to Use
- The skill auto-generation pipeline selects an idea from the backlog and needs
a design prompt for claude -p
- A developer wants to bootstrap a new skill from a JSON idea specification
- Quality review of generated skills requires awareness of the scoring rubric
Prerequisites
- Python 3.9+
- No external API keys required
- Reference files must exist under
references/
Workflow
Step 1: Prepare Idea Specification
Accept a JSON file (--idea-json) containing:
title: Human-readable idea namedescription: What the skill doescategory: Skill category (e.g., trading-analysis, developer-tooling)
Accept a normalized skill name (--skill-name) that will be used as the directory name and YAML frontmatter name: field.
Step 2: Build Design Prompt
Run the prompt builder:
python3 skills/skill-designer/scripts/build_design_prompt.py \
--idea-json /tmp/idea.json \
--skill-name "my-new-skill" \
--project-root .The script: 1. Loads the idea JSON 2. Reads all three reference files (structure guide, quality checklist, template) 3. Lists existing skills (up to 20) to prevent duplication 4. Outputs a complete prompt to stdout
Step 3: Feed Prompt to Claude CLI
The calling pipeline pipes the prompt into claude -p:
python3 skills/skill-designer/scripts/build_design_prompt.py \
--idea-json /tmp/idea.json \
--skill-name "my-new-skill" \
--project-root . \
| claude -p --allowedTools Read,Edit,Write,Glob,GrepStep 4: Validate Output
After Claude creates the skill, verify:
skills/<skill-name>/SKILL.mdexists with correct frontmatter- Directory structure follows conventions
- Score with dual-axis-skill-reviewer meets threshold
Output Format
The script outputs a plain-text prompt to stdout. Exit code 0 on success, 1 if required reference files are missing.
Resources
references/skill-structure-guide.md-- Directory structure, SKILL.md format, naming conventionsreferences/quality-checklist.md-- Dual-axis reviewer 5-category checklist (100 points)references/skill-template.md-- SKILL.md template with YAML frontmatter and standard sectionsscripts/build_design_prompt.py-- Prompt builder script (CLI interface)
Skill Quality Checklist
Derived from the dual-axis-skill-reviewer scoring rubric (100 points total).
1. Metadata & Use Case (20 points)
- [ ] YAML frontmatter has
name:matching directory name - [ ]
description:is a clear, concise trigger condition - [ ] "When to Use" section lists specific trigger scenarios
- [ ] "Prerequisites" section documents Python version, API keys, dependencies
- [ ] No ambiguity about when the skill should activate
2. Workflow Coverage (25 points)
- [ ] "Overview" section explains what the skill does (2-3 sentences)
- [ ] "Workflow" has numbered steps with imperative verbs
- [ ] Each step has concrete actions (not vague guidance)
- [ ] Bash command examples use full relative paths
- [ ] "Output Format" section shows JSON/Markdown structure
- [ ] "Resources" section lists all reference files and scripts
3. Execution Safety & Reproducibility (25 points)
- [ ] Bash commands are copy-pasteable (correct paths, flags)
- [ ] Scripts use
--output-dir reports/as default - [ ] No hardcoded absolute paths (use relative or dynamic resolution)
- [ ] API keys read from environment variables first, CLI args as fallback
- [ ] Error handling with proper exit codes documented
- [ ] Date/time stamps in all output files
4. Supporting Artifacts (10 points)
- [ ] At least one reference document in
references/ - [ ] At least one executable script in
scripts/(unless knowledge_only) - [ ] Scripts have
#!/usr/bin/env python3shebang - [ ]
__init__.pynot required (scripts are standalone)
5. Test Health (20 points)
- [ ] Test directory exists:
scripts/tests/ - [ ]
conftest.pywith sys.path setup present - [ ] At least 3 meaningful tests covering core logic
- [ ] Tests use pytest fixtures and tmp_path
- [ ] Tests pass with
python -m pytest scripts/tests/ -v
Threshold Policy
| Score | Status |
|---|---|
| 90+ | Production-ready |
| 80-89 | Usable with targeted improvements |
| 70-79 | Notable gaps; strengthen before regular use |
| <70 | High risk; treat as draft and prioritize fixes |
Knowledge-Only Skills
For skills with no executable scripts but with reference docs:
- Classify as
knowledge_only - Do not penalize missing bash command examples
- Adjust
supporting_artifactsandtest_healthexpectations - Still require clear "When to Use", "Prerequisites", and workflow structure
Skill Structure Guide
Directory Layout
Every skill follows this standardized structure:
<skill-name>/
├── SKILL.md # Required: Skill definition with YAML frontmatter
├── references/ # Knowledge bases loaded into Claude's context
├── scripts/ # Executable Python scripts (not auto-loaded)
│ └── tests/ # Test files for scripts
└── assets/ # Templates and resources for output generationSKILL.md Format
YAML Frontmatter (Required)
---
name: <skill-name>
description: <one-line trigger description>
---nameMUST match the directory name exactlydescriptiondefines when the skill should be triggered; keep it concise
Body Sections (Required)
1. Overview -- What the skill does (2-3 sentences) 2. When to Use -- Bullet list of trigger conditions 3. Prerequisites -- Python version, API keys, dependencies 4. Workflow -- Step-by-step execution instructions (imperative form) 5. Output Format -- JSON and/or Markdown report structure 6. Resources -- List of reference files and scripts
Writing Style
- Use imperative/infinitive verb forms: "Analyze the chart", "Generate report"
- Write instructions for Claude to execute, NOT user instructions
- Avoid "You should..." or "Claude will..." -- state actions directly
- Include concrete bash command examples with full paths
Naming Conventions
- Directory name: lowercase, hyphen-separated (e.g.,
position-sizer) - SKILL.md frontmatter
name:must match directory name - Scripts:
snake_case.py(e.g.,check_data_quality.py) - Reports:
<skill>_<analysis-type>_<date>.{md,json} - Output directory: default to
reports/
Progressive Loading
1. Metadata (YAML frontmatter) loads first for skill detection 2. SKILL.md body loads when skill is invoked 3. References load conditionally based on analysis needs 4. Scripts execute on demand, never auto-loaded into context
Script Requirements
- Check for API keys before making requests
- Validate date ranges and input parameters
- Provide helpful error messages to stderr
- Return proper exit codes (0 success, 1 error)
- Support retry logic with exponential backoff for rate limits
- Use relative paths or dynamic resolution (no hardcoded absolute paths)
- Default
--output-dirtoreports/
Reference Document Patterns
- Use declarative statements of fact
- Include historical examples and case studies where applicable
- Provide decision frameworks and checklists
- Organize hierarchically (H2 for major sections, H3 for subsections)
Analysis Output Requirements
All outputs must:
- Be saved to the
reports/directory - Include date/time stamps
- Use English language
- Provide probability assessments where applicable
- Include specific trigger levels for actionable scenarios
SKILL.md Template
Use this template when creating a new skill's SKILL.md file.
---
name: <skill-name>
description: <One-line description of when to trigger this skill. Be specific about user intent.>
---
# <Skill Display Name>
## Overview
<2-3 sentences describing what the skill does and its primary value.>
## When to Use
- <Specific trigger condition 1>
- <Specific trigger condition 2>
- <Specific trigger condition 3>
## Prerequisites
- Python 3.9+
- <API key requirements or "No API keys required">
- <Any third-party packages or "Standard library only">
## Workflow
### Step 1: <Action Name>
<Description of what to do in this step.>
python3 skills/<skill-name>/scripts/<script_name>.py \ --param1 value1 \ --output-dir reports/
### Step 2: <Action Name>
<Description of what to do in this step.>
### Step 3: <Action Name>
<Description of what to do in this step.>
## Output Format
### JSON Report
{ "schema_version": "1.0", "<key>": "<value>" }
### Markdown Report
<Description of markdown report structure and contents.>
Reports are saved to `reports/` with filenames `<prefix>_YYYY-MM-DD_HHMMSS.{json,md}`.
## Resources
- `scripts/<script_name>.py` -- <Brief description>
- `references/<ref_name>.md` -- <Brief description>
## Key Principles
1. <Principle 1>
2. <Principle 2>
3. <Principle 3>#!/usr/bin/env python3
"""Build a Claude CLI prompt for designing a new skill from an idea specification.
Reads the idea JSON, embeds all three reference files, lists existing skills,
and outputs a complete prompt to stdout.
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
REFERENCES_DIR = Path(__file__).resolve().parent.parent / "references"
REFERENCE_FILES = [
"skill-structure-guide.md",
"quality-checklist.md",
"skill-template.md",
]
MAX_EXISTING_SKILLS = 20
def load_references(refs_dir: Path) -> dict[str, str]:
"""Load all reference files. Returns dict of filename -> content."""
refs = {}
for name in REFERENCE_FILES:
path = refs_dir / name
if path.exists():
refs[name] = path.read_text(encoding="utf-8")
return refs
def list_existing_skills(project_root: Path, limit: int = MAX_EXISTING_SKILLS) -> list[str]:
"""List existing skill directory names (up to limit)."""
skills_dir = project_root / "skills"
if not skills_dir.is_dir():
return []
names = []
for child in sorted(skills_dir.iterdir()):
if child.is_dir() and (child / "SKILL.md").exists():
names.append(child.name)
if len(names) >= limit:
break
return names
def build_prompt(idea: dict, skill_name: str, refs: dict[str, str], existing: list[str]) -> str:
"""Build the complete design prompt."""
title = idea.get("title", "unnamed")
description = idea.get("description", "")
category = idea.get("category", "general")
existing_list = "\n".join(f"- {s}" for s in existing) if existing else "- (none)"
ref_sections = ""
for name, content in refs.items():
ref_sections += f"\n\n--- BEGIN {name} ---\n{content}\n--- END {name} ---"
prompt = f"""Design and create a complete Claude skill named '{skill_name}'.
## Idea Specification
- **Title**: {title}
- **Description**: {description}
- **Category**: {category}
## Requirements
1. Create the skill directory at `skills/{skill_name}/`
2. The YAML frontmatter `name:` field MUST be exactly `{skill_name}`
3. Follow the structure guide, quality checklist, and template below
4. Create all required files:
- `skills/{skill_name}/SKILL.md` (with YAML frontmatter)
- At least one file in `skills/{skill_name}/references/`
- At least one script in `skills/{skill_name}/scripts/` (unless this is a knowledge-only skill)
- Test directory `skills/{skill_name}/scripts/tests/` with conftest.py and at least 3 tests
5. Scripts must use `--output-dir reports/` as default output location
6. Do NOT duplicate functionality of existing skills listed below
7. Use imperative verb forms in SKILL.md workflow steps
8. All scripts must use relative paths (no hardcoded absolute paths)
## Existing Skills (do not duplicate)
{existing_list}
## Reference Documents
{ref_sections}
## Instructions
Create all the files for the skill now. Start with SKILL.md, then references, then scripts, then tests.
Ensure the skill scores well on all 5 quality categories (metadata, workflow, execution safety, artifacts, tests).
"""
return prompt
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Build a Claude CLI prompt for skill design")
parser.add_argument("--idea-json", required=True, help="Path to idea JSON file")
parser.add_argument("--skill-name", required=True, help="Normalized skill directory name")
parser.add_argument("--project-root", default=".", help="Project root directory")
return parser.parse_args()
def main() -> int:
args = parse_args()
project_root = Path(args.project_root).resolve()
# Load idea
idea_path = Path(args.idea_json)
if not idea_path.exists():
print(f"Error: idea JSON not found: {idea_path}", file=sys.stderr)
return 1
idea = json.loads(idea_path.read_text(encoding="utf-8"))
# Load references — all 3 are required (no silent degrade on partial miss)
refs = load_references(REFERENCES_DIR)
missing = [f for f in REFERENCE_FILES if f not in refs]
if missing:
print(
f"Error: reference files missing: {missing}. All 3 are required.",
file=sys.stderr,
)
return 1
# List existing skills
existing = list_existing_skills(project_root)
# Build and output prompt
prompt = build_prompt(idea, args.skill_name, refs, existing)
print(prompt)
return 0
if __name__ == "__main__":
raise SystemExit(main())
"""Test configuration for skill-designer tests."""
import sys
from pathlib import Path
# Add scripts directory to path for imports
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
"""Tests for build_design_prompt.py."""
from __future__ import annotations
from build_design_prompt import REFERENCES_DIR, build_prompt, load_references
def _make_idea(title: str = "test-skill", description: str = "A test skill") -> dict:
return {"title": title, "description": description, "category": "testing"}
def test_build_prompt_uses_skill_name():
"""Prompt uses the --skill-name value for directory and frontmatter name."""
refs = load_references(REFERENCES_DIR)
prompt = build_prompt(_make_idea(), "my-custom-name", refs, [])
assert "skills/my-custom-name/" in prompt
assert "`my-custom-name`" in prompt
assert "name:` field MUST be exactly `my-custom-name`" in prompt
def test_build_prompt_includes_refs():
"""All three reference file contents are embedded in the prompt."""
refs = load_references(REFERENCES_DIR)
# All 3 references should be loaded
assert len(refs) == 3
assert "skill-structure-guide.md" in refs
assert "quality-checklist.md" in refs
assert "skill-template.md" in refs
prompt = build_prompt(_make_idea(), "test-skill", refs, [])
# Each reference content should appear in the prompt
assert "--- BEGIN skill-structure-guide.md ---" in prompt
assert "--- BEGIN quality-checklist.md ---" in prompt
assert "--- BEGIN skill-template.md ---" in prompt
def test_build_prompt_frontmatter_name_matches():
"""Prompt instructs Claude to set name: matching the skill_name."""
refs = load_references(REFERENCES_DIR)
prompt = build_prompt(_make_idea(), "exact-name-here", refs, ["existing-a", "existing-b"])
# Should instruct the frontmatter name to match
assert "exact-name-here" in prompt
# Should list existing skills for deduplication
assert "existing-a" in prompt
assert "existing-b" in prompt
Related skills
Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k
Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k
CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k
Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k
Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72
Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10FAQ
What does Skill Designer output?
Skill Designer outputs a Claude CLI prompt that instructs Claude to create a complete skill directory. Deliverables include SKILL.md with YAML frontmatter, reference documents, helper scripts, and test scaffolding per repository conventions.
When is Skill Designer invoked in the pipeline?
Skill Designer is invoked when the skill auto-generation pipeline picks a structured idea from the backlog and needs a prompt to materialize a full skill package. The skill standardizes directory layout before manual refinement.