agent-skill-kit 0.5.2

Centralized skills repository and CLI toolkit for AI agents

Agent Skill Kit (ASK)

Centralized skills repository and CLI toolkit for AI agents (Gemini, Claude, OpenAI).

🚀 Major Update (v0.4.0)

ASK now supports the Hierarchical Multi-Agent System (HMAS) paradigm. Introduce parallel orchestration to your AI with new Subagent capabilities!

New Features

• Universal Source of Truth: ask copy now defaults to .agents/skills/ as the single source of truth for your AI skills, and automatically symlinks to older tools (like Cursor, Codex) while avoiding redundant copies!
• ask rules compile: Manage your .cursorrules, CLAUDE.md, and .agent/rules/ from a central .agents/rules repository natively using ask rules compile.
• ask purge: A new interactive command to safely clean old ask-* tracking files across all your agents.
• ask-parallel-auditor: New Orchestrator skill to chunk and run subagents in isolated worktrees entirely in parallel, bypassing token limits.
• Gold Standard Skills: Strict SKILL.md + scripts/ + assets/ structure for 37+ skills.

---

It serves as a unified "package manager" for your AI's capabilities, allowing you to define a skill once and deploy it to Gemini, Claude, Codex, Antigravity, Cursor, and more.

🧠 Why Agent Skill Kit?

Managing instructions for multiple AI agents is tedious. You often have to:

• Copy .cursorrules to .codex.md.
• Manually sync ~/instructions.md with project-specific prompts.
• Format skills differently for Gemini (SKILL.md) vs Claude (Slash Commands).

ASK solves this by treating skills as reusable packages.

1. Define Once: Write a skill in a standard format.
2. Deploy Anywhere: ASK transforms and copies the skill to the correct location and format for each agent.
3. Sync: Keep all your agents updated with a single command.

🚀 Features

• Multi-Agent Support: Native support for Gemini, Claude Code, OpenAI Codex, Antigravity, and Cursor.
• Skill Dependencies: Automatically resolves and installs dependent skills (e.g., a "Vue Architect" skill depends on "TypeScript Basics").
• Dynamic Discovery: Automatically discovers available agents in the agents/ directory.
• Safe Copy: Strictly adheres to "Do Not Overwrite". Prompts for a new name if a skill conflicts.
• Configuration: Customizable defaults via ~/.askconfig.yaml (e.g., set your default agent).
• Search & Validate: Powerful search tools and integrity checks (ask validate) to keep your library healthy.
• Local & Global: Choose between Project-Local (specific to one repo) or Global (user-wide) deployment.
• Skill Linting: Token analysis and schema validation with ask skill lint.
• Manifest Generation: Auto-generate manifest.json for skill routing.
• Extensible: Add support for any new AI agent in seconds via the ask add-agent wizard.

📦 Installation

Homebrew (Recommended for Mac/Linux)

brew tap NavanithanS/Agent-Skill-Kit
brew install agent-skill-kit

From PyPI

pip install agent-skill-kit

From Source (Development)

# Clone the repository
git clone https://github.com/NavanithanS/Agent-Skill-Kit.git
cd Agent-Skill-Kit

# Install in editable mode
pip install -e .

Upgrading an Existing Installation

When a new version (like v0.4.0) is released, you must upgrade the CLI and then sync the new skills down to your local AI agents.

# 1. Upgrade the CLI
pip install --upgrade agent-skill-kit  # If using PyPI
brew upgrade agent-skill-kit           # If using Homebrew

# 2. Sync the new skills to your agents
ask update

🛠 Usage

1. Copy Skills to an Agent ⭐

The primary way to use ASK — Deploy skills to your AI agents using the interactive wizard.

Interactive Mode (Recommended):

ask copy

The wizard guides you through:

1. Skill Selection: Beautiful table showing all skills with descriptions and categories
2. Agent Selection: Compatible agents highlighted for your chosen skill
3. Destination: Choose between local (project) or global (user-wide) installation

Quick Mode (with flags):

# Copy specific skill
ask copy gemini --skill bug-finder

# Copy all compatible skills to an agent
ask copy claude --all

2. List Available Skills

View your library of skills, including descriptions and supported agents.

# List all skills
ask list

# Search for skills
ask list --search "docker"

# Filter by category or agent
ask list --category coding --agent claude

3. Manage Rules (ask rules compile)

Easily manage rule files (.cursorrules, CLAUDE.md, .agent/rules/) by compiling them from a single central Universal Truth directory!

# Place your `.md` snippets in .agents/rules/ or ~/.agents/rules/
ask rules compile

4. Interactive Purge (ask purge)

Safely delete ask-* skills from selected target agents (or the entire Universal directory) with interactive selection prompts.

ask purge

5. Validate Library

Check your skill library for errors, missing metadata, or circular dependencies.

ask validate

6. Create a New Skill

AI-Assisted (Recommended): Simply ask your AI agent to create a skill for you:

Create a new skill for Docker best practices

Make a skill that teaches REST API design

create new skill: explaining-code
Purpose: Explains code using analogies, ASCII diagrams, and step-by-step walkthroughs. Triggered by queries like "How does this work?"
Instructions emphasize conversational tone, multiple analogies, and highlighting common misconceptions.

Prerequisites: Deploy ask-skill-creator to your agent first (see Tooling Skills).

Manual CLI (Alternative): Launch the interactive wizard to generate a standardized skill template.

ask create skill

7. Sync All Skills

Synchronize your entire skill library to all supported agents at once.

ask sync all

8. Update Skills

Keep your installed skills up-to-date with the latest versions from the repository.

ask update

Features:

• Version Checks: Compares installed version vs source.
• Interactive: Select which skills to update (or use --yes to update all).
• Safe: Automatic backup (SKILL.md.bak) created before overwriting.

9. Add Support for New Agents

Want to use Windsurf or Aider? Use the scaffold wizard:

ask add-agent

This creates the necessary adapter code, making the new agent available instantly.

10. Skill Development Tools (New in v0.2.0)

# Lint skills for token limits and schema compliance
ask skill lint

# View token usage report
ask skill profile

# Generate manifest.json for routing
ask skill compile

🎯 Supported Agents

Agent	Local Path (Project)	Global Path (User)	Format
Antigravity	.agent/skills/	~/.gemini/antigravity/skills/	SKILL.md (YAML)
Gemini CLI	.gemini/skills/	~/.gemini/skills/	SKILL.md (YAML)
Claude Code	.claude/commands/	~/.claude/commands/	Markdown Command
Codex	codex.md	~/.codex/instructions/	Markdown
Cursor	.cursor/rules/	~/.cursor/rules/	Markdown Rules

� Available Skills

ASK comes with a curated collection of skills to boost your AI agent's capabilities. Each skill provides specialized instructions and best practices.

Planning Skills

Skill	Description	Use Cases
adr-logger	Automates creation of Architectural Decision Records	• Recording tech decisions • Documenting context & consequences • Maintaining decision history
brainstorm	Guidelines for exploring user intent and requirements	• Defining user intent • Gathering requirements • Exploring design options
project-memory	Maintains a 'Project Brain' of decisions	• Avoiding re-discussions • Checking past decisions • Recording new choices
buildmaster	Smart Epic Orchestration Agent	• Epic discovery & scoping • Ticket decomposition • Execution tracking & handoff

Coding Skills

Skill	Description	Use Cases
bug-finder	Best practices for systematic bug hunting and debugging	• Debugging complex issues • Isolating bugs • Using debugging tools
code-reviewer	AI code reviewer providing constructive feedback	• Code quality checks • Security & performance review • Learning best practices
effective-llm-coder	Guides agent in declarative, simple, tenacious coding	• Declarative workflows • Simplicity & tenacity • Iterative refinement
commit-assistance	Assist with code review, staging, and committing	• Pre-commit review • Meaningful commit messages • Staging files
explaining-code	Explains code using analogies and diagrams	• Understanding complex code • Visualizing flow • Learning new codebases
flutter-architect	Senior Flutter skill using FVM	• Layer-First Architecture • Stream-based Services • Strict coding conventions
flutter-mechanic	Maintenance skill for Flutter projects using FVM	• Clean Build Protocol • iOS/Android fixes • Release protocols
laravel-architect	Senior scaffolding skill for Laravel (SQL/Mongo)	• Logic Layer separation • Hybrid SQL/Mongo Relations • Test-Driven Scaffolding
laravel-mechanic	Senior maintenance skill for database safety	• Zero Data Loss protocol • N+1 Query prevention • Queue debugging & forensics
owasp-security-review	Static code analysis aligned with OWASP Top 10	• Security scanning • Identifying vulnerabilities • Compliance checks
python-refactor	Guidelines for Python code refactoring	• Improving code quality • Refactoring legacy code • Python best practices
refactoring-readability	Improves code structure for clarity	• Renaming vars/functions • Reducing complexity • Improving readability
impact-sentinel	Guidelines for impact analysis and database design	• Breaking change detection • Strategic DB design • Safe optimization
unit-test-generation	Automates creation of comprehensive unit tests	• Generating new tests • Covering edge cases • Improving coverage
vue-architect	Expert scaffolding for Vue 3 (Inertia/Nuxt)	• Component blueprints • Stack detection • Best practices enforcement
vue-mechanic	Expert maintenance skill for Vue 3 (Inertia)	• Fixing navigation reloads • Debugging prop mismatches • Solving reactivity issues
component-scaffolder	Standardizes UI component creation	• Consistent folder structure • Typed props • Auto-generating tests
db-migration-assistant	Ensures safe database schema updates	• Drafting migrations • Creating rollback scripts • Preventing data loss
readme-gardener	Keeps documentation in sync with code	• Updating API docs • Documenting new features • Maintaining README accuracy
shadcn-architect	Enforces shadcn/ui patterns and consistency	• Preventing style bloat • Enforcing import rules • Promoting accessibility
security-sentinel	Pre-flight security checker for secrets/vulns	• Blocking commits with secrets • Detecting SQL injection • Flagging unsafe Blade usage
nextjs-architect	Expert scaffolding for Next.js 14+ (App Router)	• Server Components • Server Actions • Metadata API
fastapi-architect	Expert scaffolding for FastAPI projects	• Pydantic V2 • Async SQLAlchemy • Dep Injection
docker-expert	Expert guidance on Docker & Containers	• Multi-stage builds • Security best practices • Image optimization
conceptual-integrity-sentinel	Audits repositories for architectural drift and bloat	• Detecting complexity bloat • Identifying dead code • Enforcing simplicity

---

Tooling Skills (Meta-Skills)

🧹 ask-context-janitor

Description: Aggressive token optimizer and context summarizer for reducing large text files, logs, or agent outputs.

How to Use:

ask copy antigravity --skill ask-context-janitor

Use Cases:

• Summarizing massive .log files from build errors.
• Digesting large ARCHITECTURAL_AUDIT.md files or git diff outputs.
• Acting as a data-reducer for multi-agent workflows.

---

�️ ask-ast-mapper

Description: Read-only subagent for generating lightweight AST dependency maps and structural overviews of directories.

How to Use:

ask copy antigravity --skill ask-ast-mapper

Use Cases:

• Quickly mapping dependencies of a directory without reading every file.
• Generating a lightweight JSON structure of imports and class methods.
• Acting as a reconnaissance subagent for heavier architectural agents.

---

⚡ ask-parallel-auditor

Description: Orchestrator skill that splits a target repository into chunks and runs multiple audit subagents in parallel to bypass context limits.

How to Use:

ask copy antigravity --skill ask-parallel-auditor

Use Cases:

• Running repository-wide security scans or complexity audits.
• Delegating task subsets to identical subagents (e.g., ask-owasp-security-review).
• Bypassing the token limit of single-agent workflows.

---

�🛠️ ask-skill-creator

Description: Teaches AI agents how to create skills for Agent Skill Kit

How to Use:

# Deploy to all agents so they can create skills
ask sync all

Use Cases:

• AI-Assisted Skill Creation: Let your AI agent create new skills by simply asking

  "Create a skill for API design best practices"
  

• Standardizing skill structure and format
• Automating skill scaffolding
• Building your custom skill library
• Teaching AI agents the skill creation workflow

Example Workflow:

1. Deploy this skill to your agent: ask copy gemini --skill ask-skill-creator
2. Ask your agent: "Create a skill called 'ask-docker-best-practices' for containerization guidelines"
3. The agent generates the skill files automatically

---

🎯 ask-add-agent

Description: How to add support for new AI code editors to Agent Skill Kit

How to Use:

# Deploy to help your agent add new editor support
ask copy antigravity --skill ask-add-agent

Use Cases:

• Extending ASK: Add support for new AI editors (Windsurf, Aider, etc.)
• Creating custom agent adapters
• Understanding the agent adapter architecture
• Contributing new agent support to the project

Example Workflow:

1. Deploy this skill to your agent
2. Run the wizard: ask add-agent
3. Or ask your agent to help: "Add support for Windsurf editor"
4. The agent follows the documented process to create the adapter

---

📄 ask-pdf-processing

Description: Handle PDF text extraction, form filling, and merging

How to Use:

ask copy antigravity --skill ask-pdf-processing

Use Cases:

• Extracting text from PDF documents
• Processing PDF forms
• Merging multiple PDFs
• PDF automation workflows

---

🧠 ask-skill-capture

Description: Meta-skill. Analyzes the current session's lessons and saves them as a permanent reusable skill.

How to Use:

# Deploy to your agent (e.g., Antigravity, Gemini)
ask copy antigravity --skill ask-skill-capture

Use Cases:

• Chat-to-Code: Turn "messy" chat context into a structured skill
• Constraint Capture: Permanently save rules like "Always use FVM" or "Don't use Tailwind"
• Workflow Automation: Save a successful debugging sequence as a reusable protocol
• Team Scaling: Share tacit knowledge with your team via git-committed skills

Example Workflow:

1. You struggle through a task and finally get it right
2. You say: "Capture this as a skill called 'ask-deployment-protocol'"
3. The agent analyzes the conversation and generates the SKILL.md
4. You verify and save it

---

🏗️ ask-system-architect-prime

Description: Principal Software Architect for repository audits, complexity analysis, and actionable refactoring recommendations

How to Use:

ask copy antigravity --skill ask-system-architect-prime

Use Cases:

• Full Repository Audit: Analyze architecture, complexity, security, and test coverage
• Performance Investigation: Identify N+1 queries, blocking I/O, and bottlenecks
• Security Review: Scan for hardcoded secrets and vulnerabilities
• Test Coverage Analysis: Map source files to test suites and identify gaps

Example Workflow:

1. Deploy this skill to your agent
2. Ask: "Audit this repository for architectural flaws"
3. The agent generates an ARCHITECTURAL_AUDIT.md with health score, burn list, and recommendations

---

🚀 Quick Start with Skills

# View all available skills
ask list

# Deploy a specific skill to an agent
ask copy gemini --skill ask-bug-finder

# Deploy all compatible skills to an agent
ask copy claude --all

# Sync all skills to all agents
ask sync all

# Create your own skill (interactive)
ask create skill

# Or ask your AI agent to create one (if skill-creator is deployed)
"Create a new skill for API testing best practices"

�📐 Skill Format

Each skill is a directory containing:

• skill.yaml: Metadata (name, description, tags, supported agents).
• README.md: The actual prompt/instructions for the AI.

[!IMPORTANT] Naming Convention: All skill names must start with the ask- prefix (e.g., ask-bug-finder, ask-commit-assistance).

# skill.yaml
name: ask-bug-finder
version: 1.0.0
category: coding
agents:
  - gemini
  - claude
  - cursor
depends_on:
  - ask-code-reviewer  # Automatically installed when bug-finder is installed

SKILL.md Format (v2.0)

As of v0.2.0, SKILL.md files use a token-optimized format:

---
name: ask-example
description: Brief description
triggers: ["trigger phrase 1", "trigger phrase 2"]
---

<critical_constraints>
❌ NO forbidden actions
✅ MUST required actions
</critical_constraints>

<heuristics>
- condition → action
</heuristics>

🧩 Design Principles

1. Universal Definition: Skills are defined in a neutral format that can be adapted to any agent.
2. Local-First, Global-Ready: Prioritize project-specific skills (checked into git) while supporting user-wide global skills.
3. Safe by Default: The CLI will never silently overwrite an existing skill. It always asks.
4. Agentic Workflow: The toolkit includes skills (skill-creator) specifically designed to help AI agents help you build more skills.

🗂 Repository Structure

agent-skill-kit/
├── ask/                     # CLI Source Code
│   ├── commands/            # logic for create, copy, sync, add-agent
│   └── utils/               # adapter logic, filesystem helpers
├── agents/                  # Adapters for each AI agent
│   ├── gemini/
│   ├── claude/
│   ├── codex/
│   ├── antigravity/
│   └── cursor/              # (Added via ask add-agent)
└── skills/                  # The Skill Library
    ├── coding/
    └── tooling/

🤝 Contributing

Contributions are welcome!

1. Create a Skill: Use ask create skill and submit a PR with your best prompts.
2. Add an Agent: Use ask add-agent, test it, and submit the new adapter.

License

MIT