Skip to content

About

Skills required by AI Agents to perform basic tasks which are not probabilistic and LLM struggle with.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

7 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ€– Basic Agent Skills

A collection of OS-agnostic skills that patch well-known LLM blind spots β€” things the model cannot do reliably on its own and must delegate to real tools or scripts.

Cross-platform: Every skill ships a PowerShell script (.ps1) for Windows and a Bash script (.sh) for Linux/macOS. Each skill's SKILL.md instructs the agent to detect the OS first and run the correct script automatically.


Why This Exists

LLMs are trained on static snapshots of the world. They have no clock, no source of entropy, no arithmetic guarantees, and no access to live data or the file system. This repo teaches agents the correct procedure for each of these tasks so they always reach for the right tool instead of hallucinating an answer.


Skill Registry

# Skill Folder OS Support Status Description
1 Get Today's Date skills/get-date/ πŸͺŸ Win + 🐧 Unix βœ… Done Timezone-aware date/time via OS clock β€” IANA timezones, DST, world clock, all formats.
2 Generate Random Number skills/random-number/ πŸͺŸ Win + 🐧 Unix βœ… Done Produce a cryptographically-seeded random number using OS entropy.
3 Basic Math skills/basic-math/ πŸͺŸ Win + 🐧 Unix βœ… Done Evaluate arithmetic expressions with a real calculator to avoid rounding errors.
4 Web Search / Live Data skills/web-search/ πŸͺŸ Win + 🐧 Unix βœ… Done Fetch live facts from the web that the model's training data doesn't contain.
5 File System Operations skills/file-ops/ πŸͺŸ Win + 🐧 Unix βœ… Done Reliable read/write/list/exists operations β€” never guess file contents or paths.
6 Run Unit Tests skills/run-tests/ πŸͺŸ Win + 🐧 Unix βœ… Done Auto-detect framework (pytest/jest/dotnet/go/cargo) and run the real test suite.
7 Execute Shell Command skills/shell-exec/ πŸͺŸ Win + 🐧 Unix βœ… Done Run commands safely with blocklist validation β€” return real stdout/stderr.
8 UUID / Token Generation skills/uuid-gen/ πŸͺŸ Win + 🐧 Unix βœ… Done Generate valid UUID v4s or secure random tokens β€” not made-up strings.
9 Unit Conversion skills/convert/ πŸͺŸ Win + 🐧 Unix βœ… Done Accurate conversion for length, weight, temperature, volume, speed, and data sizes.
10 Read Environment Variables skills/env-vars/ πŸͺŸ Win + 🐧 Unix βœ… Done Inspect real runtime env vars with automatic secret redaction.
11 Hash / Checksum skills/hash/ πŸͺŸ Win + 🐧 Unix βœ… Done Compute SHA256/SHA512/SHA1/MD5 hashes of text or files β€” LLMs cannot do this.
12 Base64 Encode/Decode skills/base64/ πŸͺŸ Win + 🐧 Unix βœ… Done Encode/decode base64 (including URL-safe) without padding errors.
13 Unix Timestamp Conversion skills/timestamp/ πŸͺŸ Win + 🐧 Unix βœ… Done Convert Unix epoch ↔ human dates with timezone support.
14 Network Info skills/network-info/ πŸͺŸ Win + 🐧 Unix βœ… Done Get real IP addresses, hostname, interfaces, and public IP β€” never guess.
15 Git Info skills/git-info/ πŸͺŸ Win + 🐧 Unix βœ… Done Read current branch, status, recent commits, remotes β€” read-only, no guessing.
16 Regex Test skills/regex/ πŸͺŸ Win + 🐧 Unix βœ… Done Test patterns, extract matches, replace, or count β€” handles edge cases LLMs get wrong.
17 Password Generator skills/password-gen/ πŸͺŸ Win + 🐧 Unix βœ… Done Generate cryptographically secure passwords and passphrases with configurable rules.
18 Persistent Memory skills/memory/ πŸͺŸ Win + 🐧 Unix βœ… Done Store, search, retrieve, and delete cross-session persistent notes & variables via local JSON store.

Guardrails

All skills follow a shared set of safety guardrails defined in guardrails/GUARDRAILS.md. Six guardrail categories apply across all skills:

Category Description
Input Validation All inputs are sanitised before being passed to scripts (blocks injection, traversal, etc.)
Secret Redaction Outputs containing secret-looking values are automatically redacted ([REDACTED])
Scope Limiting Each skill operates only within its defined domain β€” no cross-skill side effects
Command Safety shell-exec validates every command against a blocklist before execution
Fail Safe If a script errors, the agent reports the error β€” it never guesses a fallback answer
Transparency For destructive operations, the agent shows the user what will run before running it

Guardrail validation scripts live in guardrails/scripts/:

Script Purpose
validate_expression.ps1 / .sh Blocks dangerous .NET/system calls in math expressions
validate_path.ps1 / .sh Blocks path traversal and access to sensitive system files
validate_command.ps1 / .sh Enforces shell command blocklist before execution
redact_secrets.ps1 / .sh Redacts secret-looking key=value pairs in any output

Evals

The evals/ directory contains a pytest-based evaluation framework that tests the scripts directly (not the LLM), following the inspect-ai / script-eval convention.

# Install dependencies
pip install -r evals/requirements.txt

# Run all evals
pytest evals/tests/ -v

# Run with scorecard summary
python evals/run_evals.py

Evals are organized per skill:

Eval file What it tests
test_get_date.py Output is non-empty, contains year + day/month name, ISO 8601 present
test_random_number.py Integers in range, correct count, floats in [0,1)
test_basic_math.py Arithmetic correctness with pytest.approx float tolerance
test_uuid_gen.py UUID v4 regex, token hex length, correct count
test_convert.py Numeric accuracy within tolerance (km→mi, °C→°F, kg→lb, GB→MB)
test_env_vars.py Secret redaction works; known var returns non-empty
test_guardrails.py Validation scripts block bad inputs (exit 1) and pass good inputs (exit 0)
test_web_search.py (skipped β€” requires network)
test_file_ops.py (skipped β€” requires filesystem setup)
test_run_tests.py (skipped β€” requires project with test suite)
test_shell_exec.py (skipped β€” requires controlled environment)

OS Detection Pattern

Every skill detects the OS before running a script. The standard pattern used:

PowerShell:

if ($IsWindows) {
    .\skills\<name>\scripts\<script>.ps1 [args]
} elseif ($IsLinux -or $IsMacOS) {
    bash ./skills/<name>/scripts/<script>.sh [args]
}

Bash:

case "$(uname -s)" in
  Linux|Darwin) bash ./skills/<name>/scripts/<script>.sh [args] ;;
  MINGW*|CYGWIN*) pwsh ./skills/<name>/scripts/<script>.ps1 [args] ;;
esac

Repository Structure

basic-agent-skills/
β”œβ”€β”€ README.md
β”œβ”€β”€ skills/                        # 10 OS-agnostic agent skills
β”‚   β”œβ”€β”€ get-date/
β”‚   β”œβ”€β”€ random-number/
β”‚   β”œβ”€β”€ basic-math/
β”‚   β”œβ”€β”€ web-search/
β”‚   β”œβ”€β”€ file-ops/
β”‚   β”œβ”€β”€ run-tests/
β”‚   β”œβ”€β”€ shell-exec/
β”‚   β”œβ”€β”€ uuid-gen/
β”‚   β”œβ”€β”€ convert/
β”‚   └── env-vars/
β”‚       β”œβ”€β”€ SKILL.md               # Agent instructions (OS detection + steps)
β”‚       └── scripts/
β”‚           β”œβ”€β”€ <script>.ps1       # Windows (PowerShell)
β”‚           └── <script>.sh        # Linux / macOS (Bash)
β”œβ”€β”€ guardrails/                    # Safety constraints for all skills
β”‚   β”œβ”€β”€ GUARDRAILS.md
β”‚   └── scripts/
β”‚       β”œβ”€β”€ validate_expression.{ps1,sh}
β”‚       β”œβ”€β”€ validate_path.{ps1,sh}
β”‚       β”œβ”€β”€ validate_command.{ps1,sh}
β”‚       └── redact_secrets.{ps1,sh}
└── evals/                         # pytest evaluation framework
    β”œβ”€β”€ README.md
    β”œβ”€β”€ requirements.txt
    β”œβ”€β”€ conftest.py
    β”œβ”€β”€ run_evals.py
    β”œβ”€β”€ fixtures/                  # YAML test case definitions (1 per skill)
    └── tests/                     # pytest test files (1 per skill)

Integrations

The skills work with every major AI coding assistant and agent framework β€” not just Antigravity. The integrations/ directory contains ready-to-use adapters for each.

Design philosophy: Every integration is a thin wrapper around the same scripts. Fix a bug in a script and it's fixed everywhere β€” Claude, Cursor, LangChain, AutoGen, all of them.

πŸ–₯️ AI Coding Assistants / IDEs

Platform Integration Type File to copy Where it goes
Antigravity Native SKILL.md discovery skills/ .agents/skills/ in your project
Claude Code CLAUDE.md instructions integrations/ide/claude/CLAUDE.md Project root
Cursor .mdc rule (alwaysApply: true) integrations/ide/cursor/.cursor/ Project root
VS Code Copilot Copilot instructions integrations/ide/vscode/.github/ Project root
Windsurf .windsurfrules integrations/ide/windsurf/.windsurfrules Project root
Any MCP client FastMCP server integrations/mcp/server.py Run as a server process

MCP (Model Context Protocol) is the most universal option β€” it works with Claude Desktop, Cursor's MCP support, VS Code extensions like Continue/Cline, and any other MCP-compatible client:

pip install -r integrations/mcp/requirements.txt
python integrations/mcp/server.py

Then point your client at the server using integrations/mcp/claude_desktop_config.example.json as a reference.

See integrations/ide/README.md for detailed setup instructions per IDE.


🐍 Agent Frameworks / SDKs

All adapters share a common integrations/frameworks/shared/skill_runner.py that handles OS detection and subprocess execution.

Framework Package Import
LangChain langchain-core>=0.3 from integrations.frameworks.langchain.tools import ALL_TOOLS
AWS Strands strands-agents>=0.1 from integrations.frameworks.strands.tools import ALL_TOOLS
CrewAI crewai>=0.80 from integrations.frameworks.crewai.tools import ALL_TOOLS
AutoGen autogen-agentchat>=0.4 from integrations.frameworks.autogen.tools import ALL_TOOLS
LlamaIndex llama-index-core>=0.11 from integrations.frameworks.llamaindex.tools import ALL_TOOLS

LangChain quick start:

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from integrations.frameworks.langchain.tools import ALL_TOOLS

llm = ChatOpenAI(model="gpt-4o")
executor = AgentExecutor(agent=create_tool_calling_agent(llm, ALL_TOOLS, prompt), tools=ALL_TOOLS)
executor.invoke({"input": "What is today's date and what is 17 * 83?"})

See integrations/frameworks/README.md for full examples per framework and integrations/README.md for the complete integration map.


Repository Structure

basic-agent-skills/
β”œβ”€β”€ README.md
β”œβ”€β”€ LICENSE
β”œβ”€β”€ skills/                        # 18 OS-agnostic agent skills
β”‚   └── <skill>/
β”‚       β”œβ”€β”€ SKILL.md               # Agent instructions (OS detection + steps)
β”‚       └── scripts/
β”‚           β”œβ”€β”€ <script>.ps1       # Windows (PowerShell)
β”‚           └── <script>.sh        # Linux / macOS (Bash)
β”œβ”€β”€ guardrails/                    # Safety constraints for all skills
β”‚   β”œβ”€β”€ GUARDRAILS.md
β”‚   └── scripts/                   # validate_expression, validate_path, validate_command, redact_secrets
β”œβ”€β”€ evals/                         # pytest evaluation framework
β”‚   β”œβ”€β”€ fixtures/                  # YAML test cases (1 per skill)
β”‚   └── tests/                     # pytest test files (1 per skill)
└── integrations/                  # Adapters for every AI platform
    β”œβ”€β”€ README.md
    β”œβ”€β”€ ide/                       # Drop-in files for coding assistants
    β”‚   β”œβ”€β”€ claude/CLAUDE.md
    β”‚   β”œβ”€β”€ cursor/.cursor/rules/
    β”‚   β”œβ”€β”€ vscode/.github/
    β”‚   └── windsurf/.windsurfrules
    β”œβ”€β”€ mcp/                       # FastMCP server (universal)
    β”‚   └── server.py
    └── frameworks/                # Python SDK adapters
        β”œβ”€β”€ shared/skill_runner.py # OS-aware script runner (shared by all)
        β”œβ”€β”€ langchain/tools.py
        β”œβ”€β”€ strands/tools.py
        β”œβ”€β”€ crewai/tools.py
        β”œβ”€β”€ autogen/tools.py
        └── llamaindex/tools.py

Contributing a New Skill

  1. Create a folder under skills/<skill-name>/.
  2. Add a SKILL.md with YAML frontmatter (name, description).
  3. Add both a .ps1 (Windows) and a .sh (Linux/macOS) script under scripts/.
  4. Include OS detection instructions in SKILL.md.
  5. Add YAML fixtures in evals/fixtures/<skill-name>.yaml and a test file in evals/tests/test_<skill_name>.py.
  6. Add an @tool function to each integrations/frameworks/*/tools.py.
  7. Add the skill to integrations/mcp/server.py.
  8. Add instructions for the skill to all IDE rules files in integrations/ide/.
  9. Review guardrails/GUARDRAILS.md and add skill-specific guardrail notes.
  10. Update the Skill Registry table in this README.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

Skills required by AI Agents to perform basic tasks which are not probabilistic and LLM struggle with.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages