From f896b654e3386aeb5610009e617e45fee1f079e1 Mon Sep 17 00:00:00 2001 From: yusyus Date: Sun, 15 Feb 2026 14:56:19 +0300 Subject: [PATCH] feat(cli): Phase 3 - Progressive disclosure with better hints and examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improvements: 1. **Better help text formatting:** - Added RawDescriptionHelpFormatter to preserve example formatting - Examples now display cleanly instead of being collapsed 2. **Enhanced epilog with 4 sections:** - Examples: Usage examples for all 5 source types - Source Detection: Clear rules for auto-detection - Need More Options?: Prominent hints for source-specific help - Common Workflows: Quick/standard/comprehensive presets 3. **Implemented progressive disclosure:** - --help-web: Shows universal + web-specific arguments - --help-github: Shows universal + GitHub-specific arguments - --help-local: Shows universal + local-specific arguments - --help-pdf: Shows universal + PDF-specific arguments - --help-advanced: Shows advanced/rare options - --help-all: Shows all 120+ options 4. **Improved discoverability:** - Default help shows 13 universal arguments (clean, focused) - Clear hints guide users to source-specific options - Examples show common patterns for each source type - Workflows section shows preset usage patterns Result: ✅ Much clearer help text with proper formatting ✅ Progressive disclosure reduces cognitive load ✅ Easy to discover source-specific options ✅ Better UX for both beginners and power users ✅ All 46 tests passing Co-Authored-By: Claude Sonnet 4.5 --- src/skill_seekers/cli/create_command.py | 97 ++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/src/skill_seekers/cli/create_command.py b/src/skill_seekers/cli/create_command.py index 25d5699..7b0fe5f 100644 --- a/src/skill_seekers/cli/create_command.py +++ b/src/skill_seekers/cli/create_command.py @@ -380,6 +380,7 @@ def main() -> int: parser = argparse.ArgumentParser( prog='skill-seekers create', description='Create skill from any source (auto-detects type)', + formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" Examples: Web documentation: @@ -401,16 +402,110 @@ Examples: Config file (multi-source): skill-seekers create configs/react.json -Source type is auto-detected. Use --help-web, --help-github, etc. for source-specific options. +Source Detection: + Source type is auto-detected from input: + • URLs (https://... or domain.com) → web scraping + • owner/repo or github.com/... → GitHub analysis + • ./path or /absolute/path → local codebase + • file.pdf → PDF extraction + • file.json → config file (multi-source) + +Need More Options? + The default help shows universal arguments only (13 flags). + For source-specific options, use: + --help-web Web scraping options (max-pages, rate-limit, workers, etc.) + --help-github GitHub options (token, max-issues, no-changelog, etc.) + --help-local Local codebase options (languages, patterns, skip-*, etc.) + --help-pdf PDF extraction options (ocr, pages, etc.) + --help-advanced Advanced/rare options (no-rate-limit, interactive-*, etc.) + --help-all All 120+ options with compatibility matrix + +Common Workflows: + Quick exploration (1-2 min): + skill-seekers create --preset quick + + Production skill (5-10 min): + skill-seekers create --preset standard --enhance-level 2 + + Comprehensive analysis (20-60 min): + skill-seekers create --preset comprehensive --enhance-level 3 + + RAG pipeline ready: + skill-seekers create --chunk-for-rag --chunk-size 512 """ ) # Add arguments in default mode (universal only) add_create_arguments(parser, mode='default') + # Add hidden help mode flags + parser.add_argument('--help-web', action='store_true', help=argparse.SUPPRESS) + parser.add_argument('--help-github', action='store_true', help=argparse.SUPPRESS) + parser.add_argument('--help-local', action='store_true', help=argparse.SUPPRESS) + parser.add_argument('--help-pdf', action='store_true', help=argparse.SUPPRESS) + parser.add_argument('--help-advanced', action='store_true', help=argparse.SUPPRESS) + parser.add_argument('--help-all', action='store_true', help=argparse.SUPPRESS) + # Parse arguments args = parser.parse_args() + # Handle source-specific help modes + if args.help_web: + # Recreate parser with web-specific arguments + parser_web = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill from web documentation', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_web, mode='web') + parser_web.print_help() + return 0 + elif args.help_github: + parser_github = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill from GitHub repository', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_github, mode='github') + parser_github.print_help() + return 0 + elif args.help_local: + parser_local = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill from local codebase', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_local, mode='local') + parser_local.print_help() + return 0 + elif args.help_pdf: + parser_pdf = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill from PDF file', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_pdf, mode='pdf') + parser_pdf.print_help() + return 0 + elif args.help_advanced: + parser_advanced = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill - advanced options', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_advanced, mode='advanced') + parser_advanced.print_help() + return 0 + elif args.help_all: + parser_all = argparse.ArgumentParser( + prog='skill-seekers create', + description='Create skill - all options', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + add_create_arguments(parser_all, mode='all') + parser_all.print_help() + return 0 + # Setup logging log_level = logging.DEBUG if args.verbose else ( logging.WARNING if args.quiet else logging.INFO