Skills System

The Skills System provides a Claude Code compatible way to define specialized agent capabilities with automatic instruction injection and tool permission enforcement.

Overview

Skills are Markdown files with YAML frontmatter that define:

1. Instructions — What the agent should do
2. Allowed Tools — Which tools the agent can use
3. Metadata — Name, description, tags, version

Key Features

• ✅ Automatic system prompt injection — Skill content is injected into the system prompt
• ✅ Tool permission enforcement — Skills restrict which tools can be used
• ✅ Claude Code format compatible — Use existing Claude Code skills
• ✅ Load from directories — Organize skills in folders
• ✅ Programmatic creation — Create skills in code

Built-in Skills (7)

A3S Code includes 7 production-ready skills:

Code Assistance Skills

1. code-search

Search codebase for patterns, functions, or types.

Allowed Tools: read(*), grep(*), glob(*)

Use case: Find all authentication functions, locate API endpoints, search for TODO comments

2. code-review

Review code for best practices, bugs, and security issues.

Allowed Tools: read(*), grep(*), glob(*)

Use case: Review pull requests, check for security vulnerabilities, ensure code quality

3. explain-code

Explain how code works in clear, simple terms.

Allowed Tools: read(*), grep(*), glob(*)

Use case: Onboard new developers, document complex logic, create tutorials

4. find-bugs

Identify potential bugs, vulnerabilities, and code smells.

Allowed Tools: read(*), grep(*), glob(*)

Use case: Pre-commit checks, security audits, code quality analysis

Tool Documentation Skills

5. builtin-tools

Documentation for all built-in tools: read, write, edit, patch, bash, grep, glob, ls, web_fetch, web_search, git_worktree, batch, task, parallel_task, run_team.

Allowed Tools: None (documentation only)

Use case: Reference for available tools and their parameters

6. delegate-task

Guide for delegating complex or multi-step tasks to specialized sub-agents using the task tool.

Allowed Tools: task(*), parallel_task(*), run_team(*)

Use case: Parallelize work, focused exploration, isolated execution

7. find-skills

Discover and install agent skills from the open skills ecosystem.

Allowed Tools: search_skills(*), install_skill(*), load_skill(*)

Use case: Extend agent capabilities, find domain-specific skills

Using Built-in Skills

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');

const session = agent.session('.', {
  builtinSkills: true
});

const result = await session.send('Review the auth code for security issues');

from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.hcl")

session = agent.session(".", SessionOptions(
    builtin_skills=True
))

result = session.send("Review the auth code for security issues")

Custom Skills

Skill File Format

Skills are Markdown files with YAML frontmatter:

---
name: api-design
description: Review API design for RESTful principles
allowed-tools: "read(*), grep(*)"
kind: instruction
tags:
  - api
  - design
  - rest
version: 1.0.0
---
# API Design Review

You are an API design expert. Check for:

1. **RESTful Principles**
   - Proper HTTP methods (GET, POST, PUT, DELETE)
   - Correct status codes (200, 201, 400, 404, 500)
   - Resource-based URLs (not action-based)

2. **Naming Conventions**
   - Consistent naming (camelCase or snake_case)
   - Clear, descriptive names
   - Plural for collections, singular for items

3. **Error Handling**
   - Proper error responses
   - Meaningful error messages
   - Error codes and types

4. **Documentation**
   - API documentation exists
   - Request/response examples
   - Authentication requirements

5. **Versioning**
   - API versioning strategy
   - Backward compatibility

Use `read` to examine API files and `grep` to search for patterns.

Frontmatter Fields

Tool Permission Syntax

The allowed-tools field supports wildcards:

# Allow all operations on specific tools
allowed-tools: "read(*), grep(*), glob(*)"

# Allow specific operations
allowed-tools: "read(*.rs), grep(TODO:*)"

# Allow all tools (not recommended)
allowed-tools: "*"

Loading Custom Skills

From Directory

import { Agent } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');

const session = agent.session('.', {
  skillsDir: './skills'
});

from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.hcl")

session = agent.session(".", SessionOptions(
    skills_dir="./skills"
))

Programmatically

import { Skill, SkillRegistry } from '@a3s-lab/code';

const skill = new Skill({
  name: 'security-audit',
  description: 'Audit code for security vulnerabilities',
  allowedTools: 'read(*), grep(*)',
  kind: 'instruction',
  content: `# Security Audit

Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Hardcoded secrets
4. Insecure authentication
`,
  tags: ['security', 'audit'],
  version: '1.0.0'
});

const registry = new SkillRegistry();
registry.register(skill);

const session = agent.session('.', {
  skillRegistry: registry
});

from a3s_code import Skill, SkillKind, SkillRegistry, SessionOptions

skill = Skill(
    name="security-audit",
    description="Audit code for security vulnerabilities",
    allowed_tools="read(*), grep(*)",
    kind=SkillKind.INSTRUCTION,
    content="""# Security Audit

Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Hardcoded secrets
4. Insecure authentication
""",
    tags=["security", "audit"],
    version="1.0.0"
)

registry = SkillRegistry()
registry.register(skill)

session = agent.session(".", SessionOptions(
    skill_registry=registry
))

How Skills Work

1. Instruction Injection

When a skill is registered, its content is automatically injected into the system prompt:

Original System Prompt:
"You are a helpful coding assistant."

After Adding Skills:
"You are a helpful coding assistant.

# Available Skills

## code-search
Search codebase for patterns, functions, or types.
[skill content...]

## api-design
Review API design for RESTful principles.
[skill content...]
"

2. Tool Permission Enforcement

When a skill defines allowed-tools, the agent can only use those tools.

3. Skill Tool - Callable Skills with Permission Isolation

The Skill tool allows the LLM to invoke skills as callable tools, with the skill's allowed-tools temporarily granted during execution. This enforces skill-based access patterns and prevents agents from bypassing skills to directly access underlying tools.

How It Works

1. LLM calls: Skill("data-processor", prompt="Read README.md")
2. SkillTool creates temporary PermissionPolicy from skill's allowed-tools
3. New AgentLoop is created with skill's permissions
4. Skill executes with temporary permissions
5. After execution, permissions are automatically revoked (RAII)

Example: Permission Isolation

import { Agent, SessionOptions, PermissionPolicy, PermissionRule } from '@a3s-lab/code';

// Create agent with Skill(*) permission only
const agent = await Agent.create('agent.hcl');

const session = agent.session('.', {
  skillsDir: './skills',
  permissionPolicy: new PermissionPolicy({
    allow: [new PermissionRule('Skill(*)')],  // Only allow Skill tool
    deny: [new PermissionRule('read(*)')],    // Deny direct read access
    defaultDecision: 'deny'
  })
});

// Agent can only access read/grep through skills
// Direct read calls will be denied
const result = await session.send('Use data-processor to read file.txt');

from a3s_code import Agent, SessionOptions, PermissionPolicy, PermissionRule

# Create agent with Skill(*) permission only
agent = Agent.create("agent.hcl")

session = agent.session(".", SessionOptions(
    skills_dir="./skills",
    permission_policy=PermissionPolicy(
        allow=[PermissionRule("Skill(*)")],  # Only allow Skill tool
        deny=[PermissionRule("read(*)")],    # Deny direct read access
        default_decision="deny"
    )
))

# Agent can only access read/grep through skills
result = session.send("Use data-processor to read file.txt")

Benefits

1. Permission Isolation: Parent agent cannot bypass skills to access underlying tools
2. Temporary Grants: Permissions are only granted during skill execution
3. Automatic Revocation: RAII pattern ensures permissions are cleaned up
4. Composable Security: Combine with permission policies for fine-grained control

Use Cases

• Restricted Environments: Allow agents to use powerful tools only through approved skills
• Audit Trails: Track which skills are invoked and what tools they use
• Skill Composition: Build complex workflows by chaining skill invocations
• Security Boundaries: Enforce security policies at the skill level

4. Multiple Skills

When multiple skills are active, a tool is allowed if any skill allows it:

Skill Types

Instruction Skills

Most common type. Provides instructions to the agent.

kind: instruction

Use case: Code review, security audit, API design

Persona Skills

Defines a persona or role for the agent to adopt.

kind: persona

Use case: Give the agent a specific identity (e.g., "security expert", "technical writer")

Examples

Read-Only Agent

Security Auditor

---
name: security-auditor
description: Comprehensive security audit
allowed-tools: "read(*), grep(*), glob(*)"
kind: instruction
tags:
  - security
  - audit
version: 1.0.0
---
# Security Auditor

You are a security expert. Perform comprehensive security audits.

## Check for:

### 1. Injection Vulnerabilities
- SQL injection
- Command injection
- LDAP injection
- XPath injection

### 2. Authentication Issues
- Weak password policies
- Missing authentication
- Insecure session management
- Hardcoded credentials

### 3. Authorization Issues
- Missing authorization checks
- Privilege escalation
- Insecure direct object references

### 4. Data Exposure
- Sensitive data in logs
- Unencrypted data transmission
- Insecure data storage

### 5. Configuration Issues
- Default credentials
- Unnecessary services enabled
- Insecure permissions

Use `grep` to search for patterns and `read` to examine files.

Documentation Generator

---
name: doc-generator
description: Generate comprehensive documentation
allowed-tools: "read(*), grep(*), glob(*), write(*)"
kind: instruction
tags:
  - documentation
  - writing
version: 1.0.0
---
# Documentation Generator

You are a technical writer. Generate clear, comprehensive documentation.

## Documentation Structure:

### 1. Overview
- What the code does
- Key features
- Architecture overview

### 2. Getting Started
- Installation
- Configuration
- Quick start example

### 3. API Reference
- All public functions/classes
- Parameters and return types
- Examples for each

### 4. Examples
- Common use cases
- Code snippets
- Best practices

### 5. Troubleshooting
- Common issues
- Solutions
- FAQ

Use `read` to examine code and `write` to create documentation files.

Best Practices

1. Clear Instructions

Write clear, specific instructions:

❌ Bad:
"Review the code."

✅ Good:
"Review the code for:
1. Security vulnerabilities (SQL injection, XSS)
2. Performance issues (N+1 queries, inefficient algorithms)
3. Code quality (naming, structure, comments)"

2. Appropriate Tool Restrictions

Only allow tools that are needed:

# For read-only analysis
allowed-tools: "read(*), grep(*), glob(*), ls(*)"

# For code modification
allowed-tools: "read(*), write(*), edit(*), patch(*)"

# For testing
allowed-tools: "read(*), bash(*)"

3. Descriptive Names

Use clear, descriptive names:

❌ Bad:
name: skill1

✅ Good:
name: api-design-review

4. Versioning

Use semantic versioning:

version: 1.0.0  # Major.Minor.Patch

5. Tags

Use tags for organization:

tags:
  - security
  - audit
  - compliance

Troubleshooting

Skill Not Loading

Problem: Skill file not recognized

Solution:

• Check file extension is .md
• Verify YAML frontmatter is valid
• Ensure frontmatter is between --- markers

Tool Permission Denied

Problem: Agent can't use a tool

Solution:

• Check allowed-tools field in skill
• Verify tool name matches exactly
• Use wildcards: read(*) not just read

Multiple Skills Conflict

Problem: Unclear which skill is active

Solution:

• Skills are additive (union of allowed tools)
• If any skill allows a tool, it's allowed
• Use specific tool restrictions per skill

API Reference

Skill

SkillKind

SkillRegistry

Related

• Security — Security features and permissions
• Tools — Built-in tools reference
• Sessions — Session management