Documentation

Complete command reference for AI Skills Manager

← Back to Home

Built on Best Practices

AI Skills Manager implements the Agent Skills specification. Each command follows the documented structure and best practices from Anthropic, providing a solid foundation for your Agent skills.

Commands

asm scaffold Create a new skill
asm validate Validate a skill
asm package Create a distributable package
asm install Install a skill
asm update Update an installed skill
asm uninstall Remove a skill
asm list List installed skills
Programmatic API Node.js module usage
Debug Mode Enable verbose logging

`asm scaffold`

Create a new Claude Code skill with the required directory structure and SKILL.md template.

Syntax

asm scaffold <name> [options]

Options

Option	Description
`-d, --description <text>`	Description for the skill (appears in frontmatter)
`-o, --output <dir>`	Custom output directory (default: .claude/skills/)
`-s, --scope <scope>`	Installation scope: "project" or "personal"
`-t, --allowed-tools <tools>`	Comma-separated list of allowed tools
`-f, --force`	Overwrite existing directory if it exists
`--template <type>`	Template variant: basic, forked, with-hooks, internal (default: basic)
`--interactive, -i`	Launch guided prompt-driven scaffold workflow
`--minimal`	Generate shorter, production-ready template without guidance text
`--context <mode>`	Set context mode in frontmatter (e.g., "fork")
`--agent <name>`	Set agent name in frontmatter
`--no-user-invocable`	Mark skill as non-user-invocable (internal helper)
`--hooks`	Include hook configuration examples in template
`--argument-hint <hint>`	Set argument hint for the skill
`--license <text>`	Set license identifier in frontmatter (e.g., MIT, Apache-2.0)
`--compatibility <text>`	Set compatibility requirements (e.g., claude-code>=2.1), max 500 chars
`--metadata <key=value>`	Add metadata key-value pair to frontmatter (repeatable)

Examples

Create a basic skill

asm scaffold code-reviewer

Create with description and custom tools

                        asm scaffold test-helper --description "Helps write unit tests" --allowed-tools "Read,Write,Bash"
                    

Create a personal skill

asm scaffold my-workflow --scope personal

Create with spec fields

asm scaffold my-tool --license MIT --compatibility "claude-code>=2.1"

Create with custom metadata

asm scaffold my-tool --metadata category=testing --metadata priority=high

Interactive scaffold mode

asm scaffold my-skill --interactive

Minimal production template

asm scaffold deploy-helper --template with-hooks --minimal

Note: Skill names must be lowercase, use hyphens for separation, and be no longer than 64 characters. Reserved words like "claude" or "anthropic" are not allowed.

`asm validate`

Validate a skill against the Agent Skills specification, checking structure, frontmatter, and required fields.

Syntax

asm validate <path> [options]

Options

Option	Description
`-q, --quiet`	Only output pass/fail result
`-o, --output <format>`	Output format: "text" or "json"

Validation Checks

SKILL.md file exists
Valid YAML frontmatter structure
Required fields present (name, description)
Only allowed properties in frontmatter
Name format validation
Description format validation
Frontmatter schema v2 field validation (context, agent, hooks, license, compatibility, metadata, etc.)
Advanced allowed-tools pattern validation (Task(AgentName), mcp__server__*, Bash(git:*))
YAML-style list format support for allowed-tools

Examples

Validate a project skill

asm validate .claude/skills/my-skill

JSON output for CI/CD

asm validate .claude/skills/my-skill --output json

Exit Codes

0Skill is valid 1Skill is invalid

`asm package`

Create a distributable .skill package file (ZIP archive) for sharing skills.

Syntax

asm package <path> [options]

Options

Option	Description
`-o, --output <dir>`	Output directory for the package file
`--skip-validation`	Skip pre-packaging validation
`-f, --force`	Overwrite existing package file

Examples

Package a skill

asm package .claude/skills/my-skill

Package to a specific directory

asm package .claude/skills/my-skill --output ./dist

Exit Codes

0Package created successfully 1Validation failed 2File system error 3Package error

Note: Development artifacts like .git, node_modules, and .DS_Store are automatically excluded from packages.

`asm install`

Install a skill from a .skill package file with automatic validation and rollback on failure.

Syntax

asm install <file> [options]

Options

Option	Description
`-s, --scope <scope>`	Installation scope: "project", "personal", or a custom path
`-f, --force`	Overwrite existing skill without prompting
`--dry-run`	Preview installation without making changes
`--content-hash`	Use content hashing for thorough file comparison

Examples

Install to project scope

asm install my-skill.skill --scope project

Install to personal skills

asm install my-skill.skill --scope personal

Preview installation

asm install my-skill.skill --dry-run

Exit Codes

0Installation successful 1Validation failed 2File system error 3Extraction error 4User cancelled

`asm update`

Update an existing skill to a newer version with automatic backups and atomic updates.

Syntax

asm update <name> <file> [options]

Options

Option	Description
`-s, --scope <scope>`	Scope of the installed skill: "project" or "personal"
`-f, --force`	Skip confirmation prompt
`--dry-run`	Preview update without making changes
`--keep-backup`	Preserve backup after successful update

Examples

Update a skill

asm update my-skill ./my-skill-v2.skill

Force update with backup preservation

asm update my-skill ./new-version.skill --force --keep-backup

Exit Codes

0Update successful 1Skill not found 2File system error 3User cancelled 4Invalid package 5Security error 6Rollback succeeded 7Rollback failed

Note: Backups are stored in ~/.asm/backups/ with timestamp naming. On update failure, automatic rollback restores the previous version.

`asm uninstall`

Remove installed skills with security checks and confirmation prompts.

Syntax

asm uninstall <name...> [options]

Options

Option	Description
`-s, --scope <scope>`	Scope to uninstall from: "project" or "personal"
`-f, --force`	Skip confirmation prompt
`--dry-run`	Preview uninstall without making changes

Examples

Uninstall a skill

asm uninstall my-skill --scope project

Bulk uninstall multiple skills

asm uninstall skill-one skill-two skill-three --scope personal

Preview uninstall

asm uninstall my-skill --dry-run

Exit Codes

0Uninstall successful 1Skill not found 2File system error 3User cancelled 4Partial failure (bulk) 5Security error

Security: Uninstall only works with official Claude Code locations (.claude/skills/ and ~/.claude/skills/). Path traversal and symlink attacks are blocked.

`asm list`

List all installed skills across project and personal scopes.

Syntax

asm list [options]

Options

Option	Description
`-s, --scope <scope>`	Filter by scope: "project", "personal", or "all" (default)
`-o, --output <format>`	Output format: "text" or "json"
`--detailed`	Show detailed skill information including description
`--recursive, -r`	Discover skills in nested .claude/skills directories (for monorepos)
`--depth <0-10>`	Limit recursive discovery depth (default: 3)

Examples

List all skills

asm list

List only personal skills

asm list --scope personal

JSON output for scripting

asm list --output json

List skills recursively in a monorepo

asm list --recursive

Limit discovery depth

asm list --recursive --depth 2

Recursive JSON output with metadata

asm list --recursive --output json

Note: When using --recursive, a warning is shown if max depth is reached and subdirectories remain unscanned. JSON output includes depthLimitReached metadata.

Exit Codes

0Success 1No skills found 2File system error

Programmatic API

Use AI Skills Manager as a Node.js module for building GUIs, integrations, and custom tooling. All CLI commands are available as typed functions.

Installation

npm install ai-skills-manager

Import

                    import { scaffold, validate, createPackage, install, update, uninstall, list } from 'ai-skills-manager';
                

Available Functions

Function	Description
`scaffold(options)`	Create a new skill with directory structure
`validate(path, options?)`	Validate a skill against the specification
`createPackage(options)`	Create a distributable .skill package
`install(options)`	Install a skill from a package file
`update(options)`	Update an installed skill
`uninstall(options)`	Remove an installed skill
`list(options?)`	List installed skills

Key Features

Full TypeScript support with complete type definitions for all options and results
Typed error handling with ValidationError, FileSystemError, PackageError, SecurityError, and CancellationError
AbortSignal support for cancelling long-running operations
Dry-run mode available on all write operations
Thin CLI wrapper - the CLI uses this API internally

Example Usage

Validate a skill programmatically

                        const result = await validate('.claude/skills/my-skill');
if (result.valid) {
  console.log('Skill is valid!');
} else {
  console.log('Issues:', result.issues);
}
                    

Install with cancellation support

                        const controller = new AbortController();
const result = await install({
  packagePath: 'my-skill.skill',
  scope: 'project',
  signal: controller.signal
});
                    

Note: The validate() function never throws for validation failures—check result.valid instead. All other functions throw typed errors that can be caught with instanceof checks.

Debug Mode

Enable verbose logging for troubleshooting by setting the ASM_DEBUG environment variable.

Usage

ASM_DEBUG=1 asm <command>

Example

Debug an installation

ASM_DEBUG=1 asm install my-skill.skill --scope project