API Reference

SKILLS.json

Machine-readable catalog of all 1337 skills. Used by agents for skill discovery.

{
  "total_skills": 1337,
  "category_count": 19,
  "categories": {
    "cybersecurity": 786,
    "development": 92,
    "content": 64,
    ...
  },
  "skills": [
    {
      "name": "seo-optimizer",
      "category": "marketing",
      "description": "Optimize content for search engines...",
      "domain": "marketing",
      "tags": ["seo", "marketing", "growth"]
    },
    ...
  ]
}

SKILL.md Format

Every skill is a Markdown file with YAML frontmatter.

---
name: skill-name           # kebab-case, matches directory name
description: One sentence   # 50-200 chars, action-oriented
domain: category            # matches parent directory
tags:                       # 3-5 relevant tags
- tag1
- tag2
- tag3
---

# Skill Title

## When to Use          (required)
## When NOT to Use      (recommended)
## Overview             (recommended)
## Workflow              (required)
## Anti-Rationalization (recommended)
## Code Example         (recommended)
## Verification         (recommended)

Frontmatter Fields

Field	Required	Type	Description
name	Yes	string	Kebab-case skill name. Must match directory name.
description	Yes	string	50-200 chars. Action-oriented. Used for search/discovery.
domain	Yes	string	Category name. Must match parent directory.
tags	Yes	list	3-5 lowercase kebab-case tags.
version	No	string	Semantic version (e.g., "1.0.0").
author	No	string	Skill author name.
subdomain	No	string	Sub-category (e.g., "threat-hunting").

Hooks

1ai-skills includes hooks for skill lifecycle events:

Hook	Type	Description
skill-tracker	PostToolUse	Logs every skill invocation with metrics
skill-banner	PostToolUse	Shows ASCII art activation banner
skill-committer	PostToolUse	Auto-commits skill changes
skill-feedback	UserPromptSubmit	Captures user feedback on skills
skill-evolver	SessionEnd	Analyzes usage and suggests improvements

Test Suite

# Run all tests
python3 scripts/test-skills.py

# Output:
# Total:    1337
# Passed:   1337 (100.0%)
# Failed:   0
# Warnings: 0
# Time:     0.96s

# JSON output for CI
python3 scripts/test-skills.py --json > test-results.json

Exit Codes

Code	Meaning
0	All skills pass
1	One or more skills failed