Skill Lifecycle: From Installation to Execution

Phase 1: Installation

Skills are installed from Git repositories using the skills CLI:

npx skills add https://github.com/VibiumDev/vibium --skill vibe-check

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 49,000+ skills. It supports multiple agent platforms (Claude Code, Cursor, Copilot, Cline). Top skills have 100k+ installs.

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:
- vibe-check: Browser automation via CLI. Navigate pages, click elements,
  fill forms, take screenshots, extract text from web pages.
- 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 vibe-check is more likely
3. Explicit invocation — User says /vibe-check or "use the vibe-check 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": "vibe-check"
  }
}

The system then performs several operations:

4a. Visibility Message (Shown to User)

<command-message>The "vibe-check" skill is loading</command-message>
<command-name>vibe-check</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:

• Claude can run vibe-check navigate <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, Claude proceeds to execute. For vibe-check, this typically means:

Claude reads: "vibe-check navigate <url> — go to a page"
Claude executes: Bash("vibe-check navigate https://example.com")
Claude reads: "vibe-check text — get all page text"
Claude executes: Bash("vibe-check text")
Claude interprets: the page text 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 vibe-check click ".btn-submit" fails with a timeout, the agent might:

• Run vibe-check find-all "button" to see what buttons exist
• Run vibe-check screenshot -o debug.png to see the page state
• Try a different selector 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.