Documentation Index
Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
Use this file to discover all available pages before exploring further.
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
qwen-extension.json:
{
"name": "my-extension",
"version": "1.0.0",
"contextFileName": "QWEN.md"
}
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"]
}
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
- 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
<Box aria-role="textbox" aria-label="Enter your name">
<TextInput value={value} onChange={setValue} />
</Box>
<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:
- 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
