# Commands > Imported skill commands from langchain Use when this capability is needed. - Skill: `tomevault-io/commands` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/commands` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/commands/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/commands --- """CLI commands for skill management. These commands are registered with the CLI via cli.py: - deepagents skills list --agent [--project] - deepagents skills create - deepagents skills info """ import argparse import re from pathlib import Path from typing import Any from deepagents_cli.config import COLORS, Settings, console from deepagents_cli.skills.load import list_skills MAX_SKILL_NAME_LENGTH = 64 def _validate_name(name: str) -> tuple[bool, str]: """Validate name per Agent Skills spec. Requirements (https://agentskills.io/specification): - Max 64 characters - Lowercase alphanumeric and hyphens only (a-z, 0-9, -) - Cannot start or end with hyphen - No consecutive hyphens - No path traversal sequences Args: name: The name to validate Returns: Tuple of (is_valid, error_message). If valid, error_message is empty. """ # Check for empty or whitespace-only names if not name or not name.strip(): return False, "cannot be empty" # Check length (spec: max 64 chars) if len(name) > MAX_SKILL_NAME_LENGTH: return False, "cannot exceed 64 characters" # Check for path traversal sequences if ".." in name or "/" in name or "\\" in name: return False, "cannot contain path components" # Spec: lowercase alphanumeric and hyphens only # Pattern ensures: no start/end hyphen, no consecutive hyphens if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name): return ( False, "must be lowercase letters, numbers, and hyphens only " "(no uppercase, no underscores, cannot start/end with hyphen)", ) return True, "" def _validate_skill_path(skill_dir: Path, base_dir: Path) -> tuple[bool, str]: """Validate that the resolved skill directory is within the base directory. Args: skill_dir: The skill directory path to validate base_dir: The base skills directory that should contain skill_dir Returns: Tuple of (is_valid, error_message). If valid, error_message is empty. """ try: # Resolve both paths to their canonical form resolved_skill = skill_dir.resolve() resolved_base = base_dir.resolve() # Check if skill_dir is within base_dir # Use is_relative_to if available (Python 3.9+), otherwise use string comparison if hasattr(resolved_skill, "is_relative_to"): if not resolved_skill.is_relative_to(resolved_base): return False, f"Skill directory must be within {base_dir}" else: # Fallback for older Python versions try: resolved_skill.relative_to(resolved_base) except ValueError: return False, f"Skill directory must be within {base_dir}" return True, "" except (OSError, RuntimeError) as e: return False, f"Invalid path: {e}" def _list(agent: str, *, project: bool = False) -> None: """List all available skills for the specified agent. Args: agent: Agent identifier for skills (default: agent). project: If True, show only project skills. If False, show all skills (user + project). """ settings = Settings.from_environment() user_skills_dir = settings.get_user_skills_dir(agent) project_skills_dir = settings.get_project_skills_dir() # If --project flag is used, only show project skills if project: if not project_skills_dir: console.print("[yellow]Not in a project directory.[/yellow]") console.print( "[dim]Project skills require a .git directory in the project root.[/dim]", style=COLORS["dim"], ) return if not project_skills_dir.exists() or not any(project_skills_dir.iterdir()): console.print("[yellow]No project skills found.[/yellow]") console.print( f"[dim]Project skills will be created in {project_skills_dir}/ when you add them.[/dim]", style=COLORS["dim"], ) console.print( "\n[dim]Create a project skill:\n deepagents skills create my-skill --project[/dim]", style=COLORS["dim"], ) return skills = list_skills(user_skills_dir=None, project_skills_dir=project_skills_dir) console.print("\n[bold]Project Skills:[/bold]\n", style=COLORS["primary"]) else: # Load both user and project skills skills = list_skills(user_skills_dir=user_skills_dir, project_skills_dir=project_skills_dir) if not skills: console.print("[yellow]No skills found.[/yellow]") console.print( "[dim]Skills will be created in ~/.deepagents/agent/skills/ when you add them.[/dim]", style=COLORS["dim"], ) console.print( "\n[dim]Create your first skill:\n deepagents skills create my-skill[/dim]", style=COLORS["dim"], ) return console.print("\n[bold]Available Skills:[/bold]\n", style=COLORS["primary"]) # Group skills by source user_skills = [s for s in skills if s["source"] == "user"] project_skills_list = [s for s in skills if s["source"] == "project"] # Show user skills if user_skills and not project: console.print("[bold cyan]User Skills:[/bold cyan]", style=COLORS["primary"]) for skill in user_skills: skill_path = Path(skill["path"]) console.print(f" • [bold]{skill['name']}[/bold]", style=COLORS["primary"]) console.print(f" {skill['description']}", style=COLORS["dim"]) console.print(f" Location: {skill_path.parent}/", style=COLORS["dim"]) console.print() # Show project skills if project_skills_list: if not project and user_skills: console.print() console.print("[bold green]Project Skills:[/bold green]", style=COLORS["primary"]) for skill in project_skills_list: skill_path = Path(skill["path"]) console.print(f" • [bold]{skill['name']}[/bold]", style=COLORS["primary"]) console.print(f" {skill['description']}", style=COLORS["dim"]) console.print(f" Location: {skill_path.parent}/", style=COLORS["dim"]) console.print() def _create(skill_name: str, agent: str, project: bool = False) -> None: """Create a new skill with a template SKILL.md file. Args: skill_name: Name of the skill to create. agent: Agent identifier for skills project: If True, create in project skills directory. If False, create in user skills directory. """ # Validate skill name first (per Agent Skills spec) is_valid, error_msg = _validate_name(skill_name) if not is_valid: console.print(f"[bold red]Error:[/bold red] Invalid skill name: {error_msg}") console.print( "[dim]Per Agent Skills spec: names must be lowercase alphanumeric with hyphens only.\n" "Examples: web-research, code-review, data-analysis[/dim]", style=COLORS["dim"], ) return # Determine target directory settings = Settings.from_environment() if project: if not settings.project_root: console.print("[bold red]Error:[/bold red] Not in a project directory.") console.print( "[dim]Project skills require a .git directory in the project root.[/dim]", style=COLORS["dim"], ) return skills_dir = settings.ensure_project_skills_dir() else: skills_dir = settings.ensure_user_skills_dir(agent) skill_dir = skills_dir / skill_name # Validate the resolved path is within skills_dir is_valid_path, path_error = _validate_skill_path(skill_dir, skills_dir) if not is_valid_path: console.print(f"[bold red]Error:[/bold red] {path_error}") return if skill_dir.exists(): console.print( f"[bold red]Error:[/bold red] Skill '{skill_name}' already exists at {skill_dir}" ) return # Create skill directory skill_dir.mkdir(parents=True, exist_ok=True) # Create template SKILL.md (per Agent Skills spec: https://agentskills.io/specification) template = f"""--- name: {skill_name} description: Brief description of what this skill does and when to use it. # Optional fields per Agent Skills spec: # license: Apache-2.0 # compatibility: Designed for deepagents CLI # metadata: # author: your-org # version: "1.0" # allowed-tools: Bash(git:*) Read --- # {skill_name.title().replace("-", " ")} Skill ## Description [Provide a detailed explanation of what this skill does and when it should be used] ## When to Use - [Scenario 1: When the user asks...] - [Scenario 2: When you need to...] - [Scenario 3: When the task involves...] ## How to Use ### Step 1: [First Action] [Explain what to do first] ### Step 2: [Second Action] [Explain what to do next] ### Step 3: [Final Action] [Explain how to complete the task] ## Best Practices - [Best practice 1] - [Best practice 2] - [Best practice 3] ## Supporting Files This skill directory can include supporting files referenced in the instructions: - `helper.py` - Python scripts for automation - `config.json` - Configuration files - `reference.md` - Additional reference documentation ## Examples ### Example 1: [Scenario Name] **User Request:** "[Example user request]" **Approach:** 1. [Step-by-step breakdown] 2. [Using tools and commands] 3. [Expected outcome] ### Example 2: [Another Scenario] **User Request:** "[Another example]" **Approach:** 1. [Different approach] 2. [Relevant commands] 3. [Expected result] ## Notes - [Additional tips, warnings, or context] - [Known limitations or edge cases] - [Links to external resources if helpful] """ skill_md = skill_dir / "SKILL.md" skill_md.write_text(template) console.print(f"✓ Skill '{skill_name}' created successfully!", style=COLORS["primary"]) console.print(f"Location: {skill_dir}\n", style=COLORS["dim"]) console.print( "[dim]Edit the SKILL.md file to customize:\n" " 1. Update the description in YAML frontmatter\n" " 2. Fill in the instructions and examples\n" " 3. Add any supporting files (scripts, configs, etc.)\n" "\n" f" nano {skill_md}\n" "\n" "💡 See examples/skills/ in the deepagents repo for example skills:\n" " - web-research: Structured research workflow\n" " - langgraph-docs: LangGraph documentation lookup\n" "\n" " Copy an example: cp -r examples/skills/web-research ~/.deepagents/agent/skills/\n", style=COLORS["dim"], ) def _info(skill_name: str, *, agent: str = "agent", project: bool = False) -> None: """Show detailed information about a specific skill. Args: skill_name: Name of the skill to show info for. agent: Agent identifier for skills (default: agent). project: If True, only search in project skills. If False, search in both user and project skills. """ settings = Settings.from_environment() user_skills_dir = settings.get_user_skills_dir(agent) project_skills_dir = settings.get_project_skills_dir() # Load skills based on --project flag if project: if not project_skills_dir: console.print("[bold red]Error:[/bold red] Not in a project directory.") return skills = list_skills(user_skills_dir=None, project_skills_dir=project_skills_dir) else: skills = list_skills(user_skills_dir=user_skills_dir, project_skills_dir=project_skills_dir) # Find the skill skill = next((s for s in skills if s["name"] == skill_name), None) if not skill: console.print(f"[bold red]Error:[/bold red] Skill '{skill_name}' not found.") console.print("\n[dim]Available skills:[/dim]", style=COLORS["dim"]) for s in skills: console.print(f" - {s['name']}", style=COLORS["dim"]) return # Read the full SKILL.md file skill_path = Path(skill["path"]) skill_content = skill_path.read_text() # Determine source label source_label = "Project Skill" if skill["source"] == "project" else "User Skill" source_color = "green" if skill["source"] == "project" else "cyan" console.print( f"\n[bold]Skill: {skill['name']}[/bold] [bold {source_color}]({source_label})[/bold {source_color}]\n", style=COLORS["primary"], ) console.print(f"[bold]Description:[/bold] {skill['description']}\n", style=COLORS["dim"]) console.print(f"[bold]Location:[/bold] {skill_path.parent}/\n", style=COLORS["dim"]) # List supporting files skill_dir = skill_path.parent supporting_files = [f for f in skill_dir.iterdir() if f.name != "SKILL.md"] if supporting_files: console.print("[bold]Supporting Files:[/bold]", style=COLORS["dim"]) for file in supporting_files: console.print(f" - {file.name}", style=COLORS["dim"]) console.print() # Show the full SKILL.md content console.print("[bold]Full SKILL.md Content:[/bold]\n", style=COLORS["primary"]) console.print(skill_content, style=COLORS["dim"]) console.print() def setup_skills_parser( subparsers: Any, ) -> argparse.ArgumentParser: """Setup the skills subcommand parser with all its subcommands.""" skills_parser = subparsers.add_parser( "skills", help="Manage agent skills", description="Manage agent skills - create, list, and view skill information", ) skills_subparsers = skills_parser.add_subparsers(dest="skills_command", help="Skills command") # Skills list list_parser = skills_subparsers.add_parser( "list", help="List all available skills", description="List all available skills" ) list_parser.add_argument( "--agent", default="agent", help="Agent identifier for skills (default: agent)", ) list_parser.add_argument( "--project", action="store_true", help="Show only project-level skills", ) # Skills create create_parser = skills_subparsers.add_parser( "create", help="Create a new skill", description="Create a new skill with a template SKILL.md file", ) create_parser.add_argument("name", help="Name of the skill to create (e.g., web-research)") create_parser.add_argument( "--agent", default="agent", help="Agent identifier for skills (default: agent)", ) create_parser.add_argument( "--project", action="store_true", help="Create skill in project directory instead of user directory", ) # Skills info info_parser = skills_subparsers.add_parser( "info", help="Show detailed information about a skill", description="Show detailed information about a specific skill", ) info_parser.add_argument("name", help="Name of the skill to show info for") info_parser.add_argument( "--agent", default="agent", help="Agent identifier for skills (default: agent)", ) info_parser.add_argument( "--project", action="store_true", help="Search only in project skills", ) return skills_parser def execute_skills_command(args: argparse.Namespace) -> None: """Execute skills subcommands based on parsed arguments. Args: args: Parsed command line arguments with skills_command attribute """ # validate agent argument if args.agent: is_valid, error_msg = _validate_name(args.agent) if not is_valid: console.print(f"[bold red]Error:[/bold red] Invalid agent name: {error_msg}") console.print( "[dim]Agent names must only contain letters, numbers, hyphens, and underscores.[/dim]", style=COLORS["dim"], ) return if args.skills_command == "list": _list(agent=args.agent, project=args.project) elif args.skills_command == "create": _create(args.name, agent=args.agent, project=args.project) elif args.skills_command == "info": _info(args.name, agent=args.agent, project=args.project) else: # No subcommand provided, show help console.print("[yellow]Please specify a skills subcommand: list, create, or info[/yellow]") console.print("\n[bold]Usage:[/bold]", style=COLORS["primary"]) console.print(" deepagents skills [options]\n") console.print("[bold]Available commands:[/bold]", style=COLORS["primary"]) console.print(" list List all available skills") console.print(" create Create a new skill") console.print(" info Show detailed information about a skill") console.print("\n[bold]Examples:[/bold]", style=COLORS["primary"]) console.print(" deepagents skills list") console.print(" deepagents skills create web-research") console.print(" deepagents skills info web-research") console.print("\n[dim]For more help on a specific command:[/dim]", style=COLORS["dim"]) console.print(" deepagents skills --help", style=COLORS["dim"]) __all__ = [ "execute_skills_command", "setup_skills_parser", ] --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/bitwikiorg) — claim your Tome and manage your conversions.