Skip to content

feat: Replace instruments with open SKILL.md standard for cross-platform AI agent compatibility #854

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
TerminallyLazy wants to merge 3 commits into
base: development
Choose a base branch
from
Open

feat: Replace instruments with open SKILL.md standard for cross-platform AI agent compatibility #854

TerminallyLazy wants to merge 3 commits into from
+4,734 −140

Conversation

@TerminallyLazy
Copy link
Contributor

@TerminallyLazy TerminallyLazy commented Dec 26, 2025 •
edited
Loading

Summary

This PR completely replaces Agent Zero's legacy instruments system with the open SKILL.md standard (originally developed by Anthropic). This brings cross-platform compatibility with Claude Code, Cursor, Goose, OpenAI Codex CLI, and GitHub Copilot while providing a richer, more structured approach to contextual expertise.

Motivation

The current instruments system uses a custom format that works only within Agent Zero. The SKILL.md standard is an open specification that enables:

  • Cross-platform compatibility - Same skills work across multiple AI agents
  • Community sharing - Skills can be imported from skillsmp.com and awesome-agent-skills
  • Structured metadata - YAML frontmatter for versioning, authorship, and discovery
  • Enhanced discoverability - Trigger patterns for automatic skill activation

Key Changes

Added

Category Changes
Core python/helpers/skill_loader.py - SKILL.md parser with YAML frontmatter
CLI python/helpers/skills_cli.py - Skill management CLI
Docs docs/CONTRIBUTING-SKILLS.md - Comprehensive contribution guide
Skills 12 built-in skills (brainstorming, debugging, TDD, code review, git workflow, API development, Docker/DevOps, database design, prompt engineering, security audit, create_skill, data analysis)

Modified

File Changes
python/helpers/memory.py Area.INSTRUMENTS → Area.SKILLS, updated knowledge loading
prompts/agent.system.main.*.md References skills instead of instruments
webui/components/settings/memory/ UI filter and color updates
All documentation files Updated terminology

Removed

Item Reason
instruments/ directory Replaced by skills/
prompts/agent.system.instruments.md Replaced by skills prompt

SKILL.md Format

---
name: "my-skill"
description: "What this skill does"
version: "1.0.0"
author: "Author Name"
tags: ["category", "purpose"]
triggers:
  - "pattern to auto-activate"
---

# Skill Instructions

Detailed instructions here...

Migration Path

Existing custom instruments continue to work during migration:

  1. Move from instruments/custom/ to skills/custom/
  2. Create a folder with a SKILL.md file
  3. Add YAML frontmatter with name and description

Directory Structure

skills/
├── builtin/           # Built-in skills (git-tracked)
│   ├── brainstorming/
│   ├── debugging/
│   ├── tdd/
│   └── ... (12 skills total)
├── custom/            # User skills (git-ignored)
└── shared/            # Community/imported skills

Testing

# List all skills
python -m python.helpers.skills_cli list

# Create a new skill
python -m python.helpers.skills_cli create my-skill

# Validate a skill
python -m python.helpers.skills_cli validate brainstorming

Checklist

  • Complete replacement of instruments with skills
  • YAML frontmatter parsing with security (yaml.safe_load)
  • 12 comprehensive built-in skills
  • Skills CLI for management
  • Cross-platform SKILL.md standard compliance
  • Comprehensive contribution documentation
  • Updated all references (prompts, docs, webui)
  • Removed legacy instruments code
  • No breaking changes to existing workflows

Related Resources

TerminallyLazy and others added 3 commits December 26, 2025 08:06
@TerminallyLazy @claude
feat: complete SKILL.md standard implementation - replace instruments
ad9e192 
This commit completes the replacement of Agent Zero's legacy "instruments"
system with the open SKILL.md standard (originally developed by Anthropic).

- Remove INSTRUMENTS from Memory.Area enum, keep only SKILLS
- Update memory.py to load skills instead of instruments
- Update memory_consolidation.py docstrings

- Delete agent.system.instruments.md (deprecated)
- Update solving.md: "prefer skills" instead of "prefer instruments"
- Update tips.md: Skills section with SKILL.md standard reference
- Update tool.skills.md: Cross-platform compatibility note

- architecture.md: Full rewrite of Skills section with SKILL.md format
- installation.md: Update directory structure references
- extensibility.md: Update component terminology
- README.md: Update navigation links

- Update memory dashboard filter options (instruments → skills)
- Update area color mappings

- .gitignore: Update skill patterns (builtin instead of default)
- .dockerignore: Same patterns
- backup.py: Update backup include patterns

- Cross-platform: Works with Claude Code, Cursor, Goose, Codex CLI
- YAML frontmatter for structured metadata
- Semantic recall from vector memory
- Token efficient (not in system prompt)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@TerminallyLazy @claude
feat: add comprehensive SKILL.md skills and remove legacy instruments
672a749 
## Skills Added
- brainstorming: Structured requirements exploration before implementation
- debugging: Systematic debugging methodology
- tdd: Test-driven development workflow
- code_review: Comprehensive code review checklist
- git_workflow: Git branching and collaboration best practices
- api_development: RESTful and GraphQL API design
- docker_devops: Container and CI/CD best practices
- database_design: Schema design and query optimization
- prompt_engineering: LLM prompt crafting best practices
- security_audit: OWASP-based security review
- create_skill: Wizard for creating new skills easily

## Changes
- Removed legacy instruments directory completely
- Updated README, docs, and knowledge files to reference skills
- Added skills_cli.py for easy skill management
- All skills follow open SKILL.md standard (Anthropic)
- Compatible with Claude Code, Cursor, Goose, Codex CLI, Copilot

## Usage
- Skills auto-load into memory via vector database
- Use `python -m python.helpers.skills_cli` for management
- Create custom skills in skills/custom/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@TerminallyLazy @claude
docs: add comprehensive SKILL.md contribution guide
8693a9e 
Add CONTRIBUTING-SKILLS.md with complete documentation for:
- SKILL.md standard format with YAML frontmatter
- Quick start guide using CLI tool
- Step-by-step skill creation tutorial
- Best practices for semantic matching
- Testing and validation workflows
- Sharing skills with the community
- Cross-platform compatibility notes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@mustafamohsen
Copy link
Contributor

mustafamohsen commented Jan 12, 2026

I was looking for that. Thanks. I hope it gets accepted and merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@TerminallyLazy @mustafamohsen