Skills vs Agent Definitions: When to Create Which

The core distinction

Skills and agent definitions serve fundamentally different purposes in the AI agent ecosystem. Getting this wrong means building the wrong artifact.

One-liner: Skills tell the agent what to know. Agents define who does the work.

AgentSkills.io open standard

The AgentSkills.io specification defines a portable skill format that works across all compatible agent products. These are the portable fields - any agent that supports the standard will understand them:

Skills following this spec work everywhere. Default to these fields unless the skill genuinely needs platform-specific behavior.

Claude Code extensions

Claude Code extends the AgentSkills spec with additional frontmatter fields. These are ignored by other agent products - use them only when needed:

When to use Claude-specific fields:

• hooks - for safety guardrails (e.g., blocking dangerous writes)
• context: fork - for heavy workloads that should run in isolation
• disable-model-invocation - for skills like /deploy that should only be manual
• paths - for auto-activating on specific file types

Note: AbsolutelySkilled registry also adds category, tags, recommended_skills, platforms, sources, and maintainers - these are registry metadata, not part of either the AgentSkills spec or Claude extensions.

Agent definition format

Agent definitions create execution contexts with their own tools, permissions, and system prompts. They use YAML frontmatter + markdown body, but the fields are different from skills:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob, Bash          # What tools the agent can use
disallowedTools: Write, Edit            # What tools are denied
model: sonnet                           # Model override
permissionMode: default                 # Permission checking behavior
maxTurns: 15                            # Maximum agentic turns
skills:                                 # Skills to preload
  - code-review-standards
  - error-handling-patterns
memory: project                         # Persistent memory scope
background: false                       # Whether to run in background
isolation: worktree                     # Git worktree isolation
---

You are a code reviewer. Analyze code and provide specific, actionable
feedback on quality, security, and best practices.

Agent definitions are stored in .claude/agents/ (project) or ~/.claude/agents/ (user-level). They are not portable across agent products.

Decision flowchart

Use this to determine whether the user needs a skill or an agent definition:

Is this primarily knowledge, instructions, or best practices?
  YES -> Create a SKILL
  NO  -> Continue...

Does it need to run in an isolated context window?
  YES -> Create an AGENT DEFINITION
  NO  -> Continue...

Does it need specific tool permissions (allow/disallow certain tools)?
  YES -> Create an AGENT DEFINITION
  NO  -> Continue...

Does it need to be portable across Claude Code, Cursor, VS Code, etc.?
  YES -> Create a SKILL
  NO  -> Continue...

Does it need its own model, maxTurns, or permission mode?
  YES -> Create an AGENT DEFINITION
  NO  -> Create a SKILL (the default)

When in doubt, create a skill. Skills are the more portable, composable choice. An agent definition can always preload skills later.

Composition patterns

The most powerful pattern is combining both: a skill provides knowledge, an agent definition creates a controlled execution environment that uses it.

Example: Code review

1. Create a code-review skill with review standards, checklists, and gotchas
2. Create a code-reviewer agent that preloads the skill with restricted tools:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality using team standards
tools: Read, Grep, Glob, Bash
skills:
  - code-review                # Preloads the skill's knowledge
maxTurns: 15
---

Review the code changes and provide feedback following the preloaded standards.

The skill is portable (works in any agent tool). The agent definition creates a focused, permission-controlled reviewer specific to Claude Code.

How skills are actually installed

The skill ecosystem uses a canonical directory + symlink federation model:

Global installation (user-level)

~/.agents/skills/              <- CANONICAL: actual files live here
  clean-code/
    SKILL.md
    evals.json
    references/

~/.claude/skills/              <- SYMLINKS for Claude Code
  clean-code -> ../../.agents/skills/clean-code

~/.cursor/skills/              <- SYMLINKS for Cursor
  clean-code -> ../../.agents/skills/clean-code

• ~/.agents/skills/ is the single source of truth for global skills
• Agent-specific directories (~/.claude/skills/, ~/.cursor/skills/, etc.) contain symlinks pointing back to the canonical directory
• One copy of the skill serves all 40+ compatible agents
• Non-universal agents (Cursor rules, Windsurf) get adapted copies instead of symlinks (content converted to agent-specific formats like MDC)
• Installation metadata tracked in ~/.agents/.skill-lock.json

Project-level installation

Project-level skills are committed to the repo so the whole team gets them. Use .agents/skills/ for cross-client compatibility.

The skl CLI

The npx skills add command manages the full installation lifecycle:

# Install from AbsolutelySkilled registry
npx skills add AbsolutelySkilled/AbsolutelySkilled --skill clean-code

# Install from any GitHub repo
npx skills add owner/repo --skill skill-name

# Install from local path
npx skills add ./path/to/skill

It handles: fetching, writing to canonical directory, creating symlinks for all detected agents, adapting content for non-universal agents, and updating the lock file.