Context Provider Extensions

Provide persistent context to the AI through extension-supplied context files

Creating Context Provider Extensions

Context providers supply persistent context to the AI model through a QWEN.md file included in your extension. This context is loaded in every session where the extension is active, allowing you to provide instructions, documentation, or domain knowledge.

What are Context Providers?

Context providers:

• Supply Markdown content loaded into system context
• Are always available to the AI in sessions
• Describe tools, commands, and capabilities
• Provide instructions and guidelines
• Document domain-specific knowledge

When to Use Context

Use context files when you need to:

• Explain Extension Tools: Describe when and how to use your MCP server tools
• Provide Instructions: Give the AI guidelines for working with your extension
• Document Conventions: Share project-specific patterns or standards
• Supply Domain Knowledge: Add specialized information relevant to your extension
• Guide Behavior: Influence how the AI responds when using your extension

Context File Format

Create a QWEN.md file in your extension root:

# Extension Name

Brief overview of what this extension provides.

## Available Tools

Describe your MCP server tools and when to use them.

## Commands

List custom commands provided by the extension.

## Guidelines

Provide instructions for the AI on how to use your extension effectively.

Extension Structure

my-extension/
├── qwen-extension.json
└── QWEN.md              # Context file

Configure in Manifest

Update qwen-extension.json:

{
  "name": "my-extension",
  "version": "1.0.0",
  "contextFileName": "QWEN.md"
}

Note: If you don’t specify contextFileName but a QWEN.md file exists in your extension directory, it will be loaded automatically.

Multiple Context Files

You can specify multiple context files:

{
  "name": "my-extension",
  "version": "1.0.0",
  "contextFileName": ["QWEN.md", "docs/GUIDELINES.md", "docs/EXAMPLES.md"]
}

All specified files will be loaded in order.

Example: MCP Server Context

If your extension provides MCP server tools:

# Database Query Extension

This extension provides tools for querying and analyzing database information.

## Available Tools

### query_database

Executes SQL queries against the configured database.

**When to use:**
- User asks about data in the database
- Need to fetch information for analysis
- Verifying data existence or structure

**Parameters:**
- `query` (string): SQL query to execute
- `limit` (number, optional): Maximum rows to return (default: 100)

**Example usage:**
```sql
SELECT * FROM users WHERE active = true LIMIT 10

Important:

• Always use parameterized queries
• Be cautious with DELETE/UPDATE operations
• Verify table names before querying

list_tables

Lists all available tables in the database.

When to use:

• User asks what data is available
• Need to discover database schema
• Before querying unknown tables

describe_table

Provides schema information for a specific table.

When to use:

• Need to know column names and types
• Before constructing complex queries
• User asks about table structure

Guidelines

• Always verify table existence with list_tables before querying
• Use describe_table to understand schema before complex queries
• Limit query results appropriately to avoid overwhelming responses
• Explain query results in user-friendly language
• Suggest optimizations for slow queries

Safety

• Never execute DELETE or DROP operations without explicit user confirmation
• Always use LIMIT clauses for SELECT queries
• Validate user input before incorporating into queries

## Example: Command Extension Context

If your extension provides custom commands:

```markdown
# Development Workflow Extension

This extension provides commands for common development workflows.

## Custom Commands

### /deploy

Deploys the current project to the configured environment.

**Usage:** `/deploy [environment]`

**Environments:** `dev`, `staging`, `production`

**What it does:**
1. Runs tests
2. Builds the project
3. Deploys to specified environment
4. Runs smoke tests

### /test:e2e

Runs end-to-end tests with detailed reporting.

**Usage:** `/test:e2e [pattern]`

Provides comprehensive test results including:
- Pass/fail status
- Execution time
- Failed test details
- Screenshot links (for UI tests)

### /docs:generate

Generates API documentation from code comments.

**Usage:** `/docs:generate`

Creates documentation in `docs/api/` directory.

## When to Suggest Commands

- User mentions deployment → suggest `/deploy`
- User asks about testing → suggest `/test:e2e`
- User needs documentation → suggest `/docs:generate`

## Project Conventions

This project follows these conventions:

- **Testing:** All features require unit and E2E tests
- **Documentation:** Public APIs must have JSDoc comments
- **Commits:** Use conventional commits format
- **Branching:** feature/*, bugfix/*, hotfix/* naming

Example: Domain Knowledge Context

# Screen Reader Accessibility Extension

This extension helps build accessible components using Ink library.

## General Principles

When building custom components, it's important to keep accessibility in mind. While Ink provides the building blocks, ensuring your components are accessible will make your CLIs usable by a wider audience.

## Best Practices

### Provide Screen Reader-Friendly Output

Use the `useIsScreenReaderEnabled` hook to detect if a screen reader is active. You can then render a more descriptive output for screen reader users.

```javascript
import { useIsScreenReaderEnabled } from 'ink';

const MyComponent = () => {
  const isScreenReaderEnabled = useIsScreenReaderEnabled();
  
  if (isScreenReaderEnabled) {
    return <Text>Detailed description for screen readers</Text>;
  }
  
  return <Text>Visual representation</Text>;
};

Leverage ARIA Props

For components that have a specific role (e.g., a checkbox or a button), use the aria-role, aria-state, and aria-label props on <Box> and <Text> to provide semantic meaning to screen readers.

<Box aria-role="button" aria-label="Submit form">
  <Text>Submit</Text>
</Box>

Guidelines for This Extension

When the user asks for help building CLI components:

1. Always consider accessibility first
2. Suggest using appropriate ARIA attributes
3. Recommend screen reader detection for complex UIs
4. Provide examples with accessibility built-in
5. Explain why accessibility matters

Common Patterns

Accessible Input

<Box aria-role="textbox" aria-label="Enter your name">
  <TextInput value={value} onChange={setValue} />
</Box>

Accessible Buttons

<Box aria-role="button" aria-label="Close dialog">
  <Text>[X]</Text>
</Box>

Status Messages

<Text aria-live="polite">
  Loading complete
</Text>

## Best Practices

### 1. Be Specific

Provide concrete, actionable information:

```markdown
✅ Good:
### query_database
Executes SQL queries. Always use LIMIT to avoid large results.
Example: SELECT * FROM users LIMIT 100

❌ Bad:
### query_database
Queries the database.

2. Include Examples

Show how to use tools and commands:

## Example: Fetching User Data

1. List tables: `list_tables()`
2. Check schema: `describe_table({table: "users"})`
3. Query data: `query_database({query: "SELECT * FROM users WHERE active = true LIMIT 10"})`

3. Document Constraints

Explain limitations and requirements:

## Important Constraints

- Maximum query result: 1000 rows
- Query timeout: 30 seconds
- Read-only access (no INSERT/UPDATE/DELETE)
- Requires valid API key in settings

4. Provide Context

Help the AI understand when to use your extension:

## When to Use This Extension

Use these tools when:
- User asks about customer data
- Need to analyze sales metrics
- Looking up order information
- Generating reports

Do NOT use for:
- Modifying data (read-only)
- Real-time streaming (batch only)
- Non-business data

5. Keep It Concise

Context consumes tokens. Be comprehensive but concise:

✅ Good:
### deploy_app
Deploys to production. Runs tests first. Use `/deploy` command instead for interactive deployment.

❌ Too verbose:
### deploy_app
This tool deploys your application to the production environment. It will first run all your tests to make sure everything is working correctly. If the tests pass, it will proceed with the deployment. If the tests fail, it will stop and show you the errors. You should probably use the `/deploy` command instead because it provides a better interactive experience with progress updates and the ability to cancel if needed.

Context vs Documentation

Context (QWEN.md) is for:

• Information the AI needs during sessions
• Tool usage instructions
• Behavioral guidelines
• Domain knowledge

README.md is for:

• Human users
• Installation instructions
• Extension overview
• Troubleshooting

Keep them separate and focused on their audiences.

Testing Context

To verify your context is effective:

1. Link your extension: qwen extensions link .
2. Start Qwen Code
3. Ask questions that should trigger your tools/commands
4. Verify the AI uses them correctly
5. Refine context based on AI behavior

Context Loading

Context is loaded:

• On Qwen Code startup
• When extension is enabled
• After extension updates

Context is NOT dynamically reloaded during sessions (unlike some other extension features).

Multiple Extensions

If multiple extensions are active, all their context files are loaded. This can increase token usage, so keep context concise.

Next Steps

• Creating Extensions - Build a complete extension
• MCP Servers - Add custom tools
• Commands - Create custom commands
• Best Practices - Extension development guidelines