Skill Lifecycle: From Installation to Execution

Updated Aug 2026

Phase 1: Installation

Skills are installed from Git repositories using the skills CLI, or generated by the tool they wrap:

# From a repository
npx skills add <repo-url> --skill <skill-name>

# Generated by the wrapped tool (the 2026-native path)
playwright-cli install --skills   # writes a SKILL.md teaching the agent the CLI

What happens:

1. The repository is cloned (or the skill directory is downloaded)
2. The SKILL.md is copied to the agent's skills directory
3. Any bundled resources (/scripts/, /references/, /assets/) are copied alongside
4. The skill becomes available in the agent's next session

Installation Locations

Skills can live in multiple locations, loaded in priority order:

Project skills override user skills which override built-in skills (by name).

The Skills Directory (skills.sh)

The Agent Skills Directory is a centralized marketplace with tens of thousands of skills. Skills are portable across agent platforms (Claude Code, Cursor, Gemini CLI, Codex CLI, Copilot, Cline) — as of 2026 the SKILL.md format is a de facto cross-agent standard, which is exactly why tool vendors now ship skills alongside their CLIs.

Phase 2: Discovery

On every conversation turn, the system:

1. Scans all skill locations for SKILL.md files
2. Reads the YAML frontmatter from each
3. Filters to skills that have a description field
4. Formats all skill names + descriptions into a text block
5. Injects this block into the Skill tool's description

The formatted block looks approximately like:

Available skills:
- playwright-cli: Browser automation via CLI. Navigate pages, click elements,
  fill forms, take snapshots and screenshots, extract page state.
- commit: Create well-formatted git commits with conventional commit messages.
- pdf: Convert documents to PDF format.

This is embedded in the tools array sent with every API request. It consumes tokens, but far fewer than MCP tool schemas — a skill contributes ~50-100 tokens to the tool description vs 500-2000 per MCP tool.

Token Budget

The system enforces a ~15,000 character budget for the available skills listing. If you install too many skills, some may be truncated or omitted. This is why skill descriptions should be concise.

Phase 3: Selection

When a user message arrives, Claude's language model processes:

• The user's message
• Conversation history
• All available tools (including the Skill tool with its embedded skill list)

There is no algorithmic routing. The selection happens inside Claude's forward pass through the transformer. Claude reads the skill descriptions and decides — through language understanding — whether any skill matches the user's intent.

This means:

• Skill descriptions are the selection mechanism — poorly written descriptions = skills that never get invoked
• Claude may choose not to use a skill even when one is available (if direct tool use seems better)
• Claude may invoke multiple skills sequentially in complex workflows

Selection Signals

Claude considers:

1. Description match — Does the skill description match the user's intent?
2. Conversation context — Has the user been working on browser testing? Then the browser skill is more likely
3. Explicit invocation — User says /playwright-cli or "use the browser skill"
4. Task context — If the agent is writing tests that need browser verification

Phase 4: Invocation

When Claude decides to use a skill, it calls the Skill tool:

{
  "tool": "Skill",
  "input": {
    "skill": "playwright-cli"
  }
}

The system then performs several operations:

4a. Visibility Message (Shown to User)

<command-message>The "playwright-cli" skill is loading</command-message>
<command-name>playwright-cli</command-name>

This appears in the user's chat interface, providing transparency about what's happening.

4b. Context Injection (Hidden from User, Sent to API)

The full content of SKILL.md is injected as a user message with isMeta: true:

• Visible to Claude — it receives the full instructions
• Hidden from UI — the user doesn't see the raw markdown
• Added to conversation history — persists for the remainder of the skill's execution

4c. Permission Elevation

If the SKILL.md frontmatter specifies allowed-tools: Bash, the Bash tool is temporarily pre-approved. This means:

• The agent can run playwright-cli open <url> without asking permission for each command
• The user isn't bombarded with "Allow Bash?" prompts during browser automation
• Permissions revert after the skill completes

4d. Model Override (Optional)

If the SKILL.md specifies a model: field, the system switches to that model for the skill's execution. This enables cost optimization — a simple skill can use Haiku while the main conversation uses Opus.

Phase 5: Execution

With the SKILL.md instructions in context and tools available, the agent proceeds to execute. For a browser skill, this typically means:

Agent reads: "playwright-cli open <url> — launch browser at a page"
Agent executes: Bash("playwright-cli open https://example.com")
Agent reads: "playwright-cli snapshot — save page state to disk"
Agent executes: Bash("playwright-cli snapshot")
Agent reads the snapshot file only if it needs it, and decides next actions

The agent is now operating with domain knowledge (how to use vibe-check) that it didn't have before the skill was loaded. This is the core value of skills.

Error Recovery During Execution

When a command fails, the agent:

1. Reads the error output from Bash
2. Applies its reasoning (enhanced by SKILL.md tips)
3. Tries alternative approaches

Example: If playwright-cli click e14 fails with a timeout, the agent might:

• Run playwright-cli snapshot and read it to see what's actually on the page
• Run playwright-cli screenshot to inspect the visual state
• Pick a different element ref based on what it finds

This is not self-healing in the traditional sense — it's an intelligent agent reasoning about failures, which is more flexible than any static retry logic.

Phase 6: Completion

When the agent finishes the task (or the user interrupts), the skill's effects unwind:

• Elevated permissions revert to the session's defaults
• The model reverts to the session's default
• SKILL.md content remains in conversation history (for context continuity)
• The browser daemon may still be running (it's separate from the skill lifecycle)

Lifecycle Diagram

┌───────────┐    ┌────────────┐    ┌────────────┐    ┌─────────────┐    ┌───────────┐    ┌────────────┐
│ Install   │───▶│ Discover   │───▶│  Select    │───▶│  Invoke     │───▶│  Execute  │───▶│  Complete  │
│           │    │            │    │            │    │             │    │           │    │            │
│ npx skills│    │ Scan dirs  │    │ LM matches │    │ Inject MD   │    │ Bash cmds │    │ Revert     │
│ add <repo>│    │ Read YAML  │    │ intent to  │    │ Grant perms │    │ via tools │    │ permissions│
│           │    │ Format list│    │ description│    │ Switch model│    │ Agent loop│    │            │
└───────────┘    └────────────┘    └────────────┘    └─────────────┘    └───────────┘    └────────────┘
  (once)         (every turn)     (every turn)      (on match)      (agent-driven)    (on finish)

Key Takeaway

The elegance of the skill system is that it adds zero new infrastructure. No servers, no APIs, no protocols. Just a markdown file that gets injected into conversation context at the right time. The agent does the rest with tools it already has (Bash, Read, Write).

This is why skills are so much lighter than MCP: MCP requires a running server process, a protocol handshake, tool schema exchange, and persistent state management. A skill is literally a file.