Agent Skills Toolbox

A production-grade repository of reusable AI agent skills designed for Warp-to-Cursor workflows.

What Is This?

This repository contains executable agent roles ("skills") that can be invoked by Warp agents to analyze codebases, generate recommendations, and produce structured handoff reports for implementation in Cursor.

Key Characteristics:

• Infrastructure, not content: These are toolchain components, not prompt snippets
• Portable: Copy into any project, works across codebases
• Structured: Skills produce standardized handoff reports
• Composable: Skills can work together in chains
• Observable: Optional execution logging for improvement

Philosophy

Separation of Concerns

• Prompt library = Content artifacts (prompts, patterns, examples)
• Agent-skills repo = Infrastructure (roles, protocols, handoff contracts)

Skills are executable capabilities, not text templates.

One Source of Truth

• One canonical repository
• Copy or subtree into projects as needed
• Cursor can operate on it cleanly
• Warp agents see consistent structure

Quick Start

Using a Skill with Warp

1. Copy this repo into your project (or reference it)
2. Choose a skill from skills/ directory
3. Invoke in Warp:

   Run architecture-review in full-scan mode on the backend service
   

4. Review handoff report generated by the skill
5. Handoff to Cursor for implementation

Example Workflow

# 1. Warp agent executes skill
warp> Run project-structure-analyzer on this codebase

# 2. Skill generates handoff report
# Output: 2024-01-05_project-structure-analyzer_full-project.md

# 3. Review report, then handoff to Cursor
cursor> Implement the recommendations from 2024-01-05_project-structure-analyzer_full-project.md

Skill Organization

Skills are organized by category:

• analysis/: Discovery and mapping skills (e.g., project-structure-analyzer)
• architecture/: Architecture review and design skills
• code-review/: Code quality and review skills
• documentation/: Documentation generation skills
• security/: Security and dependency analysis skills
• testing/: Testing and validation skills
• meta/: Meta-skills for system validation

Skill Maturity Levels

Skills progress through maturity levels:

• draft: New skill, experimental, may change
• validated: Used successfully, stable structure
• hardened: Long-term use, rarely needs updates
• deprecated: Being phased out, has replacement

See meta/promotion-criteria.md for details.

Handoff Process

How Handoffs Work

1. Warp agent executes skill

   • Skill analyzes codebase
   • Generates structured handoff report
   • Saves report with standardized filename

2. Handoff report structure (see protocols/handoff-protocol.md):

   • Context summary
   • Findings (prioritized)
   • Recommendations
   • Implementation steps
   • Files to modify/create
   • Dependencies

3. Cursor receives report

   • Implementation agent reads handoff report
   • Executes recommendations
   • Modifies code per specifications

Filename Convention

Handoff reports follow: YYYY-MM-DD_skill-name_target-component.md

Example: 2024-01-05_architecture-review_auth-service.md

Skill Chains

Skills can be chained together for comprehensive analysis:

# skill-chains/full-codebase-audit-v1.yaml
name: Full Codebase Audit
skills:
  - project-structure-analyzer
  - architecture-review
  - dependency-health-check
execution: sequential

See skill-chains/ for version-locked combinations.

Execution Modes

Skills support different execution modes:

• full-scan: Analyze entire codebase (initial assessment)
• incremental: Analyze only changed files (PR review)
• targeted: Analyze specific modules (focused debugging)

See individual skill documentation for mode details.

Decision Support

• SKILL-SELECTOR.md: Decision tree for choosing skills
• SKILL-MAP.mmd: Visual diagram of skill relationships
• profiles/: Recommended skill sequences by project type

Observability

Opt-in execution logging tracks:

• Which skills are used
• Success/failure rates
• Runtime performance
• Error patterns

Privacy: No code content, file paths, or project data is logged.

See meta/observability.md for details.

Creating New Skills

1. Copy TEMPLATE.md

   cp TEMPLATE.md skills/category/new-skill.md

2. Fill in the template

   • YAML front matter (metadata)
   • Purpose and when to use
   • Behavioral rules
   • Output contract

3. Test the skill

   • Use in real scenarios
   • Validate handoff reports
   • Refine based on results

4. Promote to validated

   • After 3+ successful uses
   • Update maturity level
   • Add to SKILL-MAP and SKILL-SELECTOR

See TEMPLATE.md and meta/promotion-criteria.md for details.

Contributing

Skill Development

1. Follow the template structure
2. Include all required sections
3. Test thoroughly before promoting
4. Document anti-patterns and limitations

Skill Retirement

Skills are deprecated when:

• Used < 3 times in 6 months
• Superseded by better skill
• Technology becomes obsolete

See meta/promotion-criteria.md for retirement process.

Project Structure

agent-skills/
├── README.md                 # This file
├── TEMPLATE.md               # Skill creation template
├── SKILL-SELECTOR.md         # Decision tree
├── SKILL-MAP.mmd             # Visual skill map
├── MIGRATION-GUIDE.md        # Refactoring procedures
├── skills/                   # All skill definitions
├── protocols/                # Handoff protocols
├── meta/                     # System rules and policies
├── skill-chains/             # Version-locked combinations
├── profiles/                 # Project-type profiles
├── tests/                    # Testing framework
└── .skill-usage/             # Execution logs (git-ignored)

Key Documents

• TEMPLATE.md: Template for creating new skills
• protocols/handoff-protocol.md: Handoff report structure
• meta/composition-rules.md: How skills work together
• meta/rule-precedence.md: Conflict resolution
• meta/promotion-criteria.md: Skill lifecycle
• meta/observability.md: Execution logging
• MIGRATION-GUIDE.md: Refactoring and rollback procedures

License

[Add your license here]

Support

[Add support information here]