# Accessible Shopping Visually Impaired Agent Skill

> A Claude skill from dungnotnull/accessible-shopping-visually-impaired-agent-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-accessible-shopping-visually-impaired-agent-skill-accessible-shopping-visually-impaired-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/accessible-shopping-visually-impaired-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-accessible-shopping-visually-impaired-agent-skill-accessible-shopping-visually-impaired-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```yaml
---
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

```markdown
---
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:

```python
# 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:

```typescript
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

2. **Content Validation**
   - Workflow steps are numbered
   - Quality gates defined
   - Tools listed are available

3. **Runtime Validation**
   - Parameters match schema
   - Required inputs present
   - Output format valid

### Validation Schema

```json
{
    "$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

```json
{
    "$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

```json
{
    "$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:

```python
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

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

## Hooks Integration

### Available Hooks

| Hook Name | Trigger | Parameters |
|-----------|---------|------------|
| pre_skill_invoke | Before main skill execution | HookContext |
| post_skill_invoke | After main skill completes | HookContext |
| pre_sub_skill_call | Before sub-skill invocation | HookContext |
| post_sub_skill_call | After sub-skill completes | HookContext |
| on_quality_gate | When quality gate is evaluated | QualityGateContext |
| on_error | When error occurs | ErrorContext |
| on_degradation | When system degrades | DegradationContext |

### Hook Registration

```python
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`:

```yaml
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

```python
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

```json
{
    "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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/accessible-shopping-visually-impaired-agent-skill](https://github.com/dungnotnull/accessible-shopping-visually-impaired-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-accessible-shopping-visually-impaired-agent-skill-accessible-shopping-visually-impaired-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.