Skip to content

NetFabric/intelligentium / .agents/skills/agent-markdown-best-practices

agent-markdown-best-practices

Verified

ALWAYS use when writing or reviewing agent-facing Markdown, including project instructions, skills and references, and custom-agent definitions. Covers only their shared content style: compact executable instructions, scannable information, active language, factual precision, and token efficiency. DO NOT USE FOR: artifact-specific structure, routing descriptions, metadata schemas, or prompt-body requirements; general Markdown documents; Markdown syntax or rendering rules.

FileKindSize
SKILL.mdskill md2.3 KB
references/compact-agent-content.mdmarkdown1.5 KB

references/compact-agent-content.md

View on GitHub
# Compact Agent Content

## Content Decisions

| Need | Best Form |
| --- | --- |
| Ordered actions | Numbered workflow with concrete verbs |
| Commands or comparable facts | Table or compact bullet list |

Use prose when sequence, rationale, or nuance would be distorted by a table. Tables are a compression tool, not a default decoration.

## Precision Rules

| Concern | Rule |
| --- | --- |
| Obligation | Use `must` for requirements, `should` for recommendations, and `may` for options |
| Completeness | State the action and target; add the condition or expected result when it affects execution or completion |
| Scope | Identify which files, tasks, tools, or circumstances a rule governs |
| Exceptions | Place an exception beside the rule it modifies |
| Precedence | State which instruction wins when rules can conflict |
| Terminology | Use one consistent term for each concept |
| Criteria | Replace subjective terms such as "properly" or "as needed" with observable conditions |
| Specificity | Replace ambiguous pronouns with the command, file, tool, or result they name |
| Prohibitions | Name the required alternative or fallback when one exists |

## Compression Decisions

- Keep rationale only when it changes how an instruction should be applied.
- Keep examples only when they disambiguate syntax or behavior.
- Convert generic callouts such as "Note," "Important," and "Remember" into direct rules.
- Keep independent requirements separate when combining them would make conditions or precedence harder to parse.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall