How to Add a Stokik Skill to Your Codebase

Connecting Claude Code or Codex to Stokik with MCP is a one-time setup. Getting consistent behaviour from those agents — across every developer, every session, every week — is a different problem.

Without written instructions, the agent has to rediscover how to use Stokik on its own each time. It asks “which project should I use?” even when the answer is obvious from the repo name. It creates tasks without descriptions. It sets statuses incorrectly. It opens an agent run, does the work, and forgets to close it. Two sessions later, a developer creates the same task again because no one checked for duplicates.

The fix is simple: write the instructions once, check them into the repo, and let every session inherit them.

This post explains how to do that, and what to put in the file.

If you haven’t connected Stokik MCP yet, start with How to Connect Claude and Codex to Stokik with MCP. This post picks up where that one leaves off.

The problem with session-level prompts

Most teams start with prompts. Someone figures out a good sequence of instructions — list the project, read the tasks, check for duplicates before creating — and pastes it into their session. It works well. They share it in Slack. Other developers use it for a week, then forget it.

Session-level prompts have a structural problem: they only exist in the session where they were typed. The next developer who runs Claude Code in the same repo starts from scratch. They do not get the benefit of what the first developer worked out. Even the same developer, in a new session two days later, has to remember to paste the prompt back in.

The agent is capable of better behaviour. The problem is not the agent — it is the absence of standing instructions.

Without guidance, a capable agent will:

• Ask “which Stokik project should I use?” every session, even when the project name matches the repo
• Create tasks with generic labels like “Look into X” instead of outcome-focused imperatives
• Set tasks to in_progress immediately instead of staging them at todo first
• Create duplicate tasks because it did not check for existing ones
• Open an agent run at the start of work and never close it
• Guess project or task IDs instead of looking them up

None of these are hard problems for the agent. They are gaps that clear instructions fill in seconds.

The goal is to write those instructions once, in a file that lives in the repo, so every session — every developer, every branch, every agent invocation — follows the same conventions automatically.

What a Stokik skill file is

A skill file is a markdown document containing prose instructions that the agent reads at the start of a session.

It is not a configuration file. There are no structured fields to fill in, no schema to validate against, no runtime parsing. It is written instructions, in plain language, that the agent follows the same way it follows any other part of your project’s documentation. The agent reads it because it reads all the project documentation that tells it how to work in this codebase.

Where it lives depends on which agent you are using:

• Claude Code: add the file path to CLAUDE.md using @filename syntax, or reference it from an @AGENTS.md include. Claude Code reads any file referenced with @ in CLAUDE.md at the start of every session.
• Codex: add the file at .codex/commands/<skill-name>.md. Codex loads command files from that directory automatically.
• Either agent: you can also inline the instructions directly in CLAUDE.md or AGENTS.md if you prefer one file over many.

The file can be as short or as detailed as your team needs. A minimal skill file covers three things: how to find the right project without asking, what a good task looks like, and how to handle agent runs. A detailed skill file also covers document conventions, status rules, canvas positioning, and explicit lists of things never to do.

The agent reads it at the start of every session, so the behaviour is consistent across the whole team with no per-developer setup beyond the initial MCP connection.

Core principle: discover before acting

Before the agent can follow any Stokik conventions, it needs to know what tools are available. This sounds obvious, but it is worth encoding explicitly.

Tool names and parameter shapes can change over time. An agent that hardcodes assumptions about tool names will fail silently when those names change. The right behaviour is to check what is available before using anything.

The instruction to write is:

At the start of each session where Stokik MCP may be used, check what Stokik
MCP tools are available before using any of them. Do not assume tool names
or parameter shapes. If the tools you expect are not present, say so before
proceeding.

This prevents an entire class of silent failures. The agent lists the available tools, confirms they match expectations, and then proceeds. If something has changed — a tool was renamed, a parameter was added — the agent surfaces it immediately instead of failing halfway through a multi-step operation.

The same principle extends to project and task IDs. The agent should never guess or hardcode an ID. IDs are opaque identifiers. The correct behaviour is to always look up the project or task by name, then use the returned ID for subsequent operations.

Never guess or hardcode a Stokik project ID, task ID, or document ID.
Always look up the resource by name, then use the returned ID.

These two instructions together — check tool availability, look up IDs by name — prevent the most common categories of Stokik agent failures.

Resolving context without asking constantly

The most noticeable failure mode of an un-instructed agent is the constant question: “which project should I use?” It is asked even when the answer is obvious. In a repo named checkout-revamp, there is almost certainly a Stokik project named something close to that. The agent should try to figure it out before asking.

The instruction to encode is a decision tree. Write it out explicitly in the skill file so the agent knows exactly what order to try things:

To determine which Stokik project to use, work through the following in order:

1. Check conversation history. Was a project or task already mentioned in this
   session? If yes, use that.

2. Check the working directory. Does the repo name or the directory name match
   or closely resemble a Stokik project name? If there is a clear single match,
   use it.

3. Check the user's request. Is a task name, feature name, or project name
   mentioned explicitly? Use that to search.

4. If a single match is found by any of the above, act on it directly without
   asking.

5. If multiple plausible matches are found, show the options and ask the user
   to choose.

6. If no match is found, say so clearly and ask for clarification.

Do not ask "which project should I use?" unless you have genuinely exhausted
steps 1 through 3 and found no clear match.

This decision tree dramatically reduces unnecessary questions. The agent tries to resolve context from what it already knows before escalating to a question. When it does ask, it is because there is genuine ambiguity — not laziness.

The same logic applies to tasks. If a user says “create a task for the fix we just discussed,” the agent should use the conversation history to understand what fix is being referred to, construct an appropriate label, and create the task — not ask “which task did you mean?” when the answer is in the last three messages.

When the agent does ask, it should show its work. “I found two projects that could match: Checkout Revamp and Checkout Analytics. Which one?” is a useful question. “Which project?” with no context is not.

Task creation conventions

Creating a task sounds simple. In practice, agents create a lot of low-quality tasks that require manual cleanup. The label is too vague to be actionable, the description is missing, the status is wrong. Encoding conventions for task creation is one of the highest-return parts of a skill file.

Label format

Labels should be short, imperative, and outcome-focused.

Good: Fix race condition in CheckoutController, Add validation to billing address form, Migrate user table to new schema

Not useful: Look at checkout issue, Billing form stuff, Database migration?

The test is: can someone read the label and understand what done looks like? If the answer is no, the label is not finished.

Write this as a concrete rule:

Task labels must be short and imperative. Use the form "Verb Noun in Location"
where Location is the relevant class, component, or module. The label should
make clear what done looks like without needing to open the task.

Status on creation

Tasks should never be created with the status in_progress. That status means a developer is actively working on it right now. Creating a task and immediately setting it to in_progress bypasses the planning step and makes it impossible to see what is in the queue.

The correct statuses at creation are:

• todo: the task is defined, scoped, and ready to be picked up
• scope: the task represents work that still needs to be sized or designed before it is ready

When creating a task, set its status to either:
- todo: if the work is clearly defined and ready to implement
- scope: if the work still needs investigation or design before implementation begins

Never set a task to in_progress at creation time.

Descriptions for non-trivial work

A task label is not a description. For anything beyond a trivial one-line change, the description should give a developer enough context to start the work without asking questions.

The format that works well in practice has three sections:

**Problem**
[What is wrong, unclear, or missing. Reference the class or method name, not
a line number. Lines change; names are stable.]

**Action Items**
- [Specific steps to complete the work]
- [Each item should be independently completable]

**References**
- [Linked documents, related tasks, or relevant context]

Write this as a rule in the skill file:

For any non-trivial task, the description is required. It must include:

1. Problem: a clear statement of what needs to change. Reference classes and
   method names, never line numbers.
2. Action Items: a list of specific steps.
3. References: linked documents or related tasks, if any exist.

A task with no description is not ready to be created.

The “no line numbers” rule deserves its own line because it is easy to forget. Line numbers look precise but become wrong immediately after any refactor. Class and method names are stable references that survive code changes.

Canvas positioning

If you are creating multiple tasks in one session, the agent should position them in a way that is visually meaningful rather than stacking them on top of each other.

When creating multiple tasks:
- Group related tasks near each other on the canvas
- Place higher-priority or blocking tasks above tasks they block
- Space tasks approximately 200 units apart to avoid overlap
- Check existing task positions before placing new ones

Checking for duplicates

Before creating any task, the agent should check whether a task covering the same work already exists.

Before creating a task, check whether an existing task in the project already
covers the same work. If a close match exists, prefer updating or linking it
over creating a duplicate.

Document conventions and linking

Documents are how context survives beyond a single session. A task describes what to do; a document explains why, what was found during investigation, and what the plan looks like.

Title prefixes

Title prefixes communicate the status and nature of a document without opening it. Use them consistently:

• Investigation: <topic> — analysis of a problem, findings, open questions
• Scope: <feature> — design and sizing before implementation begins
• Design: <component> — architectural or UX design decisions
• Fix: <description> — a concrete fix proposal, including before/after

All Stokik documents must use a title prefix that communicates document type:
Investigation:, Scope:, Design:, or Fix:

Status line

Every document should have a status line near the top. This tells anyone who opens it whether the work is still in progress or ready to act on.

Status: Ready to implement

or:

Status: Open — requires investigation

or:

Status: Ready for review

Write it as a required field:

Every document must include a Status: line near the top, immediately after
any introduction. Valid values: "Ready to implement", "Open — requires
investigation", "Ready for review", "Superseded".

Document structure

A useful document skeleton for a fix or investigation:

## Summary

[One paragraph explaining the problem and the proposed solution or finding.]

Status: [Ready to implement | Open — requires investigation | Ready for review]

## Problem

[Detailed description of the issue. Reference class and method names, not
line numbers.]

## Before

[Code snippet showing the current behaviour, if applicable.]

## After

[Code snippet showing the proposed change, if applicable.]

## Open Questions

[Any unresolved questions that need answers before implementation can begin.
Remove this section when all questions are resolved.]

## References

[Links to related tasks, documents, or external resources.]

The Open Questions section matters. When an agent creates a document for work it does not fully understand, it should record what it does not know rather than omitting the uncertainty. A document with clear open questions is more useful than a document that projects false confidence.

Linking documents to tasks

A document is only useful if someone can find it. Every document should be linked to its primary task immediately after creation.

After creating a document, link it to its primary task in the same operation.
A document that is not linked to a task will not be visible in the task context.

Agent run lifecycle and common mistakes

Agent runs are how Stokik shows what an external client is doing. They are worth using, but only if they are opened and closed correctly.

Lifecycle

The correct lifecycle is:

1. At the start of multi-step work, start an agent run
2. Record progress at meaningful checkpoints — not after every individual action, but after completing a meaningful unit of work
3. When the work is finished, complete the run

The failure mode to prevent is runs that are opened and never closed. A stale open run is misleading — it looks like work is still in progress when it is not.

Agent run lifecycle:
1. Start a run at the beginning of any multi-step Stokik operation.
2. Record progress after each meaningful unit of work (not after every
   individual tool call).
3. Always complete or fail the run before the session ends.
4. Never leave a run in an open state.

Common mistakes to make explicit

Some mistakes are common enough that it is worth listing them directly in the skill file as explicit prohibitions:

Never do the following:
- Guess or hardcode a Stokik project ID, task ID, or document ID
- Reference a line number in any task description or document
- Create a task without a description for non-trivial work
- Set a task status to in_progress at creation time
- Create a new task without first checking for existing tasks that cover the
  same work
- Leave an agent run open at the end of a session
- Create a document without linking it to its primary task

The list form is deliberate. The agent can scan it quickly, and each item is an independent rule that does not require understanding the others.

Putting it together: a full example skill file

Here is what a complete Stokik skill file looks like. This is the kind of file to drop into .codex/commands/stokik.md or reference from CLAUDE.md:

# Stokik MCP Instructions

## Setup

At the start of each session where Stokik MCP may be used, check what Stokik
MCP tools are available before using any of them. Do not assume tool names or
parameter shapes. If expected tools are not present, say so before proceeding.

Never guess or hardcode a Stokik project ID, task ID, or document ID. Always
look up the resource by name, then use the returned ID.

## Resolving context

To determine which Stokik project to use:

1. Check conversation history for a previously mentioned project or task.
2. Check the working directory name for a close match to a project name.
3. Check the current request for an explicit task or feature name.
4. Act directly on a single clear match.
5. If multiple matches exist, show them and ask.
6. If no match exists, say so and ask.

Do not ask "which project?" unless steps 1–3 have been tried and returned no
clear result.

## Task creation

Labels must be short, imperative, and outcome-focused. Use the form
"Verb Noun in Location". The label should make clear what done looks like.

Status at creation:
- todo: work is defined and ready to implement
- scope: work still needs investigation or design

Never set in_progress at creation.

For non-trivial tasks, the description is required and must include:
1. Problem: what needs to change. Reference class and method names, not line
   numbers.
2. Action Items: specific steps.
3. References: linked documents or related tasks.

Before creating a task, check for existing tasks that cover the same work.
When creating multiple tasks, space them ~200 units apart and group related
tasks near each other.

## Document conventions

Title prefixes: Investigation:, Scope:, Design:, Fix:

Every document must include a Status: line near the top.
Valid values: "Ready to implement", "Open — requires investigation",
"Ready for review", "Superseded".

After creating a document, link it to its primary task immediately.

## Agent runs

1. Start a run at the beginning of any multi-step operation.
2. Record progress after each meaningful unit of work.
3. Complete or fail the run before the session ends. Never leave it open.

## Never do

- Guess or hardcode IDs
- Reference line numbers
- Create non-trivial tasks without descriptions
- Set tasks to in_progress at creation
- Skip duplicate checks before creating tasks
- Leave agent runs open
- Create documents without linking them to a task

This file is around 350 words. It is short enough to read in full and specific enough to change actual agent behaviour.

What this changes

The skill file does not give the agent new capabilities. Claude Code and Codex can already read tasks, create documents, update statuses, and record progress. What the skill file changes is how reliably it uses those capabilities.

Without the file, behaviour depends on what each developer prompts. With the file, behaviour is consistent across every session, every developer, every branch. The agent checks for duplicates because the file says to. It uses the right status because the file defines what the right status is. It links documents to tasks because the file says to do it immediately after creation.

One file, checked into the repo, and the conventions your team agreed on become the default behaviour for every AI session that touches the codebase.

That is a different kind of leverage than a good prompt. A prompt helps one developer in one session. A skill file helps every developer in every session, without anyone needing to rediscover what the last developer worked out.