SystemSmith

Engineering methods for code, agents, and architecture.

SystemSmith turns recurring engineering judgment into reusable agent skills: how to scope work, review your own output, write durable docs, protect secrets, structure technical messages, reason about agentic systems, and build cleaner software and information architectures.

The repo exists so engineering methods can compound across tools instead of being re-explained in every session.

What It Helps With

• Turn tickets and vague requests into a rigorous engineering workflow.
• Review work before handing it back.
• Keep credentials and private material out of agent outputs.
• Write Markdown and technical messages clearly.
• Produce living artifacts that can be refreshed instead of going stale.
• Translate agentic-AI ideas into concrete runtime mechanics.

Install With skills.sh

List the skills in this repo:

npx skills add https://github.com/ArthurZakirov/SystemSmith --list

Install all skills for Codex on a machine:

npx skills add https://github.com/ArthurZakirov/SystemSmith --skill '*' -a codex -g -y

Install one specific skill:

npx skills add https://github.com/ArthurZakirov/SystemSmith --skill swe-method -a codex -g -y

Install As A Claude Code Plugin

/plugin marketplace add ArthurZakirov/SystemSmith
/plugin install systemsmith@arthur-zakirov

Claude Code plugin skills are namespaced by plugin name, for example:

/systemsmith:swe-method

Install As A Codex Plugin

This repo includes Codex plugin packaging:

• repo marketplace metadata at .agents/plugins/marketplace.json
• plugin manifest at .codex-plugin/plugin.json

Add the marketplace:

codex plugin marketplace add ArthurZakirov/SystemSmith

Then install from Codex with /plugins.

For local development from a cloned repo:

./scripts/setup-local-links.sh

Existing non-symlink paths are left untouched unless --force is used.

Included Skills

Generated from tracked skills/*/SKILL.md metadata.

Skill	Description
engineer-agentic-ai	Translate natural-language requests about AI-agent behavior, skills, MCP tools/servers, prompts, routing, context loading, memory, hooks, plugins, permissions, delegation, portability, or other agentic-system behavior into the concrete runtime mechanism and change surface. Use when a request is phrased as what the AI should understand/do rather than how the target harness actually observes, triggers, routes, persists, or enforces that behavior.
format-markdown	Create, edit, review, refactor, or rewrite Markdown artifacts while preserving meaning, valid syntax, navigability, and human reviewability. Use whenever work directly changes or reviews a Markdown file, including README.md, AGENTS.md, SKILL.md, reference docs, design docs, or Markdown produced from notes, transcripts, scratch text, or rough drafts.
information-representation-design	Choose or review the representation form for information that will already be shown: table, list, hierarchy, prose, diagram, code abstraction, chart, or another structure. Use when the same content could be organized in multiple ways and readability, comparison, scanning, or structural clarity depends on the representation.
living-artifacts	Apply when producing any markdown artifact for someone else (or future-you) to read — READMEs, analysis documents, Confluence pages, status reports, troubleshooting write-ups, skill content, conversation summaries, ticket descriptions, post-mortems, snapshots of system state, or any document that contains concrete current-state values. Defines the "snapshot + reproducer" rule (every static value must be paired with the command/query/script that regenerates it), the single-source-of-truth rule (reference canonical homes instead of duplicating values), and fact-vs-assumption marking. Trigger keywords include writing or producing or creating or drafting a README, analysis, Confluence page, status update, summary, snapshot, current state, documenting data, posting findings, file tree, port number, version number, table count, or any concrete value that may drift over time.
messaging-framework	Core principles for technical communication such as commits, PR descriptions, branch names, and technical documentation. Use when writing or refining engineering-facing messaging and when other skills need a shared communication baseline.
relevance-first-information-design	Design or review any human- or agent-facing information surface so the consumer sees the minimum sufficient information at the right abstraction level for the current task, with clear routes to deeper detail only when relevant. Use for chat, docs, code, APIs, dashboards, charts, websites, profiles, messages, UIs, agent instructions, or other information-bearing interfaces.
security	Mandatory credential protection skill for all agents. Prevents reading, exposing, or leaking credentials, secrets, API keys, tokens, passwords, and auth-capable config files.
swe-method	Guide for working through a Jira story efficiently by separating context gathering, immutable evidence collection, codebase exploration, human-in-the-loop specification refinement, execution planning, and implementation. Use when turning a ticket into a reliable engineering workflow instead of jumping straight to code.
thoughts-to-artifact	Transform a user's raw thoughts, dictation, transcript, notes, brainstorm, or conversational explanation into a structured communication artifact while preserving meaning, examples, nuance, and recoverable detail. Use for articles, documentation, skills, READMEs, messages, briefs, posts, or similar outputs when the source structure is incidental and the output should organize ideas by meaning rather than original speaking order.

Available Commands

Generated from tracked commands/*.md files.

Command	Summary
/list-skills	Please list all your available skills with a 1 sentence description for each one. Do not return any additional fluff text before or after.

Repo Inventory

Generated from tracked manifests, scripts, commands, and skills.

.
├── .agents/
│   ├── plugins/marketplace.json
│   └── skills -> ../skills
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .claude/
│   ├── commands -> ../commands
│   └── skills -> ../skills
├── .codex-plugin/
│   └── plugin.json
├── .githooks/
│   └── pre-commit
├── .github/
│   └── workflows/
│       └── readme-generated.yml
├── commands/
│   └── list-skills.md
├── scripts/
│   ├── create-claude-command.sh
│   ├── create-shared-skill.sh
│   ├── generate-readme.py
│   ├── install-git-hooks.sh
│   ├── setup-local-links.sh
│   └── update-readme.sh
├── skills/
│   ├── engineer-agentic-ai/
│   ├── format-markdown/
│   ├── information-representation-design/
│   ├── living-artifacts/
│   ├── messaging-framework/
│   ├── relevance-first-information-design/
│   ├── security/
│   ├── swe-method/
│   └── thoughts-to-artifact/
├── pyproject.toml
└── uv.lock

Development

Use ./scripts/update-readme.sh after adding or removing tracked skills, commands, scripts, or plugin metadata.