content-actionability-score¶

Score instruction files on actionability (verb density, commands, file references)


Severity	info (auto)
Autofix	-
Since	v0.7.0
Category	Content Intelligence

Why¶

A low actionability score means the file reads more like documentation than instructions. Models follow imperative statements with specific commands and file paths far more reliably than passive descriptions. Instruction files that score below the threshold are likely to be partially ignored because the model cannot translate vague prose into concrete actions.

Examples¶

Bad:

The project has a testing framework that should be used.
Code quality is important for this repository.

Good:

Run `npm test` before committing.
Use ESLint (`npm run lint`) to check code quality.
See `src/config.ts` for the project's shared configuration.

How to fix¶

Add imperative verbs, inline commands (backticked), and file path references. Replace descriptions with direct instructions. A coding agent can rewrite low-scoring files automatically.

Configuration¶

rules:
  content-actionability-score:
    enabled: auto  # true | false | auto
    severity: info

Research Basis¶

Scores instruction files on actionability — verb density, command references, file path mentions.

Instruction files full of passive descriptions ("the system architecture is microservices-based") give the model no direction. Files with imperative verbs ("use microservices architecture for all new services") give clear marching orders.

Google's Gemini prompting guide states: "Always remember to include a verb or command as part of your task — this is the most important part of a prompt." The Bsharat et al. study confirmed that imperative framing is one of the strongest predictors of prompt quality.

References:

Bsharat et al., Principled Instructions Are All You Need — Imperative framing as a quality predictor
Google Workspace Gemini Prompt Guide — "Always include a verb or command"
OpenAI Prompt Engineering Guide — "Specify the steps required to complete a task"
IBM Prompt Engineering Techniques — "The request should be an action verb: 'analyze', 'summarize', 'classify'"

Run skillsaw explain content-actionability-score to see this documentation and the rule's effective configuration in your terminal.