Skip to main content

​
What Are Skills?

Skills are directories placed in ~/.claude/skills/ containing a SKILL.md file with YAML frontmatter. They extend Claude’s capabilities with specialized instructions, templates, and workflows. 
my-skill/
  SKILL.md      # Required: frontmatter with name, description
  helpers.py    # Optional supporting files

​
What Are Agents?

Agents are individual .md files placed in ~/.claude/agents/ with YAML frontmatter that declares metadata and tool access. They act as autonomous personas that can use specific tools and follow defined instructions. 
---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools: Read, Grep, Glob
model: claude-sonnet-4-6
---

Review the provided code for...

​
Key Differences

AspectSkillAgent
FormatDirectory with SKILL.mdSingle .md file with YAML frontmatter
Install location~/.claude/skills/~/.claude/agents/
Tool accessInherits from sessionDeclares specific tools in frontmatter
Security surfaceLower — instructions onlyHigher — tool access declarations
claude.ai supportYes (ZIP upload)No (CLI/Cowork only)

​
API Endpoints

AgentPowers provides two ways to interact with agents via the API:

​
Unified Endpoints (Both Types)

The /v1/skills endpoints work for both skills and agents. Use the optional ?type= filter to narrow results: 
# List all items (skills + agents)
curl "https://api.agentpowers.ai/v1/skills"

# List only agents
curl "https://api.agentpowers.ai/v1/skills?type=agent"

# List only skills
curl "https://api.agentpowers.ai/v1/skills?type=skill"

# Search with type filter
curl "https://api.agentpowers.ai/v1/search?q=code+review&type=agent"

​
Agent-Specific Endpoints

The /v1/agents namespace enforces type=agent — it will return 404 for items that are skills: 
# List agents only
curl "https://api.agentpowers.ai/v1/agents"

# Get agent details (404 if it's a skill)
curl "https://api.agentpowers.ai/v1/agents/code-reviewer"

# Publish an agent (type is forced to "agent")
curl -X POST "https://api.agentpowers.ai/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "code-reviewer", "title": "Code Reviewer", ...}'

​
CLI Usage

The CLI handles both types transparently: 
# Search for agents
ap search "code review" --type agent

# Install an agent (auto-detects type from API)
ap install code-reviewer

# View details (type shown in output)
ap detail code-reviewer

​
Security Pipeline

Agents receive additional security scrutiny beyond what skills get:
  1. Layers 1-8 (shared): File type validation, pattern scanning, ClamAV, Snyk, GuardDog, Socket.dev, VirusTotal, AI review
  2. Layer 9 (agent-only): Tool access audit, instruction analysis for social engineering or prompt injection, trust level scoring
The trust level (low, medium, high) indicates the assessed risk based on which tools the agent requests access to.

​
Categories

Agents and skills share the same 7 canonical categories:
CategoryDescription
marketingContent marketing, social media, SEO
developmentCode review, testing, refactoring, and generation
productivityWorkflow orchestration, task management, automation
designUI/UX, visual design, prototyping
salesOutreach, CRM, lead generation
dataAnalytics, data science, ML
securityAuditing, scanning, compliance
Categories are assigned automatically based on the skill’s description and content.

​
Publishing Agents

Publishing an agent works the same as publishing a skill: 
# Publish via unified endpoint (auto-detects type from AGENT.md frontmatter)
ap publish ./my-agent

# Or use the agent-specific API endpoint
curl -X POST "https://api.agentpowers.ai/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-agent", "title": "My Agent", "description": "...", "type": "agent"}'
The CLI auto-detects whether a package is a skill or agent by checking for SKILL.md vs .md files with agent frontmatter.

​
Need Help?

Email Support

Reach us at [email protected] for account issues, billing questions, or technical help.

Discord Community

Join the AgentPowers Discord to get help from the team and other creators in real time.