shincbm

Claude Beyond Code: Intent Expression and Agent Skills

Sun, 15 Feb 2026 00:00:00 +0000

I feel like productive developers have often resisted documentation: it interrupts the flow of getting code out of your head and into the editor. Interestingly, my recent experience of agentic coding is flipping this. When an agent writes the code, the bottleneck moves upstream to: “how clearly can I express the idea?” Documentation isn’t the interruption anymore, it’s leverage over the agent.

This post introduces a set of skills for agentic document elicitation and review. The skills are reusable instruction files for Claude Code, covering document creation and review. First, I’d like to present why I’ve created them.

The leverage shift

The traditional developer’s fulcrum has been mental clarity: keep the system idea in your head, design and refine in place. The lever moves well-formed code from brain to editor at speed.

In that model documentation was an interruption, at best a necessary evil. Interrupting that flow to “document it” was disruptive. You did it because collaboration required it, not because it helped you think.

But there is a trap here. A productive developer who tries to slot an agent into their existing mental-clarity workflow may actually lose productivity. New leverage doesn’t come from keeping the idea in your head and using the agent as a faster typist. It comes from changing the workflow. Going back to documentation, this is a way to share the idea directly.

In the new model, the agentic developer’s fulcrum is agentic clarity: externalize the idea so completely that the lever moves code from agent to codebase without pulling a human back into the loop.

Here, documentation can be an enabler, or at least that’s the argument I’ll make. When an agent handles the code, human language becomes the input, not the afterthought.

Plan mode in agentic coding tools is one path to agentic clarity, but plans are one-off. A living document in the workspace gives both agents and humans a shared, versioned reference. Iterative prompting works for contained tasks, but anything that persists (an API consumed by multiple agents, a design revisited across sprints) benefits from a document under configuration management rather than a conversation that evaporates. The development lifecycle sees the same ideas surface repeatedly.

A Structured Review Skill

Firstly, this approach relies on docs as code: maintaining documentation as an artifact alongside source code. You can port the skills to a different workflow, but in my opinion that reduces leverage and adds friction.

At every stage of the development lifecycle, ask: what is the source of information? Is it the developer’s novel idea, or can the agent infer it from standard approaches? With three skills I form a pipeline to capture the relevant information and filter the noise:

Skill	Action	Information	Noise	Refinement
flesh-out	Generate	Expand	Adds (controlled)	Raw ore → shaped material
review-steps	Polish	Preserve	Reduce	Remove impurities
strong-edit	Critique	Enhance	Reduce	Stress-test the structure

A typical pipeline runs flesh-out → review-steps → strong-edit, but the skills can be applied in any order; each one detects what the document needs. All three are broken into numbered stages with developer checkpoints. The agent stops after each stage and waits for approval before proceeding.

graph LR
    raw[Raw notes] --> FO

    subgraph FO ["/flesh-out"]
        fo0(Stage 0
Extract ideas) --> fo1(Stage 1
Research)
        fo1 --> fo2(Stage 2
Structure)
        fo2 --> fo3(Stage 3
Polish)
    end

    FO --> draft[Structured draft]
    draft --> RS

    subgraph RS ["/review-steps"]
        rs0(Stage 0
Language) --> rs1(Stage 1
Clarity)
        rs1 --> rs2(Stage 2
Structure)
        rs2 --> rs3(Stage 3
Consistency)
        rs3 --> rs4(Stage 4
Best practice)
        rs4 --> rs5(Stage 5
Tidy up)
        rs5 --> rs6(Stage 6
Verify links)
    end

    RS --> reviewed[Reviewed draft]
    reviewed --> SE

    subgraph SE ["/strong-edit"]
        se0(Stage 0
Core argument) --> se1(Stage 1
Structure)
        se1 --> se2(Stage 2
Relevance)
        se2 --> se3(Stage 3
Challenge)
        se3 --> se4(Stage 4
Readability)
        se4 --> se5(Stage 5
Edits)
    end

    SE --> final[Final document]

    style raw fill:#f9f,stroke:#333
    style final fill:#9f9,stroke:#333

Writing and editing in stages

What I’m trying to do is find the perfect division of labor. The human brings the problem and the engineering; the agent brings industry techniques, frameworks, and best practices. That allows you to focus your time on what is not in the model’s training data and leverage the agent for everything else.

To do that, on top of breaking editing into three skills, each has a series of stages.

flesh-out: from raw notes to structured content: Takes a skeleton of ideas (bullet points, stream-of-consciousness notes, half-formed thoughts) and expands them into a structured document. The agent first confirms it understands the developer’s intent, then researches, structures, polishes, and tidies up. The risk here is meaning distortion. Raw notes are ambiguous, and assumptions compound. Stage 0 (extract core ideas, developer confirms) exists specifically to catch misunderstandings before they propagate.
review-steps: polish and verify: Takes a structured draft and improves it: language consistency, conceptual clarity, structural compliance, comparison against industry best practice, and link verification. The agent handles mechanical checks and research; the developer holds final authority on judgment calls. Stages 0-4 move progressively from minor editing to conceptual validation. Stage 5 tidies up references; Stage 6 verifies every URL resolves and that agent-sourced references support the claims made.
strong-edit: challenge the content: Takes a complete draft and critiques it: structure, relevance, argument strength, readability. Stages 0-4 are critique only; no edits are made to the document. The agent identifies weaknesses; the developer decides what matters. Edits happen in Stage 5 after the critique is agreed.

Try it out

Clone https://github.com/nakane1chome/claude-skills
Install to your home dir: ./install.sh and follow the prompts
Already have a completed document? Try /review-steps or /strong-edit
Starting from scratch? Write a quick and dirty memo and try /flesh-out
The collection includes other skills; try /review-skill on one of your Claude Code skill files to review its structure and coverage

Caveats & Risks

It’s not perfect yet; some of the issues with the flow are:

False sense of completeness: A large language model (LLM) will confidently proclaim your work to be exceptional and ready to publish. The strong-edit skill exists partly to counter this: the philosophy section puts it directly: “Challenge the author’s assumptions. If something seems unclear, it may be unclear, or wrong. Don’t fix; question.”
Hallucinations and trust: The staged approach constrains this risk but does not eliminate it (see This article for a concrete example from this very post). At every step, the source of information (human idea or agent inference) should be identifiable. The staged process keeps the human engaged rather than rubber-stamping, but link and fact verification remain the developer’s job. Apparently developer trust in AI accuracy remains low (only 43% in recent surveys), for me the key here is checkpoints and grounding, which is done via staged editing.
Sensitivity to generated documents: Some people will reject anything they believe was written by AI, regardless of how it was actually produced. These skills make the human the source of novel information and the agent an editor, but that distinction may not matter to everyone.
Speed: It’s deliberately supervised, which can be slow.

Final Words

I’ve heard a Japanese term for meetings where people talk past each other without a shared grounding: 空中戦 (kūchūsen, “air battle”). Opinions fly overhead like fighter jets; there’s a lot of noise, nobody lands a hit, and the meeting ends with no decisions. The antonym is 地上戦 (chijōsen, “ground battle”); discussion grounded in visible, concrete materials where participants work through specifics together.

Raw ideas create kūchūsen. An air battle with an agent is only going to slow you down! Ground the idea first, and let the agent do what it’s good at.

Afterword: Observations from practice

This post

It started as 727 words of raw notes with partial structure. /flesh-out expanded that to 2279 words, tripling the length. The structure held but the agent added padding and hedging.

Human editing cut about 12% (2279 to 2007 words), removing agent-generated filler. /review-steps added the METR productivity trap reference, the developer trust data, and the afterword observations, bringing the word count back up to 2257.

/strong-edit sharpened the opening to lead with the thesis, tightened the leverage shift sentences, and replaced false binary framing. Final word count: ~1930.

Then a link turned up 404. During /review-steps, the agent had added a reference with a fabricated URL. The domain didn’t exist. The link survived human editing and /strong-edit because at every stage the reviewer was evaluating structure, argument, and voice — nobody was clicking links. Stage 6 (verify links) was added to the review-steps skill as a direct result of this failure.

Rough attribution of the final post:

	Human	Agent	Co-created
Ideas and arguments	~95%	~5%	—
Research and references	~50%	~50%	—
Prose (the actual sentences)	~5%	~60%	~35%
Editorial decisions	100%	0%	—

In general

Applied mostly to design and architecture documents, working with Claude Code Opus 4.5 and skills-as-files:

Scaffolding precision: Claude sticks precisely to the staged workflow when actions are defined as skills. This was not the case when just adding project guidelines to CLAUDE.md or AGENTS.md; in both cases the agent did not consistently apply the scaffold.
Mode detection: The agent identifies when a review is not appropriate — e.g., when a largely complete piece would benefit more from strong-edit than review-steps.
Term sensitivity: “Review” signals preservation; “flesh-out” signals generation; “strong-edit” signals critique. The difference in vocabulary shapes the agent’s behavior significantly.

Standout steps

Review vs industry best practice

Stage 4 of review-steps sends the agent to search for relevant frameworks and approaches in the domain, then compares the document against what it finds. Not a substitute for expert review; it’s an automated search with a structured summary. But you won’t be caught off-guard by an obvious gap that a five-minute search would have revealed.

This stage tends to pull in a lot of information. I ask the agent to generate a separate report and keep it out of the document under review. Without that constraint, the agent folds unnecessary details from the research into the document.

Stage 0: Extract Idea (flesh-out) and Core Argument (strong-edit)

As a rough guide, the agent gets around 70% of these stages correct and then asks questions to clarify the remainder. It produces a concise summary of what it understands and what needs clarification, and this is very insightful to interact with.

Flesh-out catching a wrong assumption

On a separate project, I wrote 169 words of raw notes for a CPU model design. Key assumption: “Only the kernel uses the ISA directly in supervisor space.”

/flesh-out expanded to a 1962-word design document (11.6x). On a second pass, the agent researched the actual source tree and found 21+ user-space assembly files across 10 library modules and 3 applications. The assumption was wrong: the ISA boundary was a language boundary, not a privilege boundary.

This changed the design. The context diagram was rewritten from a two-path flow to a 2x2 matrix (kernel/user x assembler/pascal). A fundamental misunderstanding was caught before it shaped the implementation.

Future Extension

The review process produces a specification with a known complexity profile. That profile could select the agent: a high-end model for architectural work, a lightweight model for boilerplate. Model selection as a downstream output of document review, not a separate decision.

Review reports

OpenCL Learning Exercise — Image Transform

Sun, 11 Jan 2026 00:00:00 +0000

This is an old tool written to play with OpenCL (Open Computing Language) on x86_64 and aarch64 machines.

https://github.com/nakane1chome/opencl-learn/tree/master

ImageXform is a command-line tool for learning and experimenting with OpenCL by applying GPU-accelerated kernels to images. It provides a visual, hands-on way to understand OpenCL programming by transforming PNG or JPG images through custom or example kernels.

The tool handles all the OpenCL and image conversion boilerplate (device selection, context creation, buffer management) so the kernel can be launched and results inspected.

It is designed for learning OpenCL concepts like parallel processing, memory management, and kernel optimization through immediate visual feedback.

Code and build system have been slightly modernized after fixing a few bugs.

Example Usage

Transform an image to grayscale:

# Build the project (one-time setup)
make build-amd64

# Run grayscale conversion
cd build.amd64/imgxform
./imagexform -p grayscale.cl -i test_in.png -o output_gray.png

# The tool will:
# 1. Load test_in.png
# 2. Compile grayscale.cl kernel
# 3. Execute it on your OpenCL device (GPU/CPU)
# 4. Save the result to output_gray.png

You can substitute any .cl kernel file to experiment with different transformations like edge detection (edge_3x3.cl) or create your own custom kernels.

Original timestamps for Git

Mon, 13 Jan 2025 00:00:00 +0000

How to commit files to Git with the original timestamp.

(Or an alternative to https://githistorygenerator.com/ that can make you less employable by revealing side projects from the last century.)

I had a few copies of an old project amiga-scroller on an old hard disk image. The files were checked into RCS back in 1996 and 1997. I’d like to move them to Git and see if it can be compiled. As the files have been preserved for so long I’d like to keep the original timestamps.

Assuming we have a folder with some old files, and a repo on GitHub, first init the local folder and link to remote.

git init
git remote add origin git@github.com:nakane1chome/amiga-scroller.git

Option 1 - Set GIT_AUTHOR_DATE and GIT_COMMITTER_DATE

The timestamp can be associated with each file using find -printf "%T@ %p\n".

Start with the oldest version of the source tree. Add and then commit the file to git.

for f in `find .  -type f -printf "%T@ %p\n" | grep -v .git | sort | cut -f2 -d' '`; do  
    git add $f;
     GIT_AUTHOR_DATE="`stat -c %y $f `" GIT_COMMITTER_DATE="`stat -c %y $f `" \
        git commit -m "Add $f" ; 
done

At this point copy the newer version of the source into the repo, repeat for just the modified files.

for f in `git status | grep modified | cut -f2 -d':'`; do 
    git add $f;
     GIT_AUTHOR_DATE="`stat -c %y $f `" GIT_COMMITTER_DATE="`stat -c %y $f `" \
        git commit -m "Update $f" ;
done

More examples here.

Option 2 - Libfaketime - can be used with any application.

Install libfaketime. This will replace the dynamic linking for the standard time functions using LD_PRELOAD.