Using Skills Directly vs. Via an AI Agent in emilkowalski/skills

The emilkowalski/skills repository supports two distinct consumption modes—direct prompt pasting for static, manual control, or agent-orchestrated execution for autonomous, context-aware workflows.

The emilkowalski/skills repository is a collection of self-contained prompts stored as SKILL.md files that encode expert knowledge about UI design, animation, and component architecture. Understanding the difference between using skills directly versus via an AI agent is critical for choosing the right approach, whether you need a quick one-off query or a comprehensive codebase audit.

What Are Skills in emilkowalski/skills?

Each skill in this repository is a standalone markdown file (e.g., skills/animate/SKILL.md) containing specialized prompts that guide language models through specific tasks like animation implementation or UI library selection. These files represent portable expertise that can be fed directly into any model capable of processing markdown instructions.

Using Skills Directly

When using skills directly, you interact with the raw markdown content without intermediary tooling.

How Direct Usage Works

You copy the contents of a SKILL.md file and feed it straight to a language model. The model receives only the static text of the skill plus any additional context you manually append. For example, you might pipe the skill content to an OpenAI API endpoint:

cat skills/animate/SKILL.md | \
  openai api chat.completions.create -m gpt-4 -t @-

This approach treats the skill as a simple prompt template with no awareness of your specific repository structure or runtime variables.

When to Use Direct Prompts

Direct usage is ideal for one-off queries, quick look-ups, or situations requiring full manual control over the prompt and response. If you need to tweak the system instructions or provide highly specific, curated context, pasting the markdown directly ensures no automation interferes with your inputs.

Using Skills Via an AI Agent

The AI agent transforms static skills into dynamic, context-aware workflows through the skills CLI tooling.

How the Agent Architecture Works

After installing the suite with npx skills@latest add emilkowalski/skills, the agent loads skill definitions and injects runtime variables automatically. According to the source code in skills/improve-animations/SKILL.md, the agent executes a multi-step interaction:

1. Loads the skill definition from the appropriate SKILL.md file
2. Supplies current project context including files, stack, and UI libraries
3. Executes the model, then chains additional calls (e.g., audit → plan → review)

The agent can dispatch sub-agents, persist execution plans, and enforce hard rules defined within the skill files.

Agent Capabilities and State Management

Unlike direct usage, the agent maintains state between operations. When running skills improve-animations audit, the agent scans ./src/**/*.tsx, detects animation issues, and saves results to plans/audit.md without manual copy-pasting. The agent also enforces constraints such as the "Never modify source code" rule found in skills/improve-animations/SKILL.md, ensuring safety guardrails remain active throughout autonomous execution.

Key Differences Between Direct and Agent Usage

Understanding the architectural distinctions helps you choose the appropriate mode.

Scope of Autonomy Direct use provides static prompts with no repository awareness unless you manually add file contents. The AI agent automatically reads your codebase, populates skill placeholders, and dispatches sub-agents to handle large repositories.

State Handling Agents track intermediate results (audit reports, prioritized plans) and persist them in directories like plans/ or animation-plans/. Direct usage requires you to manually capture and store outputs.

Extensibility The agent can chain multiple skills sequentially, such as running skills find-animation-opportunities followed by skills improve-animations. Direct prompts offer no built-in chaining mechanism or enforcement of inter-skill dependencies.

User Experience The CLI provides a consistent entry point (skills <skill-name>) across all operations. Without the agent, you must locate and paste markdown files manually for each interaction.

Summary

• Direct usage involves copying SKILL.md content manually into your model interface, offering full control but requiring manual context injection and result handling.
• Agent usage leverages the skills CLI to automatically load skills, scan repositories, and orchestrate multi-step workflows with state persistence.
• Key files like skills/improve-animations/SKILL.md and skills/find-animation-opportunities/SKILL.md contain prompts designed specifically for agent orchestration with runtime variable support.
• Installation via npx skills@latest add emilkowalski/skills unlocks the agent capabilities, while direct usage requires no installation beyond access to the markdown files.

Frequently Asked Questions

Can I use emilkowalski/skills without installing the CLI?

Yes. You can use skills directly by copying the markdown content from any SKILL.md file (such as skills/animate/SKILL.md) and pasting it into your preferred language model interface. This requires no installation but lacks the context injection and automation features provided by the agent.

How does the agent inject repository context?

The agent automatically scans your project files (e.g., ./src/**/*.tsx) and supplies the current stack, UI libraries, and component architecture as runtime variables when loading the skill. This happens transparently when you invoke commands like skills improve-animations audit, whereas direct usage requires you to manually copy file contents into your prompt.

Where are execution plans stored when using the agent?

The agent persists generated plans in project directories such as plans/ or animation-plans/. For example, running skills improve-animations plan "Fix toast timings" creates a self-contained plan file that subsequent commands like skills improve-animations execute plan can read and process.

Which skill files demonstrate agent-specific features?

The skills/improve-animations/SKILL.md file showcases agent capabilities including audit-to-plan chaining, hard rule enforcement (e.g., "Never modify source code"), and sub-agent dispatch. Similarly, skills/pick-ui-library/SKILL.md demonstrates how agents avoid naive AI guesses by analyzing project context before making recommendations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}