@aptove/agentspec

CLI tool for scaffolding AI agent specifications. Create structured specs that AI tools can use to generate deployment artifacts.

Installation

npm install -g @aptove/agentspec

# Or use directly with npx
npx @aptove/agentspec

Quick Start

# Create a new agent spec project
agentspec init my-agent

# Navigate to the project
cd my-agent

# Edit the spec files in specs/
# Then validate your specs
agentspec validate

# When ready, publish to agent-catalog
agentspec publish

Commands

agentspec init [name]

Initialize a new agent spec project with interactive setup.

agentspec init                    # Interactive mode
agentspec init my-agent           # With name
agentspec init -t local-agent     # With template
agentspec init --no-interactive   # Use defaults

Options:

• -t, --template <template> - Template to use (minimal, local-agent, cloud-agent)
• --no-interactive - Skip prompts, use defaults

agentspec validate [path]

Validate agent spec files for completeness and correctness.

agentspec validate           # Validate ./specs
agentspec validate ./path    # Validate specific path
agentspec validate --strict  # Strict mode (all warnings are errors)

Options:

• --strict - Enable strict validation mode

agentspec publish

Publish agent spec to the agent-catalog repository.

agentspec publish            # Interactive publish
agentspec publish --dry-run  # Show what would happen
agentspec publish -y         # Skip confirmation

Options:

• --dry-run - Show what would be published without making changes
• -y, --yes - Skip confirmation prompts

Spec Format

The generated spec structure:

specs/
├── agent.md        # Main agent definition (name, type, protocols)
├── environment.md  # Runtime environment (OS, containers, resources)
├── components.md   # Tools, MCP servers, credentials
├── capabilities.md # What the agent can do
└── generation.md   # Instructions for AI to generate artifacts

AI Markers

Specs use special markers to separate human notes from AI-readable content:

<!-- AI:IGNORE -->
Notes for humans only - AI will skip this
<!-- /AI:IGNORE -->

<!-- AI:CONTEXT -->
Content for AI to read and process
<!-- /AI:CONTEXT -->

Workflow

1. Scaffold - Run agentspec init to create spec structure
2. Customize - Edit spec files manually and with AI assistance
3. Validate - Run agentspec validate to check completeness
4. Generate - Use external AI (Copilot, Gemini, etc.) to generate artifacts
5. Publish - Run agentspec publish to add to agent-catalog

Templates

minimal

Basic structure with minimal content. Good for custom agents.

local-agent

Pre-configured for local development:

• Auto-detects host OS
• Local tool installation
• Development-friendly defaults

cloud-agent

Pre-configured for cloud deployment:

• Container-ready
• Cloud resource specs
• Production defaults

License

MIT