> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentpowers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents vs Skills

> Understanding the difference between skills and agents on AgentPowers

## 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.

```text theme={null}
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.

```markdown theme={null}
---
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

| Aspect                | Skill                      | Agent                                   |
| --------------------- | -------------------------- | --------------------------------------- |
| **Format**            | Directory with `SKILL.md`  | Single `.md` file with YAML frontmatter |
| **Install location**  | `~/.claude/skills/`        | `~/.claude/agents/`                     |
| **Tool access**       | Inherits from session      | Declares specific tools in frontmatter  |
| **Security surface**  | Lower -- instructions only | Higher -- tool access declarations      |
| **claude.ai support** | Yes (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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

| Category       | Description                                         |
| -------------- | --------------------------------------------------- |
| `marketing`    | Content marketing, social media, SEO                |
| `development`  | Code review, testing, refactoring, and generation   |
| `productivity` | Workflow orchestration, task management, automation |
| `design`       | UI/UX, visual design, prototyping                   |
| `sales`        | Outreach, CRM, lead generation                      |
| `data`         | Analytics, data science, ML                         |
| `security`     | Auditing, 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:

```bash theme={null}
# 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?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@agentpowers.ai">
    Reach us at **[support@agentpowers.ai](mailto:support@agentpowers.ai)** for account issues, billing questions, or technical help.
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/ECAzvrvHA">
    Join the **AgentPowers Discord** to get help from the team and other creators in real time.
  </Card>
</CardGroup>