@aptove/agentspec

CLI tool for scaffolding and validating AGENTS.md files and Agent Skills.

Installation

npm install -g @aptove/agentspec

# Or use directly with npx
npx @aptove/agentspec

Quick Start

# Scaffold AGENTS.md and a starter skill
agentspec init my-project
cd my-project

# Add more skills
agentspec skill add pdf-processing

# Validate everything
agentspec validate

Commands

agentspec init [name]

Creates an AGENTS.md entry point file and optionally scaffolds a starter skill.

agentspec init                   # Interactive mode
agentspec init my-project        # With project name
agentspec init --no-interactive  # Non-interactive, no starter skill

Output:

my-project/
├── AGENTS.md           # Project-level agent instructions
└── skills/
    └── my-project/
        └── SKILL.md    # Starter skill

---

agentspec skill add <skill-name>

Scaffolds a new skill directory with a valid SKILL.md.

agentspec skill add pdf-processing
agentspec skill add data-analysis

Skill names must follow the Agent Skills naming rules:

• Lowercase letters, numbers, and hyphens only
• No leading, trailing, or consecutive hyphens
• Max 64 characters

Output:

skills/
└── pdf-processing/
    └── SKILL.md

---

agentspec validate [path]

Validates AGENTS.md and all SKILL.md files against their specifications.

agentspec validate                    # Validate current directory
agentspec validate ./skills/my-skill  # Validate a single skill

What is validated:

File	Rules
AGENTS.md	Exists, is valid Markdown
SKILL.md name	1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, matches directory name
SKILL.md description	1–1024 chars, non-empty
SKILL.md compatibility	1–500 chars if provided
SKILL.md metadata	All values must be strings
SKILL.md body	Warning if over 500 lines

Exit code 0 on success, 1 on errors.

---

File Formats

AGENTS.md

Standard Markdown with no required fields. Place it at the root of your project. Add instructions that help AI agents understand your codebase.

# My Project

## Build and Test
npm test

## Code Style
TypeScript, strict mode.

## Skills
Skills live in the `skills/` directory.

SKILL.md

Each skill is a directory containing a SKILL.md with YAML frontmatter:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs.
license: MIT
compatibility: Requires pdfplumber Python package
metadata:
  author: my-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
...

## Instructions
1. ...

Optional directories alongside SKILL.md:

• scripts/ — executable code the agent can run
• references/ — additional documentation loaded on demand
• assets/ — templates, images, data files

---

Workflow

1. Init — agentspec init to create AGENTS.md
2. Add skills — agentspec skill add <name> for each capability
3. Edit — Fill in the instructions in each SKILL.md
4. Validate — agentspec validate to check compliance
5. Reference — Point your AI agent at the skills/ directory

License

MIT