Skills & Capabilities

🎯 Extending Your Agent with Specialized Knowledge

The Skills tab is where you enhance your AI agent with pre-packaged expertise, templates, and best practices. Unlike Knowledge bases that provide factual information, Skills equip your agent with proven implementation patterns, code examples, and step-by-step guides for specific tasks or domains.

Inspired by Anthropic's Claude Skills

AgenticFlow's Skills feature is inspired by and compatible with Anthropic's Claude Skills—a capability that allows AI agents to dynamically load specialized instructions, scripts, and resources for specific tasks. Like Claude's approach, AgenticFlow Skills:

• Load on-demand: Skills are referenced only when relevant to the agent's current task, preventing context overload

• Enable repeatability: Provide structured, consistent approaches to specialized workflows

• Support customization: Allow teams to create organization-specific capabilities beyond built-in options

• Combine with tools: Work alongside integrations (like MCP connections in Claude) to enhance both procedural knowledge and tool access

While Anthropic's Skills focus on document creation and general task automation in conversational AI, AgenticFlow Skills extend this concept to enterprise workflow automation, enabling agents to leverage proven patterns for data processing, API integrations, business workflows, and industry-specific implementations.

---

🧩 What Are Skills?

Skills are organized collections of documentation, code templates, examples, and best practices that agents can reference during execution. Think of them as reference libraries or playbooks that teach your agent how to approach specific types of tasks.

Skills vs Knowledge: Key Differences

Aspect	Knowledge	Skills
Purpose	Factual information retrieval	Procedural guidance & templates
Content Type	Documents, data, facts	Code examples, tutorials, patterns
Usage	Answer questions with specific data	Implement solutions following best practices
Structure	Searchable chunks	Organized file hierarchy
Access Pattern	Semantic/full-text search	Browse and read specific files
Example	Product catalog, FAQ database	"How to analyze data with Pandas", API integration templates

When to Use Skills

✅ USE SKILLS FOR:
- Code implementation patterns and templates
- Step-by-step procedural guides
- Best practices for specific tools or frameworks
- Reusable solution templates
- Technical tutorials and documentation
- Standardized workflows and processes

✅ USE KNOWLEDGE FOR:
- Product information and specifications
- Customer data and history
- FAQ answers and support documentation
- Company policies and procedures
- Factual information retrieval

💡 Power Tip: Combine Skills with Code Execution to enable your agent to not just read code templates, but actually execute them in a secure sandbox. This unlocks powerful capabilities like data analysis, file processing, and automated report generation using your organization's proven code patterns.

---

🎨 Skill Types

AgenticFlow supports two types of skills with different scopes and management:

📦 Built-In Skills

Pre-packaged skills provided and maintained by the platform.

Characteristics

• Scope: Available platform-wide to all projects

• Management: Maintained by AgenticFlow platform

• Access: Read-only reference

• Versioning: Versioned releases (e.g., "1.0.0", "2.1.0")

• Updates: Platform updates with new versions

• Quality: Professionally curated and tested

Common Built-In Skills

• Data analysis frameworks (Pandas, NumPy)

• API integration patterns

• LLM best practices (prompt engineering, chain-of-thought)

• Document processing workflows

• Web scraping and automation

• Testing and quality assurance patterns

Version Management

• Skills use semantic versioning (MAJOR.MINOR.PATCH)

• Agents lock to specific versions for consistency

• Update versions to access new features or improvements

🔧 Project Skills

Custom skills created and uploaded by your team for project-specific needs.

Characteristics

• Scope: Private to your project

• Management: Created and maintained by project team

• Access: Full read/write control

• Versioning: Optional version tracking

• Content: Tailored to your specific use cases

• Security: Project-level access controls

Use Cases for Project Skills

• Internal code standards and conventions

• Custom framework integration guides

• Company-specific workflow templates

• Proprietary algorithm implementations

• Domain-specific best practices

• Team knowledge codification

---

➕ Adding Skills to Your Agent

Step 1: Enable Skills

Toggle the Skills switch to ON to activate the skills feature for your agent.

Step 2: Add Skills

Click the + Add button to add skills to your agent. You have two options:

Option A: Add New Skill

Create and upload a brand new skill for this project.

Upload Process:

1. Click Add new skill

2. Upload files via the file upload dialog:

   • Drag and drop files (up to 10 MB per file)

   • Or click to browse and select files

   • Maximum 100 files per batch

3. Organize files in a meaningful structure:

   my-skill/
   ├── SKILL.md              # Required: Main documentation
   ├── examples/             # Optional: Usage examples
   │   ├── basic-example.py
   │   └── advanced-example.py
   ├── templates/            # Optional: Reusable templates
   │   └── template.json
   └── scripts/              # Optional: Implementation scripts
       └── helper.py

Required File: SKILL.md

Every skill MUST include a SKILL.md file with frontmatter metadata:

---
name: Data Analysis Toolkit
description: Comprehensive guide to data analysis with Python
skill_id: data-analysis-toolkit
version: 1.0.0
author: Data Team
tags:
  - data-analysis
  - pandas
  - python
---

# Data Analysis Toolkit

This skill provides best practices and templates for data analysis tasks...

## Quick Start

1. Import required libraries
2. Load your dataset
3. Apply analysis patterns

## Examples

See the `examples/` directory for detailed use cases.

Frontmatter Fields:

• name: Human-readable skill name

• description: Brief description for discovery (appears in skill list)

• skill_id: Unique identifier (lowercase, hyphens only)

• version: Version string (e.g., "1.0.0")

• author: Creator name or team

• tags: List of categorization tags (array or comma-separated)

Option B: Add Existing Skill

Select from built-in skills provided by the platform.

Selection Process:

1. Click Add existing skill

2. Browse available built-in skills

3. View skill descriptions and versions

4. Select skills to add to your agent

5. Click Confirm to enable selected skills

Step 3: Manage Connected Skills

Once added, skills appear in the Skills list with:

• Skill Name: Display name from SKILL.md

• Skill ID: Unique identifier

• Source: "Built-in" or "Project"

• Version: Version number (if applicable)

• Status: Ready, Processing, or Error

Actions:

• Remove: Disconnect skill from agent (doesn't delete the skill)

• View Details: Browse skill contents and documentation

---

📖 Skill Structure and Organization

Recommended Directory Structure

your-skill/
├── SKILL.md                    #  REQUIRED: Main documentation with metadata
├── README.md                   # Optional: Additional overview
├── examples/                   # Recommended: Practical examples
│   ├── basic-usage.py
│   ├── advanced-patterns.py
│   └── real-world-scenario.py
├── templates/                  # Recommended: Reusable templates
│   ├── starter-template.json
│   └── config-template.yaml
├── scripts/                    # Optional: Helper scripts
│   ├── setup.py
│   └── utilities.py
├── resources/                  # Optional: Additional resources
│   ├── cheat-sheet.md
│   └── troubleshooting.md
└── docs/                       # Optional: Extended documentation
    ├── architecture.md
    └── api-reference.md

File Organization Best Practices

Use Clear, Descriptive Names

✅ GOOD:
- authentication-with-oauth.py
- database-connection-template.json
- error-handling-patterns.md
❌ AVOID:
- script1.py
- temp.json
- notes.md

Group Related Files

✅ ORGANIZED:
api-integration/
├── SKILL.md
├── examples/
│   ├── rest-api-call.py
│   ├── graphql-query.py
│   └── webhook-handler.py
└── templates/
    ├── auth-config.json
    └── request-template.py
❌ FLAT:
api-integration/
├── SKILL.md
├── example1.py
├── example2.py
├── example3.py
├── config1.json
└── template1.py

Include Graduated Examples

examples/
├── 01-basic-usage.py           # Start simple
├── 02-intermediate-patterns.py # Build complexity
└── 03-advanced-integration.py  # Full implementation

---

⚙️ How Agents Use Skills

Agent Skill Workflow

When your agent has skills enabled, it can reference them during task execution using progressive disclosure—similar to how Claude dynamically loads relevant skills. This approach ensures agents only access skills pertinent to the current task, avoiding context overload:

1. Task Analysis

   • Agent receives a task or question

   • Determines if a skill can help

2. Skill Discovery

   • Agent lists available skills to find relevant ones

   • Reviews skill descriptions and tags

   • Dynamically selects only relevant skills (not all at once)

3. Skill Exploration

   • Reads SKILL.md for overview and guidance

   • Browses directory structure to find relevant files

   • Lists files in specific directories (e.g., examples/)

4. Content Retrieval

   • Reads specific files (templates, examples, documentation)

   • Extracts relevant patterns and code

5. Solution Implementation

   • Applies templates and patterns from skill

   • Adapts examples to current task

   • Follows best practices documented in skill

Agent Skill Tools

Agents access skills through two specialized tools:

**=

Skill Browser** Browse and discover skills and their contents.

Capabilities:

• List all skills: See all enabled skills with metadata

• List files: Browse files within a skill (recursive or shallow)

• Directory navigation: Explore skill structure

Example Agent Usage:

Agent: "Let me see what skills are available..."
[Calls skill_browser to list skills]

Agent: "I'll check the examples in the data-analysis skill..."
[Calls skill_browser to list files in data-analysis/examples/]

= Skill Reader

Read file contents from skills.

Capabilities:

• Read any text file within enabled skills

• Access code examples, templates, documentation

• View structured content (JSON, YAML, Markdown, code files)

Example Agent Usage:

Agent: "Let me read the SKILL.md to understand this skill..."
[Calls skill_reader for 'data-analysis', 'SKILL.md']

Agent: "I'll look at the basic usage example..."
[Calls skill_reader for 'data-analysis', 'examples/basic-usage.py']

Automatic Skill Integration

When skills are enabled, the agent's system prompt includes:

• List of available skills with descriptions

• Usage instructions for skill_browser and skill_reader

• Best practices for leveraging skills effectively

• Philosophy: "Skills provide tested, production-ready patterns└always prefer using them"

Read-Only Reference

Important: Skills are reference materials only└they are not executable code.

✅ Agent Actions:
- Read skill documentation
- Browse skill files
- Apply templates and patterns
- Follow procedural guides
- Adapt examples to current task
❌ Agent Cannot:
- Execute skill scripts directly
- Modify skill contents
- Install packages from skills
- Run skills as standalone programs

---

🔒 Security and Access Control

Path Security

Skills enforce strict security boundaries:

Allowed Operations

• Browse within skill directory structure

• Read files inside skills directory

• Navigate subdirectories within skills

Blocked Operations

• Directory traversal (../ sequences)

• Absolute path access (/root/...)

• Access outside skills/ directory

• Hidden files or directories (leading .)

• Invalid path characters (<>:"|?*)

Path Validation Rules

✅ ALLOWED:
- skills/data-analysis/SKILL.md
- skills/api-guide/examples/basic.py
- skills/sql-patterns/templates/query.sql
❌ BLOCKED:
- skills/../secrets/config.json         # Directory traversal
- /etc/passwd                            # Absolute path
- skills/.hidden/secret.txt              # Hidden file
- skills/test<script>.py                 # Invalid characters
- skills/a/b/c/d/e/f/g.txt              # Too deep (max 5 levels)

Project-Level Access Control

Project Skills

• Scope: Private to the project

• Access: Requires project membership and permissions

• Visibility: Only visible within the project

• Management: Project admins can create, update, delete

Built-In Skills

• Scope: Platform-wide

• Access: Available to all authenticated users

• Visibility: Listed in global skill catalog

• Management: Read-only for users; maintained by platform

---

📊 File Upload Constraints

When creating project skills, observe these limits:

File Size and Count

• Maximum file size: 10 MB per file

• Maximum files per batch: 100 files

• Total skill size: No hard limit, but keep reasonable for performance

File Type Support

Text Files (Readable by Agent)

Supported Text Formats:
- Code: .py, .js, .ts, .java, .cpp, .go, .rb, .php, .sh
- Markup: .md, .html, .xml, .json, .yaml, .yml
- Data: .txt, .csv, .sql, .log
- Config: .conf, .ini, .env.example

Binary Files

Binary files are supported but:
- Agent receives metadata only (not file contents)
- Useful for templates (e.g., .xlsx, .pdf)
- Can be downloaded via API but not read directly by agent

Path Depth Limit

• Maximum depth: 5 levels

• Example: skills/my-skill/category/subcategory/examples/file.py (5 levels)

---

🎯 Best Practices for Skill Creation

Documentation Excellence

Write Clear SKILL.md

---
name: Clear, Descriptive Name
description: Brief but informative one-liner
skill_id: lowercase-with-hyphens
version: 1.0.0
author: Team or Person Name
tags:
  - primary-category
  - technology
  - use-case
---

# Skill Name

## Overview
Brief introduction to what this skill provides and when to use it.

## Quick Start
Minimal example to get started immediately.

## Key Concepts
Important principles and patterns covered in this skill.

## Structure
- `examples/`: Real-world usage examples
- `templates/`: Reusable templates
- `resources/`: Additional documentation

## Usage Guide
Step-by-step instructions for common scenarios.

## Examples
Reference specific example files with brief descriptions.

## Tips and Tricks
Advanced patterns and optimization techniques.

## Troubleshooting
Common issues and solutions.

## References
External resources and documentation links.

Use Descriptive Tags

✅ GOOD TAGS:
- python, data-analysis, pandas
- api-integration, rest, authentication
- workflow-automation, scheduling
❌ POOR TAGS:
- stuff, code, misc
- skill, example, template (too generic)

Code Example Guidelines

Include Progressive Examples

Basic Example (01-basic.py):

"""
Basic usage demonstration with minimal complexity.
Shows the simplest way to accomplish the core task.
"""

# Clear, commented code here

Intermediate Example (02-intermediate.py):

"""
Real-world scenario with error handling and configuration.
Demonstrates best practices and common patterns.
"""

# More complete implementation

Advanced Example (03-advanced.py):

"""
Production-ready implementation with full error handling,
logging, configuration management, and optimization.
"""

# Full-featured implementation

Comment Thoroughly

# ✅ GOOD: Explains WHY and provides context
def process_data(data):
    """
    Transform raw data for analysis.

    We normalize the data first because downstream analytics
    expect consistent value ranges. This prevents skewed results
    from outliers.
    """
    # Remove outliers using IQR method
    # (Interquartile Range is robust to extreme values)
    normalized = remove_outliers(data)
    return normalized

# ❌ POOR: Only says WHAT the code does (obvious from code)
def process_data(data):
    # normalize data
    normalized = remove_outliers(data)
    return normalized

Template Design

Make Templates Adaptable

{
  "// COMMENT": "Replace placeholders with your specific values",
  "api_endpoint": "YOUR_API_ENDPOINT_HERE",
  "authentication": {
    "type": "bearer_token",
    "token": "YOUR_TOKEN_HERE"
  },
  "config": {
    "timeout": 30,
    "retry_attempts": 3,
    "// NOTE": "Adjust timeout based on your API latency"
  }
}

Include Usage Instructions

"""
TEMPLATE: Database Connection Manager

USAGE:
1. Copy this file to your project
2. Replace DATABASE_CONFIG with your credentials
3. Update connection_string with your database URL
4. Modify retry_logic if needed for your use case

SECURITY:
- Never commit credentials to version control
- Use environment variables for sensitive data
- Implement connection pooling for production
"""

class DatabaseManager:
    # Template implementation here

Organization Strategies

By Task Complexity

data-processing-skill/
├── SKILL.md
├── simple-tasks/
│   ├── csv-reader.py
│   └── basic-cleaning.py
├── intermediate-tasks/
│   ├── data-transformation.py
│   └── aggregation-patterns.py
└── advanced-tasks/
    ├── distributed-processing.py
    └── optimization-techniques.py

By Use Case

api-integration-skill/
├── SKILL.md
├── authentication/
│   ├── oauth-flow.py
│   ├── api-key-auth.py
│   └── jwt-token.py
├── data-fetching/
│   ├── rest-api.py
│   ├── graphql.py
│   └── pagination.py
└── error-handling/
    ├── retry-logic.py
    └── rate-limiting.py

By Workflow Stage

ml-pipeline-skill/
├── SKILL.md
├── 01-data-preparation/
│   ├── data-loading.py
│   └── feature-engineering.py
├── 02-model-training/
│   ├── training-loop.py
│   └── hyperparameter-tuning.py
└── 03-deployment/
    ├── model-serving.py
    └── monitoring.py

---

🚀 Skill Versioning

Project Skills (Optional Versioning)

Project skills can optionally include version information:

---
name: Custom Data Pipeline
version: 2.1.0  # Optional for project skills
---

Version Update Workflow:

1. Update skill files with improvements

2. Increment version number in SKILL.md

3. Document changes in version history

4. Re-upload modified skill (or use API to update)

Built-In Skills (Required Versioning)

Built-in skills always have versions:

---
name: OpenAI Best Practices
version: 1.5.0  # Required for built-in skills
---

Semantic Versioning:

• MAJOR (1.0.0 2.0.0): Breaking changes, incompatible updates

• MINOR (1.0.0 1.1.0): New features, backward compatible

• PATCH (1.0.0 1.0.1): Bug fixes, minor improvements

Agent Version Locking:

• Agents lock to specific versions of built-in skills

• Update agent configuration to use newer versions

• Prevents unexpected changes from automatic updates

---

📈 Monitoring and Management

Skill Status

Each skill displays its current status:

Status	Meaning
Ready	Skill processed successfully, available to agent
Processing	Skill being uploaded or updated
Error	Skill processing failed (check error message)

Troubleshooting Skills

Skill Not Appearing

Cause: Skill not enabled for agent

Solution:

1. Check that Skills toggle is ON

2. Verify skill is in the enabled skills list

3. Confirm skill status is "Ready"

Agent Can't Find Files

Cause: Incorrect file paths or structure

Solution:

1. Verify SKILL.md exists at skill root

2. Check file paths are relative to skill root

3. Ensure no directory traversal in paths

4. Confirm files uploaded successfully

Processing Failed

Cause: Invalid file format or metadata

Solution:

1. Check SKILL.md has valid frontmatter (YAML format)

2. Verify all required metadata fields present

3. Ensure file sizes under 10 MB

4. Check for invalid characters in filenames

Skill Updates

To update a project skill:

1. Modify Files Locally: Make changes to skill content

2. Re-upload: Upload modified files via API or UI

3. Update Version: Increment version number in SKILL.md (optional but recommended)

4. Test: Verify agent can access updated content

5. Document Changes: Note what changed in skill documentation

---

🎓 Common Use Cases

Use Case 1: Code Standards Enforcement

Scenario: Ensure agents follow company coding standards

Skill Structure:

coding-standards/
├── SKILL.md                      # Overview and philosophy
├── python-style-guide.md         # Language-specific standards
├── git-workflow.md               # Version control best practices
├── testing-requirements.md       # Testing standards
└── examples/
    ├── good-example.py           # Compliant code
    └── anti-patterns.py          # What to avoid

Agent Benefit: Automatically applies consistent code style and patterns

Use Case 2: API Integration Templates

Scenario: Standardize integration with third-party APIs

Skill Structure:

api-integrations/
├── SKILL.md                      # Integration overview
├── authentication/
│   └── oauth-setup.py            # Auth flow template
├── templates/
│   ├── request-handler.py        # Reusable request template
│   └── error-handling.py         # Standard error handling
└── examples/
    ├── stripe-integration.py     # Full Stripe example
    └── sendgrid-integration.py   # Full SendGrid example

Agent Benefit: Rapid, consistent API integration following proven patterns

Use Case 3: Data Processing Playbooks

Scenario: Standardize data analysis workflows

Skill Structure:

data-playbook/
├── SKILL.md                      # Data processing overview
├── cleaning/
│   ├── outlier-detection.py
│   ├── missing-data-handling.py
│   └── normalization.py
├── analysis/
│   ├── statistical-tests.py
│   └── visualization-templates.py
└── reporting/
    ├── report-generation.py
    └── summary-statistics.py

Agent Benefit: Consistent, high-quality data analysis following best practices

Use Case 4: Testing and QA Patterns

Scenario: Maintain testing standards across development

Skill Structure:

testing-patterns/
├── SKILL.md                      # Testing philosophy
├── unit-tests/
│   ├── test-structure.py         # Unit test template
│   └── mocking-examples.py       # Mocking patterns
├── integration-tests/
│   └── api-testing.py            # Integration test examples
└── resources/
    ├── test-coverage-guide.md
    └── ci-cd-integration.md

Agent Benefit: Comprehensive test coverage following industry standards

---

🎯 Skills Configuration Checklist

Before activating skills for your agent:

• Skills Enabled: Toggle switched to ON

• Relevant Skills Added: Selected or uploaded appropriate skills

• SKILL.md Present: Each skill has valid SKILL.md with metadata

• Status Verified: All skills show "Ready" status

• File Structure Clear: Skills organized logically

• Examples Included: Practical examples available for agent reference

• Documentation Complete: SKILL.md provides clear guidance

• Test Agent Access: Verify agent can list and read skills

• Version Tracking: Version numbers documented (if using versioning)

• Code Execution: Consider enabling Code Execution if skills contain executable code templates

---

💡 Tips for Effective Skills

Start Simple

Begin with one or two focused skills rather than comprehensive libraries. Build incrementally based on agent needs.

Agent-Centric Design

Write skill documentation for AI agents, not just humans:

• Use clear, explicit language

• Provide complete examples

• Include step-by-step procedures

• Anticipate common variations

Maintain and Iterate

Skills evolve with your use cases:

• Add new examples as patterns emerge

• Remove outdated content

• Update based on agent performance

• Gather feedback from agent usage logs

Leverage Built-In Skills

Before creating custom skills, check if built-in skills cover your needs. Built-in skills are professionally maintained and tested.

Combine with Knowledge

Skills and Knowledge work together:

• Knowledge: "What are our product features?" (factual data)

• Skills: "How to implement feature X?" (procedural guidance)

Combine with Code Execution

Skills become even more powerful when paired with Code Execution:

• Skills provide: Code templates, implementation patterns, best practices

• Code Execution enables: Running and adapting those templates in a live sandbox

• Result: Agents can read skill code, adapt it to specific tasks, and execute it

Example: A "data-analysis-toolkit" skill contains Python scripts for analyzing CSV data. When Code Execution is enabled, your agent can:

1. Read the analysis template from the skill

2. Adapt it to your specific CSV file and requirements

3. Execute the adapted code in the sandbox

4. Generate charts, reports, and insights automatically

See Code Execution documentation for detailed guidance on using Skills with Code Execution.

---

Skills transform your agent from a general assistant into a specialized expert└invest in building a comprehensive skills library that enables consistent, high-quality implementations across your use cases.