Quick Reference for Building with AI agents
The Problem: Context Saturation & Tool Bloat. Loading hundreds of tools and entire codebases into an agent’s memory simultaneously leads to high latency, increased costs, and “context rot” (where the model becomes confused).
The Solution: Agent Skills. Based on an open standard, Skills are lightweight, modular units of specialized knowledge. Instead of loading everything at once, the agent uses Progressive Disclosure, loading specific procedural knowledge and scripts only when the user’s intent matches a specific skill.
Skills vs. Other Concepts:
vs. MCP (Model Context Protocol): MCP tools are the “hands” (deterministic functions), while Skills are the “brains” (the methodology of how and when to use them).
vs. Rules: Rules are passive guardrails that are always “on.” Skills are active capabilities triggered by the agent as needed.
vs. Workflows: Workflows are user-triggered macros; Skills are agent-triggered expertise.
Structure of a Skill: A Skill is a directory containing a
SKILL.mdfile (which includes metadata for the agent to “discover” it and instructions for execution), along with optional scripts (Python/Bash), resources, and examples.Implementation Levels: The author outlines five levels of skill complexity, ranging from simple formatting (Git commits) to procedural logic (database schema validation) and complex architectural scaffolding (ADK tool creation).
- Best Practice: Keep scripts atomic. A script should do one thing well (e.g., “run a query,” “deploy to staging”).
- Language Agnosticism: Antigravity can execute any script available in the host environment’s path (Python, Node, Bash, Go). However, Python is the most common choice due to its readability and rich library ecosystem.
- Arguments and Flags: The instruction body in
SKILL.mdmust clearly specify how to pass arguments to the script. The agent will then generate the correct CLI invocation based on the user’s request. For example, if the script takes a--envflag, theSKILL.mdshould instruct the agent to extract the environment (dev, stage, prod) from the user’s prompt and map it to that flag.
Combined Docs
Youtube
HackerNews
https://news.ycombinator.com/item?id=45607117
What Are Claude Skills?
Claude Skills are a new capability announced by Anthropic that allows AI models to have specialized abilities loaded on-demand. They’re essentially Markdown files containing instructions, scripts, and resources that Claude can use when relevant to a task. The key innovation is that skills are only loaded into context when needed, making them extremely token-efficient (typically just a few dozen tokens per skill in upfront scanning).
Key Perspectives and Insights from the Discussion
1. Skills as a Paradigm Shift Many commenters view Skills not as revolutionary new technology but as a formalization of what people were already doing informally. One developer noted: “Skills are cool, but to me it’s more of a design pattern / prompt engineering trick than something in need of a hard spec.” This raises an interesting point—Skills are about standardizing good practices rather than introducing genuinely novel functionality.
2. Simpler Than MCP but With Important Trade-offs A major theme is that Skills are dramatically simpler than Model Context Protocol (MCP). Unlike MCP’s complex protocol specification with servers, clients, and various transports, Skills are just text files. One commenter aptly called it “Fundamentally you’re getting hyped over a framework to append text to your prompt.” However, this simplicity comes with a crucial dependency: Skills require a functioning code execution environment (like Claude Code) to be truly powerful.
3. Security and Sandboxing Concerns Several developers raised important questions about security. Commenters noted concerns about token wastage with MCP (consuming “tens of thousands of tokens”) and worried about how Skills handle third-party API authentication. The discussion touched on the need for “safe external access / auth from code execution tool” to prevent security vulnerabilities. One comment emphasized: “Claude Desktop and/or Claude Code + a non-big-fat-pig MCP will be needed” for practical implementation.
4. Comparison to Existing Patterns There’s skepticism about whether Skills represent a genuine breakthrough. Some noted similarities to:
- Cursor Rules - configuration files for editor AI assistants
- AGENTS.md - a well-established pattern of dropping instructions into Markdown files
- VSCode’s nested AGENTS.md support
One developer stated: “The same like slash-commands for CC: it’s just convenience,” suggesting Skills are useful but not transformative.
5. Practical Advantages Over MCP The token efficiency advantage is compelling. Several commenters appreciated that you don’t need to describe how CLI tools work—the model can figure it out—versus MCP’s heavy upfront token cost. This makes Skills more practical for real-world use where context windows matter.
6. Design Philosophy Validation Simon Willison’s perspective (in the accompanying article) was particularly influential: the simplicity is intentional and powerful. Rather than being a limitation, the design philosophy of “throw in some text and let the model figure it out” aligns well with how LLMs actually work. This outsources hard problems to the coding environment rather than trying to enforce protocols.
Key Debates
- Skills as novelty vs. formalization: Is this genuinely new, or just standardizing what developers already do?
- Token efficiency: Skills win decisively on context management compared to MCP
- Dependency on code execution: Skills’ power is directly tied to having a safe code environment, which raises sandboxing challenges
- Skill sharing and composability: Questions about how skills could authenticate against third-party APIs and work across different environments
Consensus Takeaways
- Skills are significantly simpler and more token-efficient than MCP, making them more practical
- They represent good design thinking rather than breakthrough technology
- The real power depends on robust, sandboxed code execution environments
- Expect rapid ecosystem growth—easier to build and share than MCP implementations
- Likely to be more applicable to real-world agent use cases than the MCP hype suggested
The discussion reflects a maturation in how the developer community thinks about LLM tooling: moving beyond complex protocol specifications toward pragmatic, simple patterns that leverage the LLM’s natural capabilities.
Skils Examples
rominirani/antigravity-skills
Level 1: Basic Routing
git-commit-formatter
- Concept: Pure Prompt Engineering.
- Function: Intercepts “commit” requests and formats the message according to the Conventional Commits specification.
- Key File:
SKILL.md
Level 2: Asset Utilization
license-header-adder
- Concept: Loading static resources.
- Function: Adds a standard Apache 2.0 license header to source files by reading a template from the
resources/folder. - Key Files:
SKILL.md,resources/HEADER_TEMPLATE.txt
Level 3: Few-Shot Learning
json-to-pydantic
- Concept: Learning by Example.
- Function: Converts JSON data into Pydantic models by referencing a “Golden Example” pair (Input JSON → Output Python) instead of using complex instructions.
- Key Files:
SKILL.md,examples/
Level 4: Tool Use & Validation
database-schema-validator
- Concept: Delegating to deterministic scripts.
- Function: Validates SQL schema files for safety and naming conventions by running a Python script, ensuring 100% accuracy.
- Key Files:
SKILL.md,scripts/validate_schema.py
Level 5: Composition (The "Batteries-Included" Skill)
==adk-tool-scaffold==
- ==Concept: Combining scripts, templates, and examples.==
- ==Function: Orchestrates a full workflow to scaffold a new Antigravity ADK Tool. It generates the file using a script, populates it from a Jinja2 template, and guides the implementation using a reference example.==
- ==Key Files:
SKILL.md,scripts/scaffold_tool.py,resources/ToolTemplate.py.hbs,examples/WeatherTool.py==