Agent Steering

Agent Steering & Skills

strut ships with AI agent context — a steering doc set and one operational skill — that help coding assistants understand the project and execute strut workflows correctly. These work with any agent that supports context files: Kiro, Claude Code, Cursor, Windsurf, Copilot, Zed, Cline, and others.

Two Types of Context

Steering (always-on)

Steering files provide background context that's always available to the agent. They describe conventions, architecture, and patterns the agent should follow.

Located in .kiro/steering/:

File	What it provides
code-conventions.md	Shell module standards, function naming, error handling, testing patterns
stack-management.md	CLI usage, core concepts, essential commands, service profiles
development-workflow.md	Development workflow patterns for contributing to strut

Steering files use frontmatter to control when they're loaded:

• inclusion: auto — always included (stack-management, development-workflow)
• inclusion: fileMatch with fileMatchPattern — included when matching files are open (code-conventions loads when editing lib/*.sh or tests/*.bats)

Skills (on-demand)

A single strut skill covers every operational domain, with progressive-disclosure reference files the agent loads only when relevant (since v0.31.1 — earlier versions shipped 9 separate skills, since consolidated into one per the Agent Skills spec).

Located in .kiro/skills/strut/:

.kiro/skills/strut/
├── SKILL.md                    # Router: when to use this skill, links to references
└── references/
    ├── deployment.md
    ├── debugging.md
    ├── backups.md
    ├── secrets.md
    ├── drift.md
    ├── monitoring.md
    ├── domains-ssl.md
    ├── validation.md
    └── migration.md

SKILL.md's frontmatter (name, description) is what the agent reads to decide whether to load the skill at all; the body then points into references/ for the specific procedure needed, rather than loading everything up front.

Installing Agent Context

During strut installation

The installer (install.sh) mentions available skills after installation. Use --no-skills to suppress:

# Default install — shows skills notice
curl -fsSL https://raw.githubusercontent.com/gfargo/strut/main/install.sh | bash

# Suppress skills notice
curl -fsSL https://raw.githubusercontent.com/gfargo/strut/main/install.sh | bash -s -- --no-skills

Using strut skills

The skills command installs context files in the format your editor expects:

strut skills list                          # See available steering and skills
strut skills install                       # Kiro (default)
strut skills install --format claude       # Claude Code
strut skills install --format cursor       # Cursor
strut skills install --format copilot      # GitHub Copilot
strut skills install --format all          # All formats at once

How skill installation works (since v0.35.0)

For kiro, claude, cursor, windsurf, and copilot, strut skills install delegates the skill directory to agent-add when npx is available — the skill lands as a real, on-demand Agent Skills directory (e.g. .claude/skills/strut/, .cursor/skills/strut/) instead of being permanently inlined into a rules file. Steering content still goes into that editor's own file (CLAUDE.md, .cursorrules, etc.) since agent-add has no equivalent concept for always-on context.

If npx isn't available, or the agent-add call fails for any reason, strut falls back automatically to copying the skill directory directly (kiro/claude) or flattening it into the rules file (cursor/windsurf/copilot) — the same behavior every format used before v0.35.0. Nothing errors or requires network access to work; agent-add is strictly an enhancement, not a hard dependency.

zed, cline, and agents have no agent-add host to target, so they always flatten steering + skill content into one file, as before.

Manual copy or symlink

# Copy (snapshot — won't update with strut upgrade)
cp -r ~/.strut/.kiro/skills/strut <your-project>/.kiro/skills/strut

# Symlink (auto-updates with strut upgrade)
mkdir -p <your-project>/.kiro/skills
ln -s ~/.strut/.kiro/skills/strut <your-project>/.kiro/skills/strut

Supported Formats

Format	Steering destination	Skill destination
kiro	.kiro/steering/strut-*.md	.kiro/skills/strut/ (via agent-add, falls back to direct copy)
claude	CLAUDE.md	.claude/skills/strut/ (via agent-add, falls back to direct copy)
cursor	.cursorrules	.cursor/skills/strut/ (via agent-add, falls back to inline .cursorrules)
windsurf	.windsurfrules	.windsurf/skills/strut/ (via agent-add, falls back to inline .windsurfrules)
copilot	.github/copilot-instructions.md	.github/skills/strut/ (via agent-add, falls back to inline copilot-instructions.md)
zed	.rules	.rules (appended)
cline	.clinerules	.clinerules (appended)
agents	AGENTS.md	AGENTS.md (appended)
generic	docs/strut-context.md	docs/strut-skills.md

Writing Custom Skills

Add a new reference file under .kiro/skills/strut/references/ for a new operational domain, and point to it from SKILL.md's body — or, for something unrelated to strut's own domain, create an entirely separate skill directory elsewhere under .kiro/skills/:

.kiro/skills/my-custom-workflow/
└── SKILL.md

With frontmatter:

---
name: my-custom-workflow
description: Description of when to use this skill.
---

# My Custom Workflow

Step-by-step commands here...

Run strut skills install to propagate it to your project — every SKILL.md-rooted directory under .kiro/skills/ gets installed, not just the built-in strut skill.

Want support for another tool?

agent-add already covers a wide range of editors beyond what strut lists explicit format names for — check its host compatibility table if your tool isn't in the list above. If it's genuinely missing:

• Open an issue at github.com/gfargo/strut/issues with the tool name and how it loads context files
• Edit this wiki page directly if you know the format and want to contribute
• Submit a PR adding a new format handler to lib/cmd_skills.sh — each format is a small function (~15 lines)

Related

• CLI Reference — strut skills command reference
• MCP Server — a complementary integration: exposes strut operations as MCP tools for AI agents, also installed via agent-add
• Contributing — Development setup
• Code Conventions — What the steering docs enforce