amika-annotations
Skill301 starsChanged 11 days agoApache-2.0View on GitHub
Find and process Amika annotations (EDN #amika/<type> and XML <amika:type>) in a file, directory, or the current diff. Act on each annotation's intent, keep or delete it per type/args, respect frozen boundaries, and report everything done.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- js/AGENTS.mdAGENTS.md
- sandbox-image/AGENTS.mdAGENTS.md
- amika-cliSkill
- create-cli-release-commitSkill
- create-sdk-release-commitSkill
- distill-sessionSkill
- make-stacked-prsSkill
- naive-reader-reviewSkill
- new-specSkill
- release-commit-sandbox-imageSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
If path is given, scope to that file or directory subtree.
- Distinctive: line 35
If nothing is found, report that and stop.
- Distinctive: line 71
Look up the type in the built-in table below.
- Distinctive: line 105
If the type isn't in the table:
- Distinctive: line 107
Read the type name, content, and args and determine the intent.
- Very specific: line 118
Check boundaries first: If acting would modify a frozen symbol or a frozen-paths glob (and no override is present), do not act.
- Distinctive: line 131
When deleting an EDN annotation, remove its whole comment (all continuation lines).
- Distinctive: line 132
When "unwrapping" an XML element, remove the open/close tags but keep the (possibly transformed) content.
- Distinctive: line 135
Never leave an annotation unprocessed.
- Distinctive: line 154
Do not commit anything. Stop after reporting so the user can review the edits.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Process Amika Annotations
Find Amika annotations in the target, act on each one's intent, dispose of it (keep or delete), and report what you did. This skill is a processor, not the amikalyze enforcement engine: it does not install hooks, fire prompts, or enforce freezes. It only acts on imperative annotations and stays out of the way of the deterministic tooling.
Usage: /amika-annotations [path]
path(optional): a file or directory to process. If omitted, process the files in the current git diff / working tree (git status --porcelain, plus staged changes).
Phase 1: Find the annotations
- Resolve scope.
- If
pathis given, scope to that file or directory subtree. - Otherwise, scope to changed files:
git diff --name-only HEADplus untracked files fromgit status --porcelain. If there are no changes, say so and stop.
- If
- Grep for both markers across the scoped files:
- EDN:
#amika/[A-Za-z][\w-]* - XML:
<amika:[A-Za-z][\w-]*
- EDN:
- For each hit, read enough surrounding context to parse the full annotation (EDN expressions and XML elements can span multiple lines) and to identify what it targets.
If nothing is found, report that and stop.
Phase 2: Parse each annotation
There are two syntaxes. Parse the whole expression before acting.
EDN style: #amika/<type> ...
- The value after the type is an EDN expression. It
may be:
- a bare string:
#amika/generate "create a zod schema for the type below" - a bare map of args:
#amika/frozen { :override "computeChecksum" } - a paren form pairing a string with an options map:
#amika/rewrite ( "tighten this" { :model "claude-opus-4-7" :effort "high" } )
- a bare string:
- Multi-line: the comment prefix is repeated on every line. Strip the leading prefix
(
//,#, or*inside a block comment) from each line before reading the EDN value. - Target: by default an EDN annotation applies to the next semantic block below it (a function, class, or top-level variable; at the top of a file it applies to the whole module). If there is no following block (e.g. it sits at the end of a section, or in prose/markdown), treat it as an inline instruction to act at that point.
XML style: <amika:<type>>…</amika:<type>>
- A paired element describes the content it wraps: the text/code between the tags is the subject the annotation acts on.
- A self-closing element
<amika:<type> … />is a point annotation with no contained content; it acts at its location. - Attributes on the tag are the annotation's args/options (analogous to the EDN options map).
Phase 3: Decide behavior
Look up the type in the built-in table below. If it isn't there, infer the behavior from the type name, the content, and the args.
Built-in table
Constraint / advisory types (respected, never processed or deleted here):
| Type | What you do |
frozen | Treat the target symbol as a read-only boundary. Never let an action in this run modify a frozen symbol. If an imperative annotation's action would change it, stop that action and report the conflict instead. Leave the annotation untouched. |
frozen-paths | Same boundary rule, applied to the matching file globs. Leave untouched. |
prompt | Advisory. If your action touches a symbol carrying a #amika/prompt, read and follow its guidance while you work. Do not fire it as a turn-prompt, and leave it untouched. |
These belong to the amikalyze tooling/hooks. This skill only reads them so it doesn't trample what they protect.
Imperative types (acted on, then disposed of; default is delete after acting):
| Type | Syntax | Action | Default disposition |
generate | EDN or XML | Produce the described code/content as the target block (or inline if none). | delete |
expand | EDN or XML | Flesh out the stub/placeholder it targets into a full implementation. | delete |
rewrite | EDN or XML | Rewrite the target block (EDN) or the wrapped content (XML) per the instruction. | delete (XML: unwrap) |
edit | XML | Rewrite the wrapped content per the instruction in the annotation's prompt attribute or its own content. Equivalent to rewrite in XML form — prefer this name in prose/MDX files. | unwrap (drop tags, keep rewritten content) |
review-change | XML | The wrapped content was changed by the author and is flagged for review. Evaluate the change against the surrounding context. If it's an improvement, accept it (unwrap). If it should be reverted, note it as a conflict and leave the tags for the user to handle — you cannot recover the original automatically. | unwrap if accepted; leave tagged if rejected |
todo | EDN or XML | Perform the described task on/around the target. | delete |
note | EDN | A standing label or informational marker. Incorporate its content into the surrounding prose or action context, then delete. If it marks something that should remain (e.g. a label the user explicitly wants to keep), leave it — use judgment. | delete |
annotate | EDN or XML | A free-form question or request left for the agent (e.g. "is this still right?" or "can you make X configurable?"). Investigate the question or make the requested change, then record the result at the target. | delete |
The imperative set above is a starter. It's safe to extend this table as new types appear; until then, unknown types are handled by inference (below).
Inference for unknown types
If the type isn't in the table:
- Read the type name, content, and args and determine the intent.
- Carry out that intent on the resolved target (next block, inline, or wrapped content).
- Decide keep vs. delete yourself using the disposition rules below.
- Flag it as inferred in the report so the user can review your judgment.
Phase 4: Act and dispose
For each annotation, in file order:
- Check boundaries first. If acting would modify a
frozensymbol or afrozen-pathsglob (and no override is present), do not act. Record a boundary conflict and move on. - Act on the intent against the resolved target.
- Dispose of the annotation. Disposition is decided in this priority order:
- Per-annotation override wins.
:keep true(EDN) orkeep="true"(XML attr) forces keep;:once true/once="true"forces delete-after-acting. - Otherwise use the table default for a known imperative type.
- Otherwise (inferred type) use your judgment: an instruction that is consumed by doing it (generate, do this task) should be deleted; an annotation that remains true about the content (a description, a standing note) should be kept.
- When deleting an EDN annotation, remove its whole comment (all continuation lines). When "unwrapping" an XML element, remove the open/close tags but keep the (possibly transformed) content. Removing a self-closing tag removes just that tag.
- Per-annotation override wins.
- Never leave an annotation unprocessed. Every one found is either acted on, or recorded as a boundary conflict, or (for the respected constraint types) intentionally left in place, and every case appears in the report.
Phase 5: Report
End with a summary so the user can review the judgment calls. Use a table:
| File:line | Type | Syntax | Action taken | Disposition | Notes |
Then call out, as separate short lists:
- Inferred types: annotations whose behavior you guessed (type was not in the table).
- Boundary conflicts: actions you refused because they'd touch a frozen symbol/path.
- Left in place:
frozen/frozen-paths/promptannotations you respected.
Do not commit anything. Stop after reporting so the user can review the edits.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

