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:

Always consider accessibility first
Suggest using appropriate ARIA attributes
Recommend screen reader detection for complex UIs
Provide examples with accessibility built-in
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

List tables: `list_tables()`
Check schema: `describe_table({table: "users"})`
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:

Link your extension: qwen extensions link .
Start Qwen Code
Ask questions that should trigger your tools/commands
Verify the AI uses them correctly
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

Getting Started

Extension Types

Publishing

Context Provider Extensions

Creating Context Provider Extensions

What are Context Providers?

When to Use Context

Context File Format

Extension Structure

Configure in Manifest

Multiple Context Files

Example: MCP Server Context

list_tables

describe_table

Guidelines

Safety

Example: Domain Knowledge Context

Leverage ARIA Props

Guidelines for This Extension

Common Patterns

Accessible Input

Accessible Buttons

Status Messages

2. Include Examples

3. Document Constraints

4. Provide Context

5. Keep It Concise

Context vs Documentation

Testing Context

Context Loading

Multiple Extensions

Next Steps

Getting Started

Extension Types

Publishing

​Creating Context Provider Extensions

​What are Context Providers?

​When to Use Context

​Context File Format

​Extension Structure

​Configure in Manifest

​Multiple Context Files

​Example: MCP Server Context

​list_tables

​describe_table

​Guidelines

​Safety

​Example: Domain Knowledge Context

​Leverage ARIA Props

​Guidelines for This Extension

​Common Patterns

​Accessible Input

​Accessible Buttons

​Status Messages

​2. Include Examples

​3. Document Constraints

​4. Provide Context

​5. Keep It Concise

​Context vs Documentation

​Testing Context

​Context Loading

​Multiple Extensions

​Next Steps

Creating Context Provider Extensions

What are Context Providers?

When to Use Context

Context File Format

Extension Structure

Configure in Manifest

Multiple Context Files

Example: MCP Server Context

list_tables

describe_table

Guidelines

Safety

Example: Domain Knowledge Context

Leverage ARIA Props

Guidelines for This Extension

Common Patterns

Accessible Input

Accessible Buttons

Status Messages

2. Include Examples

3. Document Constraints

4. Provide Context

5. Keep It Concise

Context vs Documentation

Testing Context

Context Loading

Multiple Extensions

Next Steps