Accessible Shopping Visually Impaired Agent Skill

SKILL.md — Skill Registry Documentation

Overview

The accessible-shopping-visually-impaired skill uses a modular, registry-based architecture for managing sub-skills, tools, and lifecycle hooks. This document describes how skills are registered, resolved, executed, and validated.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                         Skill Registry System                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────┐      ┌───────────────┐      ┌───────────────┐   │
│  │ Main Skill    │──────│ Skill Manager │──────│ Sub-Skills    │   │
│  │ (main.md)     │      │ (Registry)    │      │ (sub-*.md)    │   │
│  └───────────────┘      └───────────────┘      └───────────────┘   │
│                                  │                      │            │
│                                  ▼                      ▼            │
│                        ┌─────────────────┐    ┌─────────────────┐   │
│                        │ Tool Registry   │    │ Hooks System    │   │
│                        │ (JSON Schemas)  │    │ (Lifecycle)     │   │
│                        └─────────────────┘    └─────────────────┘   │
│                                  │                      │            │
│                                  ▼                      ▼            │
│                        ┌─────────────────┐    ┌─────────────────┐   │
│                        │ Config Manager  │    │ Monitoring      │   │
│                        │ (env/flags)     │    │ (logging/metrics)│  │
│                        └─────────────────┘    └─────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Skill Registration

Format Specification

Each skill file must include YAML frontmatter:

---
name: skill-name
description: one-line summary of when to trigger
---

Registration Process

1. Scan Discovery: The system scans the skills/ directory for .md files
2. Metadata Extraction: Parses YAML frontmatter from each file
3. Validation: Validates required fields (name, description)
4. Registry Storage: Stores in SkillRegistry with metadata

Example

---
name: sub-gather-requirements
description: Clarify the object of analysis, constraints, timeframe, available inputs, target audience, and language before any data fetching.
---

## Role & Persona
...

Skill Resolution

Resolution Logic

When a skill invocation is requested:

1. Parse Request: Extract skill name and context
2. Registry Lookup: Find skill by name in registry
3. Version Resolution: Select appropriate version if multiple exist
4. Dependency Check: Verify required tools and dependencies are available
5. Load Skill: Load full skill content into context

Resolution Cache

Skills are cached after first load to improve performance:

# Cache entry structure
{
    "skill_name": {
        "version": "1.0.0",
        "loaded_at": "2026-07-15T10:30:00Z",
        "content": "...",
        "metadata": {...}
    }
}

Skill Execution

Execution Flow

User Request
    │
    ▼
┌─────────────────┐
│ Pre-Flight Check│
│ - Language det. │
│ - Config load   │
│ - Trace ID gen  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────────┐
│ Hook: pre_skill │────►│ Skill Execution  │
│     _invoke     │     │ - Read content   │
└─────────────────┘     │ - Parse workflow │
         ▲              │ - Execute steps  │
         │              └─────────┬────────┘
┌─────────────────┐              │
│ Hook: post_skill│◄─────────────┘
│     _invoke     │
└─────────────────┘
         │
         ▼
   Quality Gate Check
         │
    ┌────┴────┐
    ▼         ▼
  Pass      Fail (retry)
    │         │
    ▼         ▼
 Output    Auto-fix

Execution Context

Each skill execution includes:

interface ExecutionContext {
    trace_id: string;
    user_id?: string;
    language: "en" | "vi" | "auto";
    input_params: Record;
    config: SystemConfig;
    metadata: {
        start_time: DateTime;
        retry_count: number;
        degradation_level: 0-4;
    };
    state: Map;
}

Skill Validation

Validation Levels

1. Structural Validation

• Required frontmatter fields present
• Valid YAML format
• Required sections present

1. Content Validation

• Workflow steps are numbered
• Quality gates defined
• Tools listed are available

1. Runtime Validation

• Parameters match schema
• Required inputs present
• Output format valid

Validation Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Skill Validation Schema",
    "type": "object",
    "required": ["name", "description"],
    "properties": {
        "name": {
            "type": "string",
            "pattern": "^[a-z0-9-]+$",
            "minLength": 3,
            "maxLength": 50
        },
        "description": {
            "type": "string",
            "minLength": 20,
            "maxLength": 200
        },
        "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$"
        }
    }
}

Input/Output JSON Schemas

Skill Input Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Skill Input Schema",
    "type": "object",
    "properties": {
        "skill_name": {
            "type": "string",
            "description": "Name of skill to invoke"
        },
        "parameters": {
            "type": "object",
            "description": "Skill-specific parameters"
        },
        "context": {
            "type": "object",
            "properties": {
                "trace_id": {"type": "string"},
                "language": {"type": "string", "enum": ["en", "vi"]},
                "user_id": {"type": "string"}
            }
        },
        "options": {
            "type": "object",
            "properties": {
                "dry_run": {"type": "boolean"},
                "verbose": {"type": "boolean"},
                "timeout_seconds": {"type": "integer"}
            }
        }
    },
    "required": ["skill_name"]
}

Skill Output Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Skill Output Schema",
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "enum": ["success", "partial", "failed"]
        },
        "result": {
            "type": "object",
            "description": "Skill execution result following output template"
        },
        "metadata": {
            "type": "object",
            "properties": {
                "trace_id": {"type": "string"},
                "execution_time_ms": {"type": "number"},
                "token_usage": {
                    "type": "object",
                    "properties": {
                        "prompt_tokens": {"type": "integer"},
                        "completion_tokens": {"type": "integer"}
                    }
                },
                "gates_passed": {"type": "array", "items": {"type": "string"}},
                "gates_failed": {"type": "array", "items": {"type": "string"}},
                "degradation_level": {"type": "integer", "minimum": 0, "maximum": 4}
            }
        },
        "errors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "code": {"type": "string"},
                    "message": {"type": "string"},
                    "details": {"type": "object"}
                }
            }
        },
        "warnings": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["status", "result", "metadata"]
}

Tool Integration

Tool Registration

Tools are registered in tools/schemas/ with JSON schemas:

class WebSearchTool(BaseTool):
    def _build_schema(self) -> ToolSchema:
        return ToolSchema(
            name="WebSearch",
            description="Search web for domain information",
            parameters={
                "query": PropertySchema(
                    type=DataType.STRING,
                    description="Search query",
                    required=True
                )
            },
            required_parameters=["query"]
        )

Tool Execution

result = execute_tool(
    tool_name="WebSearch",
    query="accessible retail UX",
    num_results=10
)

Hooks Integration

Available Hooks

| Hook Name | Trigger | Parameters | |-----------|---------|------------| | preskillinvoke | Before main skill execution | HookContext | | postskillinvoke | After main skill completes | HookContext | | presubskillcall | Before sub-skill invocation | HookContext | | postsubskillcall | After sub-skill completes | HookContext | | onqualitygate | When quality gate is evaluated | QualityGateContext | | onerror | When error occurs | ErrorContext | | ondegradation | When system degrades | DegradationContext |

Hook Registration

from hooks import register_hook, HookContext

def my_handler(context: HookContext) -> HookContext:
    # Handle hook event
    context.metadata["custom_data"] = "value"
    return context

register_hook('pre_skill_invoke', my_handler)

Configuration

Configuration File

Located at config/config.yml:

environment: development
log_level: INFO

llm:
  default_model: "claude-opus-4-7"
  max_tokens: 200000
  temperature: 0.7

knowledge:
  max_results_per_source: 10
  cache_ttl_hours: 24

quality_gates:
  max_retry_attempts: 2
  strict_mode: true

Environment Variables

Override configuration with environment variables:

• SKILL_ENVIRONMENT: deployment environment
• LLM_DEFAULT_MODEL: default LLM model
• LOG_LEVEL: logging level
• MONITORING_ENABLED: enable/disable metrics

Monitoring

Metrics Available

1. Token Usage: Track token consumption per skill
2. Performance: Operation latency and throughput
3. Quality Gates: Pass/fail rates per gate
4. Degradation: System degradation events

Metrics Access

from monitoring import get_all_metrics

metrics = get_all_metrics()
print(metrics["tokens"]["total"])
print(metrics["performance"]["overall"])

Quality Gates

Universal Gates (U1-U6)

| Gate | Check | Auto-Fix | |------|-------|----------| | U1 | ≥3 sources cited, ≥1 academic | Fetch from knowledge base | | U2 | Disclosure before recommendation | Prepend disclosure | | U3 | Evidence hierarchy stated | Tag source tiers | | U4 | Language matches preference | Translate output | | U5 | Output uses template | Reformat | | U6 | Claims traceable to sources | Mark unsupported |

Domain Gates (G1-G4)

| Gate | Check | Auto-Fix | |------|-------|----------| | G1 | Wayfinding accessible | Add wayfinding | | G2 | Product ID available | Add product ID | | G3 | App navigation accessible | Add indoor nav | | G4 | Checkout & staff training | Add training |

Error Handling

Error Categories

1. Validation Errors: Invalid parameters or input
2. Execution Errors: Tool or sub-skill failures
3. Timeout Errors: Operation exceeded timeout
4. Degradation Errors: Service degradation

Error Response Format

{
    "status": "failed",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Missing required parameter: object",
        "details": {
            "parameter": "object",
            "constraints": ["required"]
        }
    },
    "metadata": {
        "trace_id": "...",
        "retry_count": 0,
        "degradation_level": 0
    }
}

Best Practices

For Skill Authors

1. Clear Descriptions: Make skill descriptions descriptive and trigger-appropriate
2. Explicit Inputs: Clearly document required vs optional parameters
3. Structured Output: Use consistent output templates
4. Error Handling: Handle edge cases gracefully
5. Documentation: Include examples in skill files

For Skill Users

1. Provide Context: Give complete requirements upfront
2. Validate Inputs: Double-check parameters before invocation
3. Monitor Execution: Use trace IDs for debugging
4. Handle Errors: Implement proper error handling
5. Check Logs: Review structured logs for issues

Version Compatibility

| Version | Changes | |---------|---------| | 1.0.0 | Initial production release | | 1.1.0 | Added hooks system | | 1.2.0 | Added tool registry | | 2.0.0 | Breaking changes to execution flow |

Troubleshooting

Common Issues

Issue: Skill not found

• Solution: Verify skill name matches registry exactly

Issue: Parameter validation failed

• Solution: Check parameter types and required fields

Issue: Quality gate failed repeatedly

• Solution: Review gate requirements and enable auto-fix

Issue: Hook not executing

• Solution: Verify hook is enabled in configuration

References

• Main Skills: skills/main.md, skills/sub-*.md
• Tool Schemas: tools/schemas/__init__.py
• Hooks: hooks/__init__.py
• Config: config/config.yml
• Monitoring: hooks/monitoring.py

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/accessible-shopping-visually-impaired-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.