Qiushi Skill: A Methodology Toolkit for AI Agents Based on Materialist Dialectics

What Qiushi Skill Does and Who It Is For

Qiushi Skill addresses a specific problem in AI agent behavior: agents tend to answer quickly rather than investigate first, struggle to identify the central issue in a complex problem, and stop when they hit an obstacle rather than diagnosing the root cause. The README frames these as methodological failures rather than capability gaps.

The project's response is a set of nine skills organized around a guiding principle called Seek Truth from Facts. This principle, derived from classical materialist dialectics, acts as an overarching constraint: conclusions must follow evidence, facts must be separated from inferences, and only verified results count as complete.

The nine methods are organized into three layers. The philosophical layer contains Contradiction Analysis (identifying main contradictions in a complex problem) and Practice-Cognition Cycle (iteration through practice, recognition, and re-practice). The working methods layer contains Investigation First (no conclusion without evidence), Mass Line (gather feedback, systematize, return for verification), and Criticism and Self-Criticism (review and improve completed work). The strategic tactics layer contains Protracted Strategy (plan for long tasks without rushing or giving up), Concentrate Forces (focus on one main objective), Spark Prairie Fire (build foundations before expanding), and Overall Planning (balance multiple objectives without one-sidedness).

The intended users are developers who use AI coding tools and want those tools to apply more deliberate analysis on complex tasks. The package supports Claude Code, Cursor, Codex, OpenCode, OpenClaw, Hermes, and Nanobot.

Installation: npx, Marketplace, and Manual Copy

Installation happens through three paths.

The recommended path for all platforms is:

npx qiushi-skill

This command runs an interactive detection step that identifies which supported AI coding tools are installed and writes the skills to their corresponding directories. You can also target specific platforms directly:

npx qiushi-skill install --target claude-code --scope user
npx qiushi-skill install --target cursor,codex,opencode,openclaw,hermes,nanobot --scope user

For Claude Code specifically, the package is also available through the Claude Code Marketplace:

/plugin marketplace add HughYau/qiushi-skill
/plugin install qiushi-skill@qiushi-skill

For environments without Node.js, copying the skills/ directory contents into the host tool's skills directory manually achieves the same result. The package is published on npm as `qiushi-skill` at version 2.0.0 and requires Node.js 18.17 or later.

To verify the installation worked correctly:

npx qiushi-skill validate

On systems without Node.js, `tests/validate.sh` (macOS and Linux) or `tests/validate.ps1` (Windows) perform the same check.

How the Skills Work at Runtime

When a session starts in a supported host tool, a small resident kernel of approximately 50 lines is injected automatically. This kernel enforces the Seek Truth from Facts principle through four hard rules: conclusions must follow evidence, the agent must distinguish facts from inferences and unknowns, a task is complete only after verification, and obstacles should trigger diagnosis rather than giving up.

After applying the base constraint, the agent evaluates the current task to decide whether calling any of the nine methodology skills adds value. The README states explicitly that direct execution tasks do not trigger any downstream skill; the methodology layer is reserved for cases where the task is complex enough to benefit from structured analysis.

Each skill file is structured in five sections: when to use it and when not to, the operational procedure (specific actions to take), the output template (the observable artifact), hard constraints (behaviors that cannot be bypassed), and handoff (what typically comes next). Reference materials such as original classical texts, scenario guides, and phase indicators are kept in separate files and loaded on demand rather than occupying the resident context.

The skills can also be invoked manually through slash commands. Eleven commands are available, including `/contradiction-analysis`, `/investigation-first`, `/concentrate-forces`, and `/workflows` for combining multiple methods.

Source Organization and the Subagent Architecture

The repository structure groups skills by directory under skills/, with each skill directory containing at minimum a SKILL.md file, supporting reference materials, and where applicable a set of subagents under agents/.

Two specialized subagents are included. The `investigator.md` subagent is a read-only research agent that produces a structured report with three columns: facts, inferences, and unknowns. Multiple instances of this agent can be dispatched in parallel by the main agent for concurrent investigation. The `self-critic.md` subagent reviews completed work from a fresh context without access to the author's own account of what was done, producing criticisms with attached evidence and improvement suggestions.

Commands in the commands/ directory provide manual entry points for each skill. In hosts that support Markdown slash commands, these can be called directly. In hosts that do not support a command directory, the corresponding SKILL.md file can be opened or loaded directly.

A hooks/ directory handles session injection. The hooks.json file specifies when the session-start script runs, and both a POSIX shell script and a Windows PowerShell script are included for cross-platform compatibility.

The Claude Code plugin configuration is in .claude-plugin/plugin.json and marketplace.json. The Cursor plugin configuration is in .cursor-plugin/plugin.json.

Methodology Basis and What the Project Is Not

The nine methods and the Seek Truth from Facts principle are drawn from published classical materialist dialectics texts. Each method's SKILL.md file cites the original source text and chapter. An original-texts.md file in each skill directory contains the relevant passages from the source works, clearly attributed and not loaded into the agent context by default.

The README explicitly states two things this project is not. First, it is not propaganda: the methods are general problem-solving frameworks applicable to any analytical task, and the project treats them as methodology research. Second, it is not personality distillation, which is a different category of project that attempts to simulate a historical figure's behavior. The README draws a clear line between extracting methodology from published texts and attempting to recreate a personality.

The closest comparable project listed in the README is obra/superpowers, an agentic skills framework for software development methodology. The difference is scope: obra/superpowers focuses on software development practices while Qiushi Skill focuses on the analytical reasoning layer that precedes and guides any task, including but not limited to software work.

Limitations and Maintenance Status

The skills work within the constraints of the host tool. If a host has its own equivalent workflow for a given methodology, the skill documentation instructs the agent to defer to the host's approach rather than duplicating it. Teams using heavily customized agent configurations should verify that the skill injection does not conflict with existing hooks or custom instructions.

The resident kernel of approximately 50 lines adds to every session's context regardless of whether the methodology is invoked. On sessions where the agent only performs simple, direct tasks, this overhead is present but the downstream skills do not fire. For very context-sensitive workflows with strict token budgets, this is a consideration.

The last push to the repository was on 2026-09-06. The project is MIT licensed and published on npm. No GitHub releases exist; versioning follows the package.json version field.

Editorial conclusion

Qiushi Skill is a practical option for teams that want their AI coding agents to apply structured analytical methodology rather than producing quick, unverified answers. The installation takes a single command across all supported platforms. The package is MIT licensed and version 2.0.0, with the last push on 2026-09-06. The skills are most valuable for complex, multi-step tasks where the agent needs to investigate before acting; the README notes that for direct execution tasks the skills do not trigger at all, which avoids overhead on straightforward requests.

Frequently asked questions

Official sources

1. HughYau/qiushi-skill on GitHub
2. Issues
3. License: MIT
4. Project website
5. README